Start, verify, and steer work

Use the tool's advertised input schema from tools/list. Tool descriptions and field descriptions include the startup contract; an agent does not need access to this repository to discover it. Starting work consumes workspace credits and requires member access and the usual billing, repository, and model admission.

Remote OAuth: recommended start-work toolCopy Anchor Link

1. Call uno_get_workspace to find the consented workspace and repository IDs.
2. Call uno_create_session with the complete instructions, at least one selected repository ID, and a UUID generated once for this operation. Replace the illustrative UUIDs below with the discovered IDs and your own request UUID.

{
  "objective": "Add Discovery before Spec",
  "repositoryIds": ["00000000-0000-4000-8000-000000000004"],
  "requestId": "00000000-0000-4000-8000-000000000005"
}

Uno submits objective verbatim as the first user message and queues its turn in the same creation operation, using workspace agent/model defaults. Do not send the objective again after acceptance. For explicit model, agent, branch, or attachment settings, use the advanced creation tool below.

The successful result is available as MCP structuredContent and equivalent JSON text for older clients. It preserves existing session fields and adds:

Successful new creation confirms that a turn exists. queued means accepted, not that the model has started. Retries read the persisted first-turn status instead of returning a stale execution status from the creation response.

Local stdio or advanced remote creationCopy Anchor Link

Local stdio exposes the shared v1 tools, including post_workspaces_sessions. The uno_* convenience tools are remote OAuth aliases. Discover a workspace with get_workspaces, then use get_workspaces_session_repository_options and get_workspaces_session_configuration for its repositories and available models.

Call post_workspaces_sessions with the following shape. Include body.initialConversation.message to start execution. The initial message can be a nonempty string or an object with a nonempty text field. Other optional agent/model settings remain in body.initialConversation.

{
  "workspaceId": "00000000-0000-4000-8000-000000000002",
  "body": {
    "objective": "Add Discovery before Spec",
    "repositories": [
      { "repositoryId": "00000000-0000-4000-8000-000000000004" }
    ],
    "initialConversation": {
      "message": { "text": "Add Discovery before Spec" }
    }
  },
  "idempotencyKey": "00000000-0000-4000-8000-000000000005"
}

Read data.id and data.primary_conversation_id from the response envelope. Supplying only objective intentionally creates an idle session: it records the goal and prepares an environment without submitting a message. Use that form only when preparation without execution is intended. HTTP 202 and a session's creating or ready status do not prove an agent turn is running.

Verify and follow progressCopy Anchor Link

Call get_conversations_status with the returned conversation ID:

{
  "conversationId": "00000000-0000-4000-8000-000000000006"
}

Inspect data.latest_turn_status:

• queued: Uno accepted the message and is waiting to execute it.
• running: the turn is executing; read get_conversations_activity for progress.
• completed, failed, or cancelled: the latest turn is terminal. Inspect the activity and get_conversations_messages before reporting the result or retrying work.
• null: no turn is recorded yet. Check data.activity_status; queued may indicate a pending input awaiting materialization. Read messages/activity before recovery and do not resend pending work. A prepared sandbox alone is not acceptance.

The status endpoint reports the latest turn; initial_turn_id in the convenience creation response identifies the first turn even after later follow-ups. Use get_workspaces_sessions_startup to diagnose environment preparation separately. Make bounded status reads with backoff while following progress. Report "accepted and queued" until execution is observed, and report completion only from persisted terminal state and the agent's result.

Steer work already in progressCopy Anchor Link

Both remote OAuth and local stdio expose post_conversations_steer and get_conversations_steering. Steering uses the session's conversation ID; it keeps the agent working and submits new guidance to its active turn.

1. Read get_conversations_status. Choose the entry in data.turns whose status is queued or running; its id is targetTurnId. Refresh for each new instruction rather than assuming initial_turn_id is still active.
2. Read get_conversations_steering with that conversationId. Check data.supported. If false, report that the runtime needs an upgrade; do not stop the session or substitute a duplicate message.
3. Call post_conversations_steer with this format, replacing the example IDs:

{
  "conversationId": "00000000-0000-4000-8000-000000000006",
  "body": {
    "targetTurnId": "00000000-0000-4000-8000-000000000007",
    "text": "Keep the existing task permissions and add a focused regression test."
  },
  "idempotencyKey": "00000000-0000-4000-8000-000000000008"
}

The explicit idempotencyKey is required (8–200 printable ASCII characters). Generate it once per instruction and reuse the same key and arguments after an uncertain response. Changed arguments with the same key are rejected. Optional body.imageAssetIds requires body.draftKey and ready uploads from the caller's draft. Existing workspace membership, billing and runtime capability checks apply.

HTTP 202 confirms durable acceptance, not delivery. Save data.steering.id, then call get_conversations_steering to find that ID in data.requests:

{
  "conversationId": "00000000-0000-4000-8000-000000000006"
}

Omit optional query.turnId while tracking a request by ID: remaining pending instructions can be retargeted to a continuation. A stale-target conflict means refresh status and decide which turn should receive new guidance. Replaying an already accepted request with its original key returns that request, even if the turn has since changed. If no queued or running turn exists, use post_conversations_messages (or remote uno_send_message) for an idle follow-up. Stopping is a separate action and requires an intent to stop.

Retry and recoverCopy Anchor Link

• After a timeout, retry uno_create_session with the same requestId and identical arguments. It returns the original session without another message or turn. Changed arguments with the same ID are rejected. Concurrent requests share a database startup claim; an in-progress response means retry the same request, not generate a new ID. Failed claims without a linked session can be reclaimed immediately; abandoned claims expire after ten minutes. Recovery rotates the lease and preserves the reserved session ID, so a delayed former owner cannot create another session. If that session was already inserted, inspect it before recovery. The idempotency annotation applies to this exact-argument replay, not to changing the request ID.
• For the advanced tool and message tools, supply an explicit stable idempotencyKey (or requestId for uno_send_message) on every retry. A fresh operation key can create additional work. Do not switch creation tools midway through a retry: their request keys are namespaced differently.
• Sessions created by the older broken uno_create_session remain accessible. Replaying their original request returns the existing session with execution_status: "not_started" and null initial IDs. It does not silently start historical work. Read uno_get_messages and get_conversations_status first. When explicitly recovering that work, call uno_send_message with its conversation ID, the saved objective as text, and a new UUID for the recovery message. Reuse that message UUID on retries, then verify status.
• If interrupted creation reports a session ID but cannot confirm acceptance, inspect that session before any recovery. A failed partial creation retains its claim so a retry cannot allocate another session behind the same request.