version: "1.0.2" name: session-control description: Start, stop, and steer agentic sessions in sgai workspaces. Use when you need to launch AI agent sessions, halt running sessions, or inject steering instructions to guide the agent mid-execution without stopping it. compatibility: Requires a running sgai server with workspaces that have a GOAL.md configured.

Session Control

Sessions are the running instances of AI agents working on a workspace. Each workspace can have at most one running session.

Start a Session

Endpoint: POST /api/v1/workspaces/{name}/start

# Brainstorming mode (interactive, pauses for human input)
curl -X POST $BASE_URL/api/v1/workspaces/my-project/start \
  -H "Content-Type: application/json" \
  -d '{"auto": false}'
 
# Self-drive mode (fully autonomous, no pausing)
curl -X POST $BASE_URL/api/v1/workspaces/my-project/start \
  -H "Content-Type: application/json" \
  -d '{"auto": true}'

Request:

{"auto": true}

Response:

{
  "name": "my-project",
  "status": "running",
  "running": true,
  "message": "session started"
}

Session Modes

Notes:

• Root workspaces cannot start agentic work (only forks/standalone can)
• If already running, returns "message": "session already running"

Stop a Session

Endpoint: POST /api/v1/workspaces/{name}/stop

curl -X POST $BASE_URL/api/v1/workspaces/my-project/stop

Response:

{
  "name": "my-project",
  "status": "stopped",
  "running": false,
  "message": "session stopped"
}

If already stopped: "message": "session already stopped"

Steer an Agent

Inject a steering instruction into a running session without stopping it. The instruction is recorded in .sgai/PROJECT_MANAGEMENT.md and workflow state navigates to the coordinator.

Endpoint: POST /api/v1/workspaces/{name}/steer

curl -X POST $BASE_URL/api/v1/workspaces/my-project/steer \
  -H "Content-Type: application/json" \
  -d '{"message": "Focus on the authentication module first, skip the dashboard for now"}'

Request:

{"message": "Focus on the authentication module first, skip the dashboard for now"}

Response:

{
  "success": true,
  "message": "steering instruction added"
}

Notes:

• The steering instruction is recorded as a human steering entry internally
• Workflow state requests coordinator as the next agent so the instruction is processed next
• This works while a session is running or even when stopped; it is picked up on the next run

Check Running Status

Use the full state endpoint to check session status:

STATE=$(curl -s $BASE_URL/api/v1/state)
RUNNING=$(echo $STATE | jq '.workspaces[] | select(.name=="my-project") | .running')
AGENT=$(echo $STATE | jq -r '.workspaces[] | select(.name=="my-project") | .currentAgent')
TASK=$(echo $STATE | jq -r '.workspaces[] | select(.name=="my-project") | .task')

Key workspace state fields for session monitoring:

Open in OpenCode (Local Only)

Open the workspace in OpenCode terminal (localhost connections only).

Endpoint: POST /api/v1/workspaces/{name}/open-opencode

curl -X POST http://localhost:PORT/api/v1/workspaces/my-project/open-opencode

Response:

{
  "opened": true,
  "message": "opened in opencode"
}

Errors:

• 403 — remote connections not allowed (localhost only)
• 409 — session not running

Open in Editor

Open the workspace directory in the configured editor (VS Code, etc.).

Endpoint: POST /api/v1/workspaces/{name}/open-editor

curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor

Response:

{
  "opened": true,
  "editor": "code",
  "message": "opened in editor"
}

Open Specific Files

# Open GOAL.md in editor
curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor/goal
 
# Open PROJECT_MANAGEMENT.md in editor
curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor/project-management