UI Shell: HTTP API For Plan Execution

by Admin 38 views
UI Shell: HTTP API for Plan Execution

Hey guys! Let's dive into the exciting world of UI Shell and how we're making plan-driven execution smoother with HTTP APIs. This article will cover the new API endpoints designed to let agents orchestrate the planner/executor loop directly through the UI. We're talking about generating plans, inspecting them, and executing nodes, all while sticking to those essential contracts we've come to rely on.

Goal

Our main goal here is to provide you with API endpoints that enable an agent to orchestrate the planner/executor loop via the UI. This means generating a plan for a work item, thoroughly inspecting it, and then executing the individual nodes. The best part? We're doing all this while still fully honoring the existing contracts that keep everything running smoothly. This ensures a seamless and reliable workflow.

Scope

Think of this as building upon the groundwork laid by Issues #59 and #60. We're taking those initial steps and expanding them with plan-centric commands. This is all about making the process more streamlined and efficient. We're introducing new capabilities that revolve around managing and executing plans effectively. This includes functionalities to generate, inspect, and execute plan nodes, providing a comprehensive suite of tools for plan-driven execution. The intention is to provide developers with more control and visibility over the planning and execution processes, enabling them to create more robust and reliable applications. Furthermore, this scope is designed to improve the overall developer experience by simplifying the interactions with the UI Shell and providing a more intuitive way to manage complex workflows.

Endpoints

Alright, let's break down the endpoints we're adding to the mix. These are the core of how you'll interact with the new plan-driven execution features. Understanding these will be key to leveraging the full potential of the UI Shell.

POST /api/sessions/{id}/plan/generate

  • Endpoint: POST /api/sessions/{id}/plan/generate
  • Body: { workItemId?, force?: bool }
  • Behavior: This endpoint is your go-to for kicking off the planner agent for a specific session. If the automatic planning isn't already in motion, this will get the ball rolling. You can specify a workItemId to generate a plan for a particular work item, and the force parameter lets you override any existing plans. The request body accepts two optional parameters: workItemId, which specifies the identifier of the work item for which the plan should be generated, and force, a boolean value that, when set to true, forces the generation of a new plan even if one already exists. This endpoint is crucial for initiating the planning process and ensuring that the most up-to-date plan is available for execution. The use of these parameters allows for flexible and controlled plan generation, catering to different scenarios and requirements. The endpoint ensures that the planning process is initiated correctly and efficiently, setting the stage for subsequent execution steps.
  • Returns: A PlanUpdated summary in the format: { planId, nodeCount, nodes: [{ nodeId, title, dependsOn[], suggestedBranch, tags[] }] }. This summary gives you a snapshot of the generated plan, including its ID, the number of nodes, and details about each node (ID, title, dependencies, suggested branch, and tags). The response provides a structured overview of the newly generated plan, enabling developers to quickly understand its key characteristics and components. This detailed summary is essential for further analysis and decision-making, such as identifying specific nodes for execution or evaluating the overall plan structure. The returned data facilitates informed actions and ensures that the execution process aligns with the intended goals.

GET /api/sessions/{id}/plan

  • Endpoint: GET /api/sessions/{id}/plan
  • Returns: This endpoint retrieves the current TaskPlan. The structure is the same as the PlanUpdated summary: { planId, nodeCount, nodes: [{ nodeId, title, dependsOn[], suggestedBranch, tags[] }] }. Think of it as a way to get the current state of the plan for a given session. This endpoint provides a read-only view of the current task plan, allowing developers to inspect its properties and status. The data returned includes the plan ID, the total number of nodes in the plan, and a detailed description of each node, including its unique identifier, title, dependencies, suggested branch, and any associated tags. This information is crucial for understanding the structure and dependencies of the plan, and it can be used to make informed decisions about how to proceed with the execution process. The endpoint ensures that developers have access to the latest plan information, enabling them to monitor progress and identify potential issues.

POST /api/sessions/{id}/plan/execute-node

  • Endpoint: POST /api/sessions/{id}/plan/execute-node
  • Body: { nodeId }
  • Behavior: This is where the magic happens! This endpoint executes a specific node within the plan using the executor. It essentially maps to one or more orchestrator commands, triggering the necessary actions to complete the node. The nodeId parameter is crucial for specifying which node to execute. Upon receiving the request, the executor translates the node execution into corresponding orchestrator commands, ensuring that the necessary steps are taken to complete the node's task. This process is designed to be seamless, allowing developers to focus on managing the overall plan rather than the individual command executions. The endpoint also takes care of any required dependencies and ensures that the node is executed in the correct context.
  • Returns: An acknowledgement and a correlation ID for tracking the execution. The correlation ID is super helpful for monitoring the progress and status of the executed node. The acknowledgement confirms that the execution request has been received and processed, while the correlation ID provides a unique identifier for tracking the execution's progress. This allows developers to monitor the execution status, identify any potential issues, and correlate events related to the node execution. The returned information is essential for maintaining visibility and control over the execution process, ensuring that everything runs smoothly and as expected.

Safety

It's crucial to remember that we're still keeping things safe and sound. There are still no Push/Jira transitions implemented. This means that execution will be either a dry-run or limited to local operations. The only exception is if you have LivePolicy enabled along with the necessary environment flags. All actions taken through these endpoints will be diligently logged as remote-control operations. This ensures transparency and allows for auditing and debugging. The safety measures in place prevent accidental or unauthorized modifications to external systems, keeping the execution environment secure and predictable. The logging of all actions provides a comprehensive record of activities, facilitating troubleshooting and compliance with security policies.

Done When

We'll know we've nailed it when a script can successfully:

  1. Create a session from a work item.
  2. Generate a plan for that session.
  3. Execute a node within the plan and observe the corresponding events and artifacts. This entire process needs to be automated and reliable. This is our ultimate test to ensure that the APIs are working as expected and provide the necessary functionality for plan-driven execution. The ability to create a session, generate a plan, and execute nodes demonstrates the end-to-end functionality of the new APIs, ensuring they meet the requirements for orchestrating the planner/executor loop. The observation of corresponding events and artifacts confirms that the execution is producing the desired outcomes and can be tracked effectively.

So there you have it! We're building a robust system to manage the planning and execution of tasks in the UI Shell. These new HTTP APIs will give you the power to orchestrate complex workflows with ease. Stay tuned for more updates! Remember, the goal is to give you more control, better visibility, and a smoother experience overall. Let's make this happen!