better-dsh 0.0.0 → 0.2.3

package/docs/v0.1.8d_artifacts/tools-sdk.python.txt

@@ -0,0 +1,592 @@
+## Writing code for run_code
+
+`run_code` takes two required arguments: `code` — the body of an async Python function (top-level `await` and `return` both work) — and `description`, a short summary of what the program does. At run time exactly two of the names declared below are bound: `tools` and `ToolCallError`. Everything else is a STATIC STUB describing argument and return types — in particular the `TypedDict` classes do NOT exist at run time, so build arguments as plain `dict`/`list` JSON values: `await tools.name({"field": 1})`, never `FooArgs(field=1)`, which raises `NameError`. Inside the program:
+
+- Call tools as `await tools.name(args)` — subscript access for exotic, reserved, or underscore-leading names: `await tools["my-tool"](args)`. Every call resolves to the tool's typed canonical JSON value (each method's return type below). Tool arguments must be lossless JSON.
+- A FAILED tool call raises `ToolCallError`, whose `toolName` identifies the failed tool and whose message is human-readable — wrap in `try/except` to handle and continue.
+- Independent read-only calls MAY overlap under `asyncio.gather` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.
+- Emit the run's answer with `print(...)` and/or a top-level `return <value>`; the returned value must be lossless JSON. Only what you print and return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+
+The available tools:
+
+```python
+from typing import Any, Literal, NotRequired, Protocol, TypedDict
+
+class ToolCallError(Exception):
+    toolName: str
+
+class AskUserQuestionArgsQuestionsOptions(TypedDict):
+    # Short user-facing option label.
+    label: str
+    # One sentence explaining the tradeoff or impact.
+    description: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class AskUserQuestionArgsQuestions(TypedDict):
+    # Stable id for this question; echoed in the answer.
+    id: str
+    # The specific question to ask the user.
+    question: str
+    # Optional short heading for the question, such as "Confirm" or "Choose Mode".
+    header: NotRequired[str]
+    # Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label.
+    options: NotRequired[list[AskUserQuestionArgsQuestionsOptions]]
+    # Whether the user may select more than one option. Defaults to false.
+    multi_select: NotRequired[bool]
+    # Additional keys beyond those declared are allowed.
+
+class AskUserQuestionArgs(TypedDict):
+    # Questions to ask the user before continuing.
+    questions: list[AskUserQuestionArgsQuestions]
+    # Additional keys beyond those declared are allowed.
+
+class AskUserQuestionOutputAnswers(TypedDict):
+    id: str
+    selected: list[str]
+    custom: NotRequired[str]
+
+class AskUserQuestionOutput(TypedDict):
+    answers: list[AskUserQuestionOutputAnswers]
+
+class BashArgs(TypedDict):
+    # The bash command to execute.
+    command: str
+    # Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: "ls" → "List files in current directory"; "git status" → "Show working tree status"; "npm install" → "Install package dependencies".
+    description: str
+    # Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.
+    timeoutMs: NotRequired[float]
+    # Working directory for this command. Defaults to the session workspace; a relative path is resolved against it.
+    workdir: NotRequired[str]
+    # Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies.
+    run_in_background: NotRequired[bool]
+    # The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.
+    sandbox_permissions: NotRequired[Literal["workspace-write", "danger-full-access"]]
+    # Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access.
+    justification: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class BashOutput1(TypedDict):
+    kind: Literal["background"]
+    jobId: str
+
+class BashOutput2Stdout(TypedDict):
+    text: str
+    truncated: bool
+    spillPath: NotRequired[str]
+
+class BashOutput2Stderr(TypedDict):
+    text: str
+    truncated: bool
+    spillPath: NotRequired[str]
+
+class BashOutput2Sandbox(TypedDict):
+    mode: str
+    denied: bool
+    enforcement: NotRequired[str]
+    runnerFailed: NotRequired[bool]
+
+class BashOutput2(TypedDict):
+    kind: Literal["foreground"]
+    exitCode: int | None
+    signal: str | None
+    timedOut: bool
+    aborted: bool
+    timeoutMs: float
+    stdout: BashOutput2Stdout
+    stderr: BashOutput2Stderr
+    sandbox: NotRequired[BashOutput2Sandbox]
+
+class CreateGoalArgs(TypedDict):
+    # The concrete completion objective inferred from the direct human request.
+    objective: str
+    # Optional positive safe-integer limit on automatic continuation rounds.
+    max_goal_rounds: NotRequired[float]
+    # Additional keys beyond those declared are allowed.
+
+class CreateGoalOutput1(TypedDict):
+    goal: None
+
+class CreateGoalOutput2GoalBlockedReason(TypedDict):
+    code: str
+    message: str
+
+class CreateGoalOutput2Goal(TypedDict):
+    id: str
+    revision: int
+    objective: str
+    phase: Literal["active", "paused", "blocked", "complete"]
+    roundsStarted: int
+    maxGoalRounds: int
+    blockedReason: NotRequired[CreateGoalOutput2GoalBlockedReason]
+
+class CreateGoalOutput2(TypedDict):
+    goal: CreateGoalOutput2Goal
+    activation: Literal["armed", "disarmed"]
+
+class EditArgs(TypedDict):
+    # Path to edit, resolved by the filesystem backend.
+    file_path: str
+    # Literal text to replace. Must match exactly.
+    old_string: str
+    # Literal replacement text. Use an empty string to delete the match.
+    new_string: str
+    # Replace all matches. Defaults to false; when false, old_string must appear exactly once.
+    replace_all: NotRequired[bool]
+    # The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.
+    sandbox_permissions: NotRequired[Literal["workspace-write", "danger-full-access"]]
+    # Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access.
+    justification: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class EditOutput(TypedDict):
+    path: str
+    before: str
+    after: str
+
+class ExitPlanModeArgs(TypedDict):
+    # The complete plan, as markdown, starting with a # heading that names it.
+    plan: str
+    # Additional keys beyond those declared are allowed.
+
+class ExitPlanModeOutput(TypedDict):
+    approved: Literal[True]
+
+class GetGoalOutput1(TypedDict):
+    goal: None
+
+class GetGoalOutput2GoalBlockedReason(TypedDict):
+    code: str
+    message: str
+
+class GetGoalOutput2Goal(TypedDict):
+    id: str
+    revision: int
+    objective: str
+    phase: Literal["active", "paused", "blocked", "complete"]
+    roundsStarted: int
+    maxGoalRounds: int
+    blockedReason: NotRequired[GetGoalOutput2GoalBlockedReason]
+
+class GetGoalOutput2(TypedDict):
+    goal: GetGoalOutput2Goal
+    activation: Literal["armed", "disarmed"]
+
+class GlobArgs(TypedDict):
+    # Glob pattern to match file paths against (e.g. "**/*.ts", "src/**/*.test.js"). A pattern with no "/" matches the basename at any depth, so "*" and "*.ts" both search the whole tree; include a separator to anchor the depth.
+    pattern: str
+    # Directory to search in. Defaults to the session workspace; a relative path resolves against it.
+    path: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class GlobOutput(TypedDict):
+    root: str
+    paths: list[str]
+
+class GrepArgs(TypedDict):
+    # Regular expression to search for (ripgrep syntax).
+    pattern: str
+    # File or directory to search. Defaults to the session workspace; a relative path resolves against it.
+    path: NotRequired[str]
+    # One glob filter for which files to search (e.g. "*.ts", "*.{js,jsx}"). Not a list; negation is not supported.
+    include: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class GrepOutputMatches(TypedDict):
+    path: str
+    lineNumber: int
+    line: str
+
+class GrepOutput(TypedDict):
+    matches: list[GrepOutputMatches]
+
+class InterruptAgentArgs(TypedDict):
+    # The agent id of the running agent to interrupt.
+    agent_id: str
+    # Additional keys beyond those declared are allowed.
+
+class InterruptAgentOutput(TypedDict):
+    accepted: bool
+
+class JobKillArgs(TypedDict):
+    # Job id returned by the tool that started the background work.
+    job_id: str
+    # Optional short reason, recorded in the log and forwarded to the job.
+    reason: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class JobKillOutputJob(TypedDict):
+    id: str
+    kind: str
+    label: str
+    status: Literal["running", "stopping", "completed", "killed", "failed"]
+    detail: NotRequired[str]
+    startedAt: int
+    finishedAt: NotRequired[int]
+
+class JobKillOutput(TypedDict):
+    outcome: Literal["cancellation-requested", "already-finished"]
+    job: JobKillOutputJob
+
+class JobListOutput(TypedDict):
+    id: str
+    kind: str
+    label: str
+    status: Literal["running", "stopping", "completed", "killed", "failed"]
+    detail: NotRequired[str]
+    startedAt: int
+    finishedAt: NotRequired[int]
+
+class JobOutputArgs(TypedDict):
+    # Job id returned by the tool that started the background work.
+    job_id: str
+    # Block until the job reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the job alive.
+    wait: NotRequired[bool]
+    # Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum.
+    timeout_ms: NotRequired[float]
+    # Additional keys beyond those declared are allowed.
+
+class JobOutputOutputJob(TypedDict):
+    id: str
+    kind: str
+    label: str
+    status: Literal["running", "stopping", "completed", "killed", "failed"]
+    detail: NotRequired[str]
+    startedAt: int
+    finishedAt: NotRequired[int]
+
+class JobOutputOutput(TypedDict):
+    text: str
+    job: JobOutputOutputJob
+
+class ListAgentsArgs(TypedDict):
+    # children (default) lists direct children only; descendants walks the complete tree below you.
+    scope: NotRequired[Literal["children", "descendants"]]
+    # Additional keys beyond those declared are allowed.
+
+class ListAgentsOutput1(TypedDict):
+    kind: Literal["child"]
+    id: str
+    label: str
+    status: Literal["running", "idle", "ready"]
+    parent: NotRequired[str]
+    depth: NotRequired[float]
+
+class ListAgentsOutput2(TypedDict):
+    kind: Literal["diagnostic"]
+    id: str
+    reason: Literal["corrupt", "unsupported", "unavailable"]
+    parent: NotRequired[str]
+    depth: NotRequired[float]
+
+class RalphArgs(TypedDict):
+    # The immutable completion objective for every fresh Ralph round.
+    objective: str
+    # Optional positive safe-integer round cap, bounded by the deployment ceiling.
+    maxRounds: NotRequired[float]
+    # Additional keys beyond those declared are allowed.
+
+class RalphOutput(TypedDict):
+    runId: str
+    agentsStarted: int
+    result: Any
+
+class ReadArgs(TypedDict):
+    # Path to read, resolved by the filesystem backend.
+    file_path: str
+    # 1-based first line to return. Defaults to 1.
+    offset: NotRequired[float]
+    # Maximum number of lines to return. Defaults to 2000.
+    limit: NotRequired[float]
+    # Additional keys beyond those declared are allowed.
+
+class ReadOutputLines(TypedDict):
+    number: int
+    text: str
+
+class ReadOutput(TypedDict):
+    path: str
+    offset: int
+    lines: list[ReadOutputLines]
+    totalLines: int
+
+class ReadImageArgs(TypedDict):
+    # Path to the image file, resolved by the filesystem backend.
+    file_path: str
+    # Additional keys beyond those declared are allowed.
+
+class ReadImageOutputImageOriginalDimensions(TypedDict):
+    width: int
+    height: int
+
+class ReadImageOutputImage(TypedDict):
+    attachmentId: str
+    mediaType: Literal["image/png", "image/jpeg", "image/webp", "image/gif"]
+    bytes: int
+    width: int
+    height: int
+    name: NotRequired[str]
+    originalDimensions: NotRequired[ReadImageOutputImageOriginalDimensions]
+
+class ReadImageOutput(TypedDict):
+    path: str
+    image: ReadImageOutputImage
+
+class SendMessageArgs(TypedDict):
+    # The subagent id returned when the background subagent was started.
+    subagent_id: str
+    # The message to deliver to the subagent.
+    message: str
+    # Additional keys beyond those declared are allowed.
+
+class SendMessageOutput(TypedDict):
+    messageId: str
+
+class SkillArgs(TypedDict):
+    # The exact skill name from the available skills list.
+    name: str
+    # Additional keys beyond those declared are allowed.
+
+class SkillOutputResourceBase1(TypedDict):
+    kind: Literal["directory"]
+    path: str
+
+class SkillOutputResourceBase2(TypedDict):
+    kind: Literal["url"]
+    url: str
+
+class SkillOutputResourceBase3(TypedDict):
+    kind: Literal["opaque"]
+    description: str
+
+class SkillOutput(TypedDict):
+    name: str
+    provider: str
+    resourceBase: NotRequired[SkillOutputResourceBase1 | SkillOutputResourceBase2 | SkillOutputResourceBase3]
+    content: str
+
+class SubagentArgs(TypedDict):
+    # A short (3-5 word) description of the delegated task, for display.
+    description: str
+    # The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs.
+    prompt: str
+    # Whether to run in the background and return a durable subagent id immediately. Defaults to true. Set false to wait for the result when your next action depends on it.
+    run_in_background: NotRequired[bool]
+    # Additional keys beyond those declared are allowed.
+
+class SubagentOutput1(TypedDict):
+    kind: Literal["background"]
+    jobId: str
+
+class SubagentOutput2(TypedDict):
+    kind: Literal["continuable"]
+    subagentId: str
+
+class SubagentOutput3(TypedDict):
+    kind: Literal["foreground"]
+    runId: str
+    output: list[Any]
+
+class SubagentForkArgs(TypedDict):
+    # A short (3-5 word) description of the delegated task, for display.
+    description: str
+    # The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new.
+    prompt: str
+    # Whether to run in the background and return a durable subagent id immediately. Defaults to true. Set false to wait for the result when your next action depends on it.
+    run_in_background: NotRequired[bool]
+    # Additional keys beyond those declared are allowed.
+
+class SubagentForkOutput1(TypedDict):
+    kind: Literal["background"]
+    jobId: str
+
+class SubagentForkOutput2(TypedDict):
+    kind: Literal["continuable"]
+    subagentId: str
+
+class SubagentForkOutput3(TypedDict):
+    kind: Literal["foreground"]
+    runId: str
+    output: list[Any]
+
+class TodoWriteArgsTodos(TypedDict):
+    # What the task is — a short imperative line.
+    content: str
+    # pending (not started) | in_progress (now) | completed (done).
+    status: Literal["pending", "in_progress", "completed"]
+
+class TodoWriteArgs(TypedDict):
+    # The COMPLETE task list, replacing any previous list.
+    todos: list[TodoWriteArgsTodos]
+    # Additional keys beyond those declared are allowed.
+
+class TodoWriteOutputTodos(TypedDict):
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+
+class TodoWriteOutputCounts(TypedDict):
+    pending: int
+    inProgress: int
+    completed: int
+
+class TodoWriteOutput(TypedDict):
+    todos: list[TodoWriteOutputTodos]
+    counts: TodoWriteOutputCounts
+
+class UpdateGoalArgs(TypedDict):
+    # Exact id returned by get_goal.
+    goal_id: str
+    # Exact positive revision returned by get_goal.
+    revision: float
+    # edit | pause | resume | complete | blocked
+    action: Literal["edit", "pause", "resume", "complete", "blocked"]
+    # Replacement objective; valid only with action edit.
+    objective: NotRequired[str]
+    # Replacement cap; valid only with action edit.
+    max_goal_rounds: NotRequired[float]
+    # Concrete blocking condition; required only with action blocked.
+    blocked_reason: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class UpdateGoalOutput1(TypedDict):
+    goal: None
+
+class UpdateGoalOutput2GoalBlockedReason(TypedDict):
+    code: str
+    message: str
+
+class UpdateGoalOutput2Goal(TypedDict):
+    id: str
+    revision: int
+    objective: str
+    phase: Literal["active", "paused", "blocked", "complete"]
+    roundsStarted: int
+    maxGoalRounds: int
+    blockedReason: NotRequired[UpdateGoalOutput2GoalBlockedReason]
+
+class UpdateGoalOutput2(TypedDict):
+    goal: UpdateGoalOutput2Goal
+    activation: Literal["armed", "disarmed"]
+
+class WebSearchArgs(TypedDict):
+    # Required search queries; accepts 1–4 items and merges their results.
+    queries: list[str]
+    # Additional keys beyond those declared are allowed.
+
+class WebSearchOutputSources(TypedDict):
+    url: str
+    title: NotRequired[str]
+    snippet: NotRequired[str]
+    publishedAt: NotRequired[str]
+
+class WebSearchOutput(TypedDict):
+    content: NotRequired[str]
+    sources: list[WebSearchOutputSources]
+    truncated: bool
+
+class WorkflowArgsMetaPhases(TypedDict):
+    # The phase title phase() calls match by exact string.
+    title: str
+    # Optional one-line description of the phase.
+    detail: NotRequired[str]
+    # Optional provider override this phase is expected to use.
+    provider: NotRequired[str]
+    # Optional model override this phase is expected to use.
+    model: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class WorkflowArgsMeta(TypedDict):
+    # Short kebab-case workflow name.
+    name: str
+    # One-line description of what the workflow does.
+    description: str
+    # Optional guidance on when this workflow applies.
+    whenToUse: NotRequired[str]
+    # Optional phase declarations matched by phase() calls.
+    phases: NotRequired[list[WorkflowArgsMetaPhases]]
+    # Additional keys beyond those declared are allowed.
+
+class WorkflowArgs(TypedDict):
+    # The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`).
+    script: str
+    # The workflow identity block (plain JSON — never code).
+    meta: WorkflowArgsMeta
+    # Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}).
+    args: NotRequired[dict[str, Any]]
+    # Additional keys beyond those declared are allowed.
+
+class WorkflowOutput(TypedDict):
+    runId: str
+    agentsStarted: int
+    result: Any
+
+class WriteArgs(TypedDict):
+    # Path to write, resolved by the filesystem backend.
+    file_path: str
+    # Full UTF-8 text content to write.
+    content: str
+    # The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.
+    sandbox_permissions: NotRequired[Literal["workspace-write", "danger-full-access"]]
+    # Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access.
+    justification: NotRequired[str]
+    # Additional keys beyond those declared are allowed.
+
+class WriteOutput(TypedDict):
+    path: str
+    operation: Literal["create", "update"]
+    before: str | None
+    after: str
+
+class Tools(Protocol):
+    async def ask_user_question(self, args: AskUserQuestionArgs) -> AskUserQuestionOutput:
+        """Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer."""
+    async def bash(self, args: BashArgs) -> BashOutput1 | BashOutput2:
+        """Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later."""
+    async def create_goal(self, args: CreateGoalArgs) -> CreateGoalOutput1 | CreateGoalOutput2:
+        """Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority."""
+    async def edit(self, args: EditArgs) -> EditOutput:
+        """Edit an existing UTF-8 text file by replacing literal text."""
+    async def exit_plan_mode(self, args: ExitPlanModeArgs) -> ExitPlanModeOutput:
+        """Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again."""
+    async def get_goal(self, args: dict[str, Any]) -> GetGoalOutput1 | GetGoalOutput2:
+        """Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal."""
+    async def glob(self, args: GlobArgs) -> GlobOutput:
+        """Find files whose paths match a glob pattern. Returns matching file paths — never directories — including hidden and ignored files (VCS metadata directories are excluded). Up to 100 paths come back in modification-time order; a larger result returns the first 100 paths in modification-time order, says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries."""
+    async def grep(self, args: GrepArgs) -> GrepOutput:
+        """Search file contents with a ripgrep regular expression. Returns matching lines with line numbers, grouped by file. Returns the first 250 matches inline; a capped result reports where the complete match list was saved. Use read on a matched file for surrounding context."""
+    async def interrupt_agent(self, args: InterruptAgentArgs) -> InterruptAgentOutput:
+        """Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op."""
+    async def job_kill(self, args: JobKillArgs) -> JobKillOutput:
+        """Request cancellation of a running background job by job id. Returns immediately; the job settles as killed once its work actually stops."""
+    async def job_list(self, args: dict[str, Any]) -> list[JobListOutput]:
+        """List your background jobs (running and finished) with their ids, kinds, and statuses."""
+    async def job_output(self, args: JobOutputArgs) -> JobOutputOutput:
+        """Read a background job. Stream jobs return only output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap."""
+    async def list_agents(self, args: ListAgentsArgs) -> list[ListAgentsOutput1 | ListAgentsOutput2]:
+        """List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and ready means it exists only in storage — resumable, not terminal, and not a result waiting to be collected; a `send_message` starts a new turn on the same conversation, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only."""
+    async def ralph(self, args: RalphArgs) -> RalphOutput:
+        """Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools."""
+    async def read(self, args: ReadArgs) -> ReadOutput:
+        """Read a UTF-8 text file and return line-numbered content."""
+    async def read_image(self, args: ReadImageArgs) -> ReadImageOutput:
+        """Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input."""
+    async def send_message(self, args: SendMessageArgs) -> SendMessageOutput:
+        """Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered."""
+    async def skill(self, args: SkillArgs) -> SkillOutput:
+        """Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill."""
+    async def subagent(self, args: SubagentArgs) -> SubagentOutput1 | SubagentOutput2 | SubagentOutput3:
+        """Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This tool runs in the background by default, immediately returns a durable subagent id, and keeps the child conversation available for later turns. When that run settles, the runtime sends the parent a notice containing its outcome and any final assistant message; `send_message` starts a later turn in the same child conversation. Set `run_in_background: false` only when your next action depends on receiving the result."""
+    async def subagent_fork(self, args: SubagentForkArgs) -> SubagentForkOutput1 | SubagentForkOutput2 | SubagentForkOutput3:
+        """Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn). Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive its result, not its intermediate steps. This tool runs in the background by default, immediately returns a durable subagent id, and keeps the child conversation available for later turns. When that run settles, the runtime sends the parent a notice containing its outcome and any final assistant message; `send_message` starts a later turn in the same child conversation. Set `run_in_background: false` only when your next action depends on receiving the result."""
+    async def todo_write(self, args: TodoWriteArgs) -> TodoWriteOutput:
+        """Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished)."""
+    async def update_goal(self, args: UpdateGoalArgs) -> UpdateGoalOutput1 | UpdateGoalOutput2:
+        """Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason."""
+    async def web_search(self, args: WebSearchArgs) -> WebSearchOutput:
+        """Search the web for current information. Provide 1–4 queries in the required queries array. Returns an optional summary answer and a list of source URLs."""
+    async def workflow(self, args: WorkflowArgs) -> WorkflowOutput:
+        """Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes."""
+    async def write(self, args: WriteArgs) -> WriteOutput:
+        """Create or fully replace a UTF-8 text file."""
+
+tools: Tools
+```