diff --git a/README.md b/README.md index bf8a45675..72e846d3b 100644 --- a/README.md +++ b/README.md @@ -393,7 +393,7 @@ Headless browser automation with 14 stealth scripts to evade bot detection: - **Selector flexibility**: CSS, `aria/`, `text/`, `xpath/`, `pierce/` query handlers for Shadow DOM piercing - **Reader mode**: `tab.extract()` uses Mozilla Readability for clean article extraction - **Headless/visible toggle**: Switch modes at runtime via `/browser` command or `browser.headless` setting -- **One-command Chromium fetch**: `omp setup browser` downloads a known-good Chromium; prebuilt binaries embed the tab worker entry via `with { type: "file" }` so single-file binaries no longer fail with `Timed out initializing browser tab worker` +- **One-command Chromium fetch**: the browser tool auto-downloads a known-good Chromium on first use; prebuilt binaries embed the tab worker entry via `with { type: "file" }` so single-file binaries no longer fail with `Timed out initializing browser tab worker` - **NixOS support**: Automatically detects NixOS (`/etc/NIXOS`) and resolves a system Chromium since Puppeteer's bundled binary cannot run on a non-FHS system ### + Cursor Provider @@ -412,7 +412,7 @@ Distribute load across multiple API keys: - **Round-robin distribution**: Automatically cycles through credentials per session - **Usage-aware selection**: For OpenAI Codex, checks account limits before credential selection - **Automatic fallback**: Switches credentials mid-session when rate limits are hit -- **Consistent hashing**: FNV-1a hashing ensures stable credential assignment per session +- **Consistent hashing**: `Bun.hash.xxHash32` over the session id ensures stable credential assignment per session - **Disable events**: Extensions can subscribe to `credential_disabled` to react when an OAuth token is soft-disabled (e.g. `invalid_grant`) without regex-matching error messages ### + Image Generation @@ -502,7 +502,7 @@ Supported platforms: `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, ` - **`omp acp` subcommand**: Run as an Agent Client Protocol server over stdio - **`omp config` subcommand**: Manage settings from CLI (`list`, `get`, `set`, `reset`, `path`) -- **`omp setup` subcommand**: Install optional dependencies (`omp setup python`, `omp setup browser`) +- **`omp setup` subcommand**: Install optional dependencies (`omp setup python`, `omp setup stt`) - **`omp stats` subcommand**: Local observability dashboard for AI usage (requests, cost, cache rate, tokens/s) with input/output token totals - **`omp jupyter` was removed**: the Python `eval` backend now runs as a subprocess (no Jupyter dependency) - **`xhigh` thinking level**: Extended reasoning for Anthropic models with increased token budgets @@ -521,7 +521,7 @@ Supported platforms: `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, ` - **Per-command PTY control**: `bash` tool supports `pty: true` for commands requiring a real terminal (sudo, ssh) - **@file auto-read**: Type `@path/to/file` in prompts to inject file contents inline - **AST tools**: `ast_grep` and `ast_edit` for syntax-aware code search and codemods via ast-grep -- **Plan mode**: ExitPlanMode offers three approvals — execute (purge), keep full transcript, or compact context (re-anchors plan on a fresh cache breakpoint) +- **Plan mode**: approval surface offers three outcomes — execute (purge), keep full transcript, or compact context (re-anchors plan on a fresh cache breakpoint). Completion routes through the existing `resolve` tool with `action: "apply"` and an `extra: { title }` payload - **`/btw` ephemeral turns**: One-shot model query that doesn't pollute the session transcript - **Sampling controls**: `topP`, `topK`, `minP`, `presencePenalty`, `repetitionPenalty` settings for fine-grained model tuning @@ -531,7 +531,7 @@ Supported platforms: `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, ` ### Via Bun (recommended) -Requires [Bun](https://bun.sh) **>= 1.3.7**: +Requires [Bun](https://bun.sh) **>= 1.3.14**: ```bash bun install -g @oh-my-pi/pi-coding-agent diff --git a/docs/environment-variables.md b/docs/environment-variables.md index be2089244..518fcc005 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -278,7 +278,6 @@ Extra conditional behavior: | `PI_TASK_MAX_OUTPUT_BYTES` | Max captured output bytes per subagent (default `500000`) | | `PI_TASK_MAX_OUTPUT_LINES` | Max captured output lines per subagent (default `5000`) | | `PI_TIMING` | If `1`, enables startup/tool timing instrumentation logs | -| `PI_DEBUG_STARTUP` | Enables startup stage debug prints to stderr in multiple startup paths | | `PI_PACKAGE_DIR` | Overrides package asset base dir resolution (docs/examples/changelog path lookup) | | `PI_DISABLE_LSPMUX` | If `1`, disables lspmux detection/integration and forces direct LSP server spawning | | `PI_RPC_EMIT_TITLE` | Boolean-like flag enabling title events in RPC mode | diff --git a/docs/python-repl.md b/docs/python-repl.md index 672a02775..e9a35c539 100644 --- a/docs/python-repl.md +++ b/docs/python-repl.md @@ -238,4 +238,3 @@ Output is streamed through `OutputSink` and may be persisted to artifact storage - `PI_PYTHON_SKIP_CHECK=1` — bypass Python preflight/warm checks - `PI_PYTHON_INTEGRATION=1` — enable gated integration tests that spawn a real Python - `PI_PYTHON_IPC_TRACE=1` — log NDJSON frames exchanged with the runner subprocess -- `PI_DEBUG_STARTUP=1` — emit startup-stage debug markers diff --git a/docs/tools/bash.md b/docs/tools/bash.md index 789036cee..204130ecd 100644 --- a/docs/tools/bash.md +++ b/docs/tools/bash.md @@ -100,7 +100,7 @@ Stdout and stderr are merged before the model sees them. Non-zero exit codes are - Uses `session.allocateOutputArtifact()` for spill files. - User-visible prompts / interactive UI - PTY mode opens a TUI overlay titled `Console` and forwards input to the PTY. - - Background start messages direct the agent to `job` and to read `jobs://`. + - Background start messages direct the agent to the `job` tool (use `list: true` for a snapshot, or pass `poll: [id]` to wait). - Background work / cancellation - Async and auto-background jobs continue after the initial tool return. - Cancellation aborts the native run; PTY overlay dismissal also kills the PTY. diff --git a/docs/tools/job.md b/docs/tools/job.md index 5b35d3337..edeb260c8 100644 --- a/docs/tools/job.md +++ b/docs/tools/job.md @@ -8,7 +8,6 @@ - Key collaborators: - `packages/coding-agent/src/async/job-manager.ts` — job registry, cancellation, delivery suppression. - `packages/coding-agent/src/async/support.ts` — feature gating for background jobs. - - `packages/coding-agent/src/internal-urls/jobs-protocol.ts` — `jobs://` listing and per-job detail. - `packages/coding-agent/src/tools/bash.ts` — explicit async bash and auto-backgrounded bash jobs. - `packages/coding-agent/src/task/index.ts` — async task-job scheduling. - `packages/coding-agent/src/sdk.ts` — automatic follow-up delivery for unsuppressed completions. @@ -18,8 +17,9 @@ | Field | Type | Required | Description | | --- | --- | --- | --- | -| `poll` | `string[]` | No | Job ids to watch. If omitted and `cancel` is also omitted, the tool watches all running jobs. If provided, missing ids are silently filtered out before waiting. | +| `poll` | `string[]` | No | Job ids to watch. Cannot be combined with `list`. If omitted (and `cancel` is also omitted), the tool watches all running jobs. If provided, missing ids are silently filtered out before waiting. | | `cancel` | `string[]` | No | Job ids to cancel before any polling. Missing ids are reported as `not_found`; non-running ids as `already_completed`. | +| `list` | `boolean` | No | Return an immediate snapshot of every job spawned by the calling agent (running + completed within retention) without waiting. Read-only — cannot be combined with `poll` or `cancel`. | ## Outputs The tool returns one text block plus `details`. @@ -41,9 +41,8 @@ Streaming behavior: - During a polling wait, `execute(...)` emits `onUpdate(...)` every 500 ms with an empty text block and fresh `details.jobs` snapshots. - Final return is single-shot after a completion, timeout, abort, or immediate fast path. -Related read path: -- Reading `jobs://` lists all current jobs. -- Reading `jobs://` renders one job with status, label, start time, duration, and stored result/error text. +Read-only snapshot path: +- Calling `job` with `list: true` returns a markdown summary of every job spawned by the calling agent (running + completed within retention) without waiting. ## Flow 1. `JobTool.createIf(...)` in `packages/coding-agent/src/tools/job.ts` only exposes the tool when `isBackgroundJobSupportEnabled(...)` returns true for either `async.enabled` or `bash.autoBackground.enabled`. @@ -77,7 +76,7 @@ Related read path: - Poll explicit ids: call with `poll` only. - Cancel only: call with `cancel` only; cancellations happen and the tool returns immediately. - Cancel then poll: call with both. Cancellations are applied first, then the tool watches the remaining resolved `poll` ids. -- Read-only inspection outside the tool: `jobs://` and `jobs://` expose the same manager state without waiting. +- Read-only inspection: call with `list: true` for the same snapshot data without waiting on completion. Spawn paths that produce jobs: - `packages/coding-agent/src/tools/bash.ts` @@ -129,15 +128,13 @@ Lifecycle and exact state names: - Cancelling a non-running job is not an exception; it reports `already_completed` even if the actual status is `completed`, `failed`, or `cancelled`. - Tool-call abort during polling stops waiting and returns a final snapshot through `#buildResult(...)`; it does not cancel watched jobs. - Failures inside the underlying async work are stored on the job (`status: "failed"`, `errorText`) and reported in normal tool output, not rethrown by `job`. -- Reading `jobs://` for a missing job returns markdown content headed `# Job Not Found` rather than throwing. +- Calling `list: true` against an empty manager returns a normal empty-list result rather than throwing; missing ids passed to `poll` are silently filtered. ## Notes - `job` waits for the first watched running job to settle, not for all watched jobs. If others remain `running`, they are reported under `## Still Running`; the caller must invoke `job` again to continue waiting. - Delivery suppression is the key difference between snapshot and automatic delivery: - - snapshots (`job`, reads of `jobs://`) read current manager state; + - snapshots (`job` calls with `poll` or `list: true`) read current manager state; - follow-up delivery comes from `AsyncJobManager.#enqueueDelivery(...)` and `sdk.ts` `onJobComplete`; - watched or acknowledged ids are suppressed via `isDeliverySuppressed(...)`. - `manager.cancel(id)` sets `status = "cancelled"` before the underlying promise settles. The job function may later populate `resultText` or `errorText`; `job-manager.ts` preserves that text but does not transition the status away from `cancelled`. -- `jobs://` is implemented by `JobsProtocolHandler` with `immutable = true`, but each resolve call reads live manager state at access time. -- `jobs://` shows a cancellation section only when a cancelled job has `errorText`; cancelled jobs with `resultText` are not rendered with a result section there. -- Retention eviction removes the job record, suppression flags, and watch flag together. After eviction, both `job` and reads of `jobs://` behave as if the id never existed. +- Retention eviction removes the job record, suppression flags, and watch flag together. After eviction, both `job` calls and `list: true` snapshots behave as if the id never existed. diff --git a/docs/tools/read.md b/docs/tools/read.md index 3bdae131f..ad7fc8630 100644 --- a/docs/tools/read.md +++ b/docs/tools/read.md @@ -10,7 +10,7 @@ - `packages/coding-agent/src/tools/archive-reader.ts` — detect `archive.ext:inner/path`, index archives, list/read entries. - `packages/coding-agent/src/tools/sqlite-reader.ts` — detect SQLite targets, parse selectors, render tables. - `packages/coding-agent/src/tools/fetch.ts` — URL parsing, fetch/render pipeline, URL cache/artifacts. - - `packages/coding-agent/src/internal-urls/router.ts` — resolve `agent://`, `artifact://`, `jobs://`, `local://`, `mcp://`, `memory://`, `pi://`, `rule://`, `skill://`. + - `packages/coding-agent/src/internal-urls/router.ts` — resolve `agent://`, `artifact://`, `local://`, `mcp://`, `memory://`, `pi://`, `rule://`, `skill://`. - `packages/coding-agent/src/edit/notebook.ts` — convert `.ipynb` to editable `# %% [...] cell:N` text. - `packages/coding-agent/src/utils/file-display-mode.ts` — decide hashline vs line-number vs raw display. - `packages/coding-agent/src/workspace-tree.ts` — render directory trees. @@ -194,7 +194,7 @@ URL selectors are parsed separately in `packages/coding-agent/src/tools/fetch.ts ### Internal URLs - `read` does not resolve these itself; it delegates to `session.internalRouter.resolve()`. -- Registered protocols are outside this file, but the router in `packages/coding-agent/src/internal-urls/router.ts` is built for `agent://`, `artifact://`, `issue://`, `jobs://`, `local://`, `mcp://`, `memory://`, `pi://`, `pr://`, `rule://`, and `skill://`. +- Registered protocols are outside this file, but the router in `packages/coding-agent/src/internal-urls/router.ts` is built for `agent://`, `artifact://`, `issue://`, `local://`, `mcp://`, `memory://`, `pi://`, `pr://`, `rule://`, and `skill://`. - `#handleInternalUrl()` behavior: - parses the URL with `parseInternalUrl()` so colons inside the host segment are legal - for `agent://`, treats non-root path extraction or `?q=` extraction as a special no-pagination mode