csf-agent

One agent recipe, one inspectable assignment

This executable example prepares a named worker and submits its task through an existing Workbench. It uses CSF's generated contracts and the Workbench's generated client. It starts no server, backend loop or scheduler.

%% Generated from csf/compiler/language/architecture.csf; do not edit.
%% Documentation model only; status labels do not establish runtime verification.
flowchart LR
  classDef csf_existing fill:#0F766E,stroke:#115E59,stroke-width:2px,color:#FFFFFF;
  classDef csf_planned fill:#FEF3C7,stroke:#B45309,stroke-width:2px,color:#78350F;
  n_recipe["Agent definition and assignment file (existing)"]:::csf_existing
  n_prepare["PrepareAgentAssignment (existing)"]:::csf_existing
  n_plan["Prepared assignment (existing)"]:::csf_existing
  n_requests["Generated Workbench requests (existing)"]:::csf_existing
  n_session["Session and worktree records (existing)"]:::csf_existing
  n_copilot["Copilot brain provider (existing)"]:::csf_existing
  n_receipt["Assignment receipt (existing)"]:::csf_existing
  n_recipe --> n_prepare
  n_prepare --> n_plan
  n_plan --> n_requests
  n_requests --> n_session
  n_session --> n_copilot
  n_session --> n_receipt
  linkStyle 0 stroke:#0F766E,stroke-width:2px
  linkStyle 1 stroke:#0F766E,stroke-width:2px
  linkStyle 2 stroke:#0F766E,stroke-width:2px
  linkStyle 3 stroke:#0F766E,stroke-width:2px
  linkStyle 4 stroke:#0F766E,stroke-width:2px
  linkStyle 5 stroke:#0F766E,stroke-width:2px

Run

From the public archive or repository root containing go.mod:

go run ./examples/csf-agent --recipe ./examples/csf-agent/agent.json

The default prints a plan and performs no network requests. Before submitting, copy the recipe, choose a fresh nonzero UUID for assignment_id, and replace the example ticket, model and repository identifiers with your actual values. Model and repository catalogs are the existing /v1/models and /v1/repositories operations. The example identifiers are placeholders.

go run ./examples/csf-agent --recipe ./my-assignment.json \
  --workbench http://127.0.0.1:14111 --submit > assignment-receipt.json

--submit creates a worktree and session and submits the task. The JSON receipt contains the complete prepared recipe, its fingerprints and a clickable session_url. turn_id proves prompt acceptance was acknowledged; inspect the session's actual turn state and evidence before claiming task completion. Existing Workbench metrics, transcript, permissions and usage apply.

Retain both files. Replay the same recipe to recover the existing session and turn through Workbench's durable idempotency records. Changing already submitted content under the same assignment ID produces a conflict. A new assignment needs a new ID; a changed reusable definition needs a new revision. The scaffold fingerprints definitions but has no registry enforcing revision uniqueness across separate assignments.

If session creation succeeds but prompt submission fails, the example emits a partial receipt and exits nonzero. An empty turn_id means acceptance was not confirmed, including an ambiguous network failure. Retry with the original recipe rather than generating new keys. Restoring links does not resume an interrupted tool call or establish that it succeeded.

Mechanical extension path

Run generation from the public module root. The archive includes these generators and their inputs; the shell generators require Docker, and the CSF API generator also requires Python 3. New behavior still requires implementation; code generation supplies the contracts and transport plumbing. Liquid field predicates are enforced by the Go service; not every predicate is represented in the generated MCP JSON Schema.

Embed without another process boundary

plan, err := csf.PrepareAgentAssignment(recipe)
// Handle err; retain plan with the assignment's evidence.
requests, err := csf.NewAgentWorkbenchRequests(plan)
// Handle err. Pass requests.Session to the existing adapter's CreateSession
// and requests.Prompt to SubmitPrompt, with its returned session ID.

The standalone example hands the plan to a brain: csf.SubmitAgentAssignment asks an IAgentAssignmentBrain (the ipc/model contract) to propose one agent turn. Production wires copilot.NewCopilotBrain over the adapter's generated client because its Workbench already runs elsewhere; specs wire stub.NewCannedBrain and need no model. A proposal is never permission to execute: the turn's tool calls still wait on the session's permission policy. A host embedding both capabilities can call the adapter directly. Registering the csf.Service exposes PrepareAgentAssignment through the existing HTTP and MCP handlers; no additional listener is required.

Ownership in this slice

Acceptance covers the shipped recipe, generated MCP/HTTP preparation, Workbench storage, conflicting retries and host reconstruction with generated mocks at the Copilot and filesystem/process boundaries. It does not claim a live model completed a review.