From 9a6b2241de1eec1991eed3f2321c163cadd0da8e Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Thu, 28 May 2026 00:34:59 +0000 Subject: [PATCH 01/10] docs: document recent task and output updates --- packages/design-system/README.md | 58 ++++++++++++++++++++++++++++++++ packages/task-list/README.md | 48 ++++++++++++++++++++++++-- packages/toolcraft/README.md | 13 +++++-- 3 files changed, 114 insertions(+), 5 deletions(-) create mode 100644 packages/design-system/README.md diff --git a/packages/design-system/README.md b/packages/design-system/README.md new file mode 100644 index 0000000000..dc5e192c61 --- /dev/null +++ b/packages/design-system/README.md @@ -0,0 +1,58 @@ +# @poe-code/design-system + +Shared terminal UI components, themes, prompt primitives, and static renderers for Poe Code packages. + +## Components + +- `createLogger` / `logger`: consistent scoped log output. +- `helpFormatter`: usage, command, and option formatting for CLI help. +- `renderTable`: tabular and detail-style row rendering. +- `renderDetailCard`: title, subtitle, prose, badge, section, and label/value rendering for rich command results. +- `renderTemplate`: Mustache-backed text rendering with configured escaping. +- `prompts`: themed select, multiselect, text, password, confirm, spinner, and note helpers. +- `dashboard` / `explorer`: interactive terminal layouts. +- `terminal-markdown`: Markdown parsing and terminal rendering. + +## `renderDetailCard` + +Use detail cards when command output is a single record with scalar fields and nested sections: + +```ts +import { getTheme, renderDetailCard } from "@poe-code/design-system"; + +const output = renderDetailCard({ + theme: getTheme(), + title: "Deployment", + subtitle: "production", + badges: ["SUCCESS"], + sections: [ + { + rows: [ + { label: "Version", value: "v3.0.228" }, + { label: "URL", value: "https://example.com/releases/v3.0.228" } + ] + } + ] +}); +``` + +The renderer wraps long values, aligns labels, formats optional prose blocks, and skips empty sections. + +## Environment variables + +| Env var | Behavior | +| ------------------------- | --------------------------------------------------------------------------------------- | +| `POE_CODE_THEME` | Explicit theme override. Supports `light` or `dark`; takes precedence over `POE_THEME`. | +| `POE_THEME` | Theme override used when `POE_CODE_THEME` is not set. Supports `light` or `dark`. | +| `APPLE_INTERFACE_STYLE` | Theme detection fallback; `Dark` selects the dark theme, other values select light. | +| `VSCODE_COLOR_THEME_KIND` | Theme detection fallback; values containing `dark` or `light` select that theme. | +| `COLORFGBG` | Theme detection fallback based on the terminal background color code. | +| `OUTPUT_FORMAT` | Static rendering mode. Supports `terminal`, `markdown`, or `json`. | +| `FORCE_COLOR` | Forces ANSI color when set to any value except `0`. | +| `NO_COLOR` | Disables ANSI color unless `FORCE_COLOR` is set. | +| `TERM` | Used for color support detection; `dumb` disables color without `FORCE_COLOR`. | +| `POE_NO_SPINNER` | Set to `1` to render spinner fallbacks instead of animated spinners. | + +## Config options + +This package has no file-based configuration. Components are configured by function options, such as the `theme`, `columns`, `rows`, `width`, and prompt option objects passed to exported helpers. diff --git a/packages/task-list/README.md b/packages/task-list/README.md index fc4c0662bd..d4ad30d2b9 100644 --- a/packages/task-list/README.md +++ b/packages/task-list/README.md @@ -19,6 +19,7 @@ The task lifecycle is `draft -> planned -> in-progress -> done -> archived`. `ar - `openTaskList(options)`: opens a task store and returns a `TaskList` - `TaskList`: top-level interface for listing lists, querying all tasks, and resolving qualified IDs - `Tasks`: per-list interface for create, update, `fire`, `canFire`, `events`, delete, `move`, `reorder`, and list operations +- `moveTasks(options)`: copies tasks from one backend to another with optional state mapping, rate limiting, dry-run, and source deletion - `Task`: normalized task record with `list`, `id`, `qualifiedId`, `name`, `state`, `description`, and `metadata` - `TaskState`: `"draft" | "planned" | "in-progress" | "done" | "archived"` - `TaskDefaults`: default `metadata` applied when creating new tasks @@ -103,6 +104,33 @@ await plans.list("plans").reorder(["api-shape-providers", "memory"]); `frontmatterMode: "strict"` expects full task frontmatter (`kind`, `version`, `name`, `state`, and related task fields). `frontmatterMode: "passthrough"` keeps unrelated frontmatter keys as task metadata and writes back only the task-owned fields (`name`, `description`, `state`), so existing plan metadata is preserved. +### Moving tasks between backends + +Use `moveTasks` to migrate tasks between two configured backends. The helper creates target tasks, optionally maps source states to target states, rate-limits creates, rolls back a target task when a later step fails, and can delete the source task after a successful create. + +```ts +import { moveTasks } from "@poe-code/task-list"; + +await moveTasks({ + source: { + type: "markdown-dir", + path: "/repo/docs/plans", + singleList: "import", + frontmatterMode: "passthrough" + }, + target: { + type: "gh-issues", + repo: "octo-org/octo-repo", + project: { owner: "octo-org", number: 7 } + }, + stateMap: { planned: "queued", done: "done" }, + rate: 30, + deleteSource: true +}); +``` + +When the source state already matches the target state, no transition event is fired. This avoids spurious round-trips through other states on any-to-any state machines. + ### `yaml-file` ```ts @@ -235,10 +263,10 @@ The CLI exposes the same verification and provisioning flow: ```sh poe-code tasks verify --workflow ./WORKFLOW.md --repo octo-org/octo-repo --project octo-org/7 --states queued,agent-running,human-review,done,failed,archived --json -poe-code tasks sync --workflow ./WORKFLOW.md --repo octo-org/octo-repo --project octo-org/7 --states queued,agent-running,human-review,done,failed,archived --json --yes +poe-code tasks sync --workflow ./WORKFLOW.md --repo octo-org/octo-repo --project octo-org/7 --states queued,agent-running,human-review,done,failed,archived --title "Delivery Board" --json --yes ``` -`` and `--project` both use `/` project syntax. `--workflow` defaults to `./WORKFLOW.md`. `--repo` overrides the task repository from workflow frontmatter. `--states` overrides the required state list from workflow frontmatter. `--json` prints the report object as JSON. `--yes` confirms non-interactive sync; it is only used by `poe-code tasks sync`. +`` and `--project` both use `/` project syntax. `--workflow` defaults to `./WORKFLOW.md`. `--repo` overrides the task repository from workflow frontmatter. `--states` overrides the required state list from workflow frontmatter. `--title` sets the human-readable project title when sync must create a missing project. `--json` prints the report object as JSON. `--yes` confirms non-interactive sync; it is only used by `poe-code tasks sync`. | Option | Commands | Behavior | | -------------------------- | ---------------- | --------------------------------------------------- | @@ -246,12 +274,26 @@ poe-code tasks sync --workflow ./WORKFLOW.md --repo octo-org/octo-repo -- | `--repo ` | `verify`, `sync` | GitHub repository owner/name. | | `--project ` | `verify`, `sync` | GitHub Project v2 owner/number. Overrides ``. | | `--states ` | `verify`, `sync` | Required task state names. | +| `--title ` | `sync` | Project title to use if sync creates the project. | | `--json` | `verify`, `sync` | Prints the report as JSON. | | `--yes` | `sync` | Confirms non-interactive provisioning. | The `Status` field name and option names are matched case-sensitively. The field must be named `Status`, and required option names must match exactly. For example, `status` is treated as a missing field, and `Done` is treated as missing when the required state is `done`. -In v1, if sync creates a new GitHub Project v2 board, the CLI prints the new project number and does not rewrite `WORKFLOW.md`. The operator must update `WORKFLOW.md` by hand with the printed `/`. +If sync creates a new GitHub Project v2 board, it re-reads the new project to pick up GitHub's auto-created `Status` field before adding missing options. Existing option colors and descriptions are preserved when missing options are appended. The CLI prints the new project number and does not rewrite `WORKFLOW.md`; the operator must update `WORKFLOW.md` by hand with the printed `/`. + +`poe-code tasks sync` reads `tasks.auth.token` from workflow frontmatter with the same `$ENV` expansion used by backend options. If the workflow does not provide a token, the CLI falls back to `gh auth token`. + +## Importing Markdown task files + +Use `poe-code tasks import` to ingest a directory of Markdown files into the backend configured by a target workflow file: + +```sh +poe-code tasks import --from ./incoming-tasks --to ./WORKFLOW.md --rate 30 +poe-code tasks import --from ./incoming-tasks --to ./WORKFLOW.md --dry-run --keep +``` + +The import source is treated as a `markdown-dir` backend with `singleList: "import"` and `frontmatterMode: "passthrough"`, so files without full task frontmatter can be imported. By default, successfully imported source files are deleted. Pass `--keep` to leave source files in place. `--rate`, `--limit`, and `--dry-run` match `poe-code tasks move`. ## Notes diff --git a/packages/toolcraft/README.md b/packages/toolcraft/README.md index b38c31a037..b81171d154 100644 --- a/packages/toolcraft/README.md +++ b/packages/toolcraft/README.md @@ -250,7 +250,7 @@ Services are merged into the handler context alongside the built-ins (`fetch`, ` ## Output rendering -Handlers return raw values. Add per-format renderers when you want richer CLI output: +Handlers return raw values. Add per-format renderers when you want custom CLI output: ```ts defineCommand({ @@ -265,7 +265,16 @@ defineCommand({ }); ``` -CLI picks `rich` by default, `--json` switches to `json`. SDK and MCP always return the raw handler value. +CLI picks `rich` by default, `--json` switches to `json`, and `--output md` switches to Markdown. SDK and MCP always return the raw handler value. + +When a command does not define a renderer, Toolcraft auto-renders common shapes: + +- `undefined` / `null` → `Done.` for rich and Markdown output, or `{ "ok": true }` for JSON. +- `string` → printed as-is. +- `string[]` → printed one item per line in rich output. +- object records → rich detail cards with scalar fields, nested-object sections, compact URLs, boolean values as `Yes` / `No`, and arrays under a `Lists` section. +- arrays of objects → rich tables with columns inferred from object keys. +- MCP call-tool envelopes → unwrapped from `structuredContent.result`, `structuredContent`, or text content before rendering; `isError: true` writes the rendered payload to stderr and marks the CLI run as failed. ## MCP proxy: adopt an existing MCP server From e8749c4dec2fc77be6d6e71146ba241f3117ace2 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Wed, 3 Jun 2026 00:44:57 +0000 Subject: [PATCH 02/10] docs: document recent code review and pipeline updates --- packages/agent-code-review/README.md | 3 ++- packages/pipeline/README.md | 31 +++++++++++++++------------- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/packages/agent-code-review/README.md b/packages/agent-code-review/README.md index c6aa4043f6..ecff94fcf6 100644 --- a/packages/agent-code-review/README.md +++ b/packages/agent-code-review/README.md @@ -48,6 +48,7 @@ The package defines no environment variables of its own. Runtime review does not - `runCodeReview` resolves runtime config, session and agent selection; fetches PR metadata, diff, and prior review activity through `github-review`; includes optional external feedback in the orchestrator prompt; initializes YAML state; and spawns the orchestrator through the `poe-code` SDK. - `ingestCodeReviewProfile` fetches normalized review-history records through `github-review`, records `.poe-code/code-review/ingest//{source.yaml,comments.jsonl,synthesis-prompt.md}`, and spawns the selected agent to write `.poe-code/code-review/profiles/.md` directly. - The orchestrator can call `code_review_agent_spawn` for profile reviewers. Each subagent may override `agent`; omitted overrides inherit the run agent, and each resolved agent is persisted in YAML. +- Review orchestrator and subagent prompts are sent through stdin for Codex and Claude Code, including aliases that resolve to those spawn configs, so large review contexts do not need to fit in command-line arguments. Other agents keep the normal spawn prompt transport. ## Recovery and resume @@ -98,7 +99,7 @@ Slack approval, ticketing, or any other human-gate integration belongs outside ` await runCodeReview({ prUrl: "https://github.com/acme/widgets/pull/123", cwd: process.cwd(), - additionalFeedback: "Please verify rollback coverage before approval.", + additionalFeedback: "Please verify rollback coverage before approval." }); ``` diff --git a/packages/pipeline/README.md b/packages/pipeline/README.md index 0c5ea4815d..0c7b367982 100644 --- a/packages/pipeline/README.md +++ b/packages/pipeline/README.md @@ -21,6 +21,12 @@ poe-code pipeline run ## Example Plan ```yaml +kind: pipeline +version: 1 +name: session-refresh +state: in_progress +extends: default + tasks: - id: fix-timeout title: Fix timeout bug @@ -42,7 +48,7 @@ tasks: commit: open ``` -Each step becomes its own agent execution. Steps are resolved from `.poe-code/pipeline/steps.yaml` (or `~/.poe-code/pipeline/steps.yaml`). See [Step Configuration](#step-configuration). +Each step becomes its own agent execution. `kind`, `version`, `name`, and `state` are optional plan metadata fields; the runner uses `extends`, `tasks`, `vars`, hooks, and MCP config for execution. Steps are resolved from `.poe-code/pipeline/steps.yaml` (or `~/.poe-code/pipeline/steps.yaml`). See [Step Configuration](#step-configuration). ## Step Configuration @@ -120,8 +126,7 @@ Hooks can be defined in `steps.yaml` (shared defaults) or in the plan file (per- ```yaml setup: false -tasks: - ... +tasks: ... ``` If setup fails, no tasks run. If teardown fails, the pipeline returns `stopReason: "failed"`. @@ -221,23 +226,21 @@ Exports: `runPipeline`, `resolvePlanPath`, `parsePlan`, `writeTaskStatus`, `load ## Testing Helper ```ts -import { - createPipelineSimulation, - successTurn, - failTurn -} from "@poe-code/pipeline/testing"; +import { createPipelineSimulation, successTurn, failTurn } from "@poe-code/pipeline/testing"; const sim = createPipelineSimulation({ projectSteps: { implement: { mode: "yolo", prompt: "Implement {{id}}" } }, plan: { - tasks: [{ - id: "task-1", - title: "Demo task", - prompt: "Do the thing", - status: { implement: "open" } - }] + tasks: [ + { + id: "task-1", + title: "Demo task", + prompt: "Do the thing", + status: { implement: "open" } + } + ] }, turns: [successTurn()] }); From 038eaaac045eb94774b9c2a9ff220ab9ff711c5b Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Thu, 4 Jun 2026 00:44:33 +0000 Subject: [PATCH 03/10] docs: document whoami newline output --- docs/README_FULL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README_FULL.md b/docs/README_FULL.md index f7ce63d57b..da9260b309 100644 --- a/docs/README_FULL.md +++ b/docs/README_FULL.md @@ -299,7 +299,7 @@ Running `poe-code auth` with no subcommand is the same as `poe-code auth status` |------------|-------------| | `status` | Show whether a stored Poe credential is valid and print the account name/handle. Honors `--dry-run` by skipping the `/whoami` request. | | `api-key` | Print the stored Poe API key only. Exits with code `1` when no key is stored. | -| `whoami` | Call Poe `/whoami` and print the raw identity JSON to stdout. Resolves `POE_API_KEY` first, then the stored credential. Exits with code `1` when no key is available. | +| `whoami` | Call Poe `/whoami` and print the raw identity JSON to stdout with a trailing newline. Resolves `POE_API_KEY` first, then the stored credential. Exits with code `1` when no key is available. | | `login` | Store a Poe API key for reuse across commands. Same behavior as top-level `poe-code login`. | | `logout` | Remove all configuration and credentials. Same behavior as top-level `poe-code logout`. | From 1fbb0e29da63dfaf759418720c744aede2e3b7ae Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Fri, 5 Jun 2026 00:40:43 +0000 Subject: [PATCH 04/10] docs: document recent package lint and MCP updates --- docs/development/NPM_PUBLISHING.md | 26 +++++- docs/plans/package-lint.md | 110 ++++++++++------------- docs/qa/package-lint.md | 29 +++--- packages/package-lint/README.md | 15 +++- packages/tiny-http-mcp-server/README.md | 25 ++++-- packages/tiny-stdio-mcp-server/README.md | 89 ++++++++++++++++-- scripts/README.md | 56 +++++++++--- 7 files changed, 243 insertions(+), 107 deletions(-) diff --git a/docs/development/NPM_PUBLISHING.md b/docs/development/NPM_PUBLISHING.md index b70aa6eb57..43093d46b2 100644 --- a/docs/development/NPM_PUBLISHING.md +++ b/docs/development/NPM_PUBLISHING.md @@ -35,7 +35,7 @@ For trusted publishing, avoid token-based npm auth in the workflow: - Trusted publishing requires `npm >= 11.5.1` and `node >= 22.14.0`. - In `actions/setup-node`, set `node-version`, then upgrade npm (example: `npm install --global npm@^11.5.1`) before running `npm publish --provenance --access public`. -For the version alignment step, use `--allow-same-version` so the workflow does not fail on first run after local initial publish: +For a single-package release, the workflow can align to the current npm version and patch from there. Use `--allow-same-version` so the workflow does not fail on first run after local initial publish: ```sh REMOTE=$(npm view version 2>/dev/null || echo "0.0.0") @@ -43,6 +43,30 @@ npm version --no-git-tag-version --allow-same-version "$REMOTE" npm version --no-git-tag-version patch ``` +For packages that must release in lockstep, use the shared composite action after calculating the concrete version and before packing/publishing any package in the group: + +```yaml +- name: Prepare lockstep package versions + uses: ./.github/actions/prepare-lockstep-release + with: + version: ${{ steps.version.outputs.version }} + packages: '["packages/toolcraft", "packages/toolcraft-openapi"]' +``` + +The action rewrites every listed `package.json` to the same version and rewrites intra-group `dependencies`, `peerDependencies`, and `optionalDependencies` to that exact version. The group must contain at least two public npm package directories, and each prepared package should be published by the workflow. `npm run lint:packages` enforces this with `lockstep-release-group-valid`. + +If a published package declares `bin`, add the shared executable-bit helper to `prepack` so `tsc`-emitted binaries do not ship as mode `0644`: + +```json +{ + "scripts": { + "prepack": "npm run build && node ../../scripts/set-bin-executable.mjs" + } +} +``` + +The helper derives targets from the package `bin` field, fails when a declared bin file is missing, and writes progress to stderr so `npm pack --json` output stays valid JSON. + ## 4. Provenance troubleshooting If publish fails with an error like: diff --git a/docs/plans/package-lint.md b/docs/plans/package-lint.md index ba027b3198..72521b61c2 100644 --- a/docs/plans/package-lint.md +++ b/docs/plans/package-lint.md @@ -18,10 +18,10 @@ A tool that looks up each package, figures out its dependency tree, and determin Decisions taken (from chat): -- New package `@poe-code/package-lint`, run via `npm run lint:packages`, folded into `npm run lint`. +- New package `@poe-code/package-lint`, run via `npm run lint:packages` (kept separate from the aggregate `npm run lint` while it remains developer tooling). - Offline only — no npm registry calls. "Published" is derived from the explicit `private` flag plus release-workflow wiring, never from `@scope` vs unscoped (scope does not map to publish status: `@poe-code/design-system` is scoped and public; `agent-code-review` is unscoped and private). -- Rollout is fix-then-hard-fail: clear the existing violations, then `lint`/CI block on any violation. -- This plan builds the analyzer; applying the fixes it surfaces is a follow-up. +- Rollout is fix-then-hard-fail: clear the existing violations, then keep `npm run lint:packages` as the package-boundary regression guard. +- This plan builds the analyzer and tracks the follow-up fixes that reduced the baseline to empty. Non-goals: @@ -37,7 +37,6 @@ Non-goals: ```sh npm run lint:packages # human report, non-zero exit on any violation npm run lint:packages -- --json # machine-readable, for CI logs / tooling -npm run lint # eslint + types + workflows + packages ``` `lint:packages` maps to the package bin `poe-package-lint` (no `poe-code` subcommand — dev tooling, not a user feature). @@ -53,51 +52,30 @@ Exit `0` clean · `1` violations found · `2` tool error (unreadable/malformed ` ### Example output (rendered via design-system) ``` -package-lint · 6 rules · 60 packages +package-lint · 11 rules · 60 packages -✖ shipped-dist-deps-unresolvable (1) - bin poe-superintendent-mcp → packages/superintendent/dist/mcp.js - imports toolcraft, tiny-stdio-mcp-server by bare name; neither is in - root "dependencies" and the tarball ships no node_modules for them. - ERR_MODULE_NOT_FOUND on install. Bundle them, or add to root deps. - -✖ no-published-to-private-dep (7) - toolcraft-codemode → @poe-code/agent-script (dependencies, private) - toolcraft → @poe-code/config-mutations (optionalDependencies, private) - … 5 more - -✖ public-needs-publish-wiring (9) - auth-store no release-*.yml; required by published mcp-oauth, toolcraft, toolcraft-openapi - @poe-code/design-system no release-*.yml; required by published toolcraft, toolcraft-openapi - mcp-oauth no release-*.yml; required by published tiny-http-mcp-oauth-test-server, tiny-mcp-client, toolcraft - -✖ published-dep-needs-version-range (17) - mcp-oauth → auth-store@* → use a concrete range - opencode-poe-auth → poe-oauth@* → use a concrete range - … 15 more - -bundle-self-contained ✓ +shipped-dist-deps-unresolvable ✓ +no-published-to-private-dep ✓ +published-dep-needs-version-range ✓ +public-needs-publish-wiring ✓ release-workflow-maps-to-package ✓ - -5 rules failed · 34 violations +lockstep-release-group-valid ✓ +no-cross-package-relative-import ✓ +imported-workspace-dep-unresolvable ✓ +exports-subpath-resolvable ✓ +bundle-self-contained ✓ +published-bin-must-be-executable ✓ +✓ all 11 rules passed ``` `--json` shape: ```json { - "summary": { "packages": 60, "rules": 6, "violations": 34, "ok": false }, - "violations": [ - { - "rule": "shipped-dist-deps-unresolvable", - "package": "@poe-code/superintendent", - "severity": "error", - "via": "bin:poe-superintendent-mcp", - "detail": { "unresolved": ["toolcraft", "tiny-stdio-mcp-server"] }, - "message": "shipped dist imports bare names not in root dependencies", - "fix": "Bundle poe-superintendent-mcp so these are inlined, or add each to root \"dependencies\"." - } - ] + "summary": { "packages": 60, "rules": 11, "violations": 0, "ok": true }, + "evaluated": ["shipped-dist-deps-unresolvable", "..."], + "violations": [], + "skipped": [] } ``` @@ -105,19 +83,21 @@ release-workflow-maps-to-package ✓ Every rule decides from facts. "Published" = `private !== true`. "Shipped" = the package's built `dist` reaches the published `poe-code` tarball (a root `files` entry or a root `bin` target path under `packages//dist`). Packages with a Python project file are tagged `pypi` and exempt from the npm rules. -| id | Proves (fact checked) | Caught in this repo today | -| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| `shipped-dist-deps-unresolvable` | Every runtime dependency of a shipped (tsc-emitted, unbundled) dist resolves from the published tarball — it is in root `dependencies`, a Node builtin, or itself bundled. A bare workspace/third-party import that isn't installed = `ERR_MODULE_NOT_FOUND`. | `poe-superintendent-mcp` → `toolcraft`, `tiny-stdio-mcp-server` | -| `no-published-to-private-dep` | No published package depends (deps/peer/optional) on a private workspace package — it will never exist on npm. `optionalDependencies` is the exact vector for the same-name collision. | 7: `toolcraft-codemode`→`@poe-code/agent-script`; `toolcraft`→ 6 private `@poe-code/*` (optional) | -| `published-dep-needs-version-range` | A published→published workspace dep uses a concrete range, never `*`/`workspace:*` (on npm `*` resolves to whatever the registry returns — the collision vector). | 17: `mcp-oauth`→`auth-store@*`, … | -| `public-needs-publish-wiring` | Hygiene: a public package with no release workflow or no `repository.directory` has no publish path — it cannot be published as-is (`warning`). Whether a published package actually _needs_ it on npm is decided from real imports by `imported-workspace-dep-unresolvable`, not from declarations. | 8 warnings (public packages with no release workflow). | -| `release-workflow-maps-to-package` | Every release workflow targets an existing, non-private (or pypi) package — no drift between workflow and packages. | 0 | -| `no-cross-package-relative-import` | No source file imports a sibling package by a relative path that escapes its own directory (e.g. `../../mcp-oauth/dist/index.js`) — it bypasses the dependency graph and breaks once published. Error in shipped code, warning in tests. | 12: `tiny-mcp-client`, `memory`→`tokenfill/dist`, `terminal-pilot` template paths, … | -| `imported-workspace-dep-unresolvable` | Import-driven: every workspace package a published package's shipped source **actually imports** (runtime, non-type-only) is vendored (`bundledDependencies`) or itself reaches npm. Catches **undeclared** imports the package.json rules can't see. | 1: `terminal-pilot`→`@poe-code/agent-skill-config` (undeclared import of a private package). | -| `exports-subpath-resolvable` | Import-driven: a bare subpath import of a workspace package (e.g. `toolcraft/cli`) must be a subpath the target's `exports` map exposes — Node gates `exports`, so an unlisted subpath is `ERR_PACKAGE_PATH_NOT_EXPORTED` once published (masked in-repo by test/bundle aliases). | 0 today (54 subpath imports across 19 exports-mapped packages all resolve — regression guard). | -| `bundle-self-contained` _(build-aware)_ | The bundled entry (`dist/index.js`, `agent.js`, `providers/*`) inlines every referenced workspace package and externalizes nothing absent from root `dependencies`. Consumes the esbuild metafile. | 0 (bundle is clean) | - -The vendoring guarantee is layered: `shipped-dist-deps-unresolvable` (static, package.json) catches the superintendent bin break without a build; `imported-workspace-dep-unresolvable` and `no-cross-package-relative-import` parse the **real** `src` import graph with the TypeScript compiler's own scanner (the engine `typescript-eslint` runs on), catching undeclared/cross-boundary imports declarations can't see; `bundle-self-contained` (build-aware) consumes the metafile. Private packages that nothing in the published surface imports (`worktree`, `e2e-test-runner`, `cached-resource`, `agent-child-process`, `py-poe-spawn`) are correctly _not_ vendored and raise nothing. +| id | Proves (fact checked) | Current status | +| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `shipped-dist-deps-unresolvable` | Every runtime dependency of a shipped (tsc-emitted, unbundled) dist resolves from the published tarball — it is in root `dependencies`, a Node builtin, or itself bundled. A bare workspace/third-party import that isn't installed = `ERR_MODULE_NOT_FOUND`. | 0 today (regression guard). | +| `no-published-to-private-dep` | No published package depends (deps/peer/optional) on a private workspace package — it will never exist on npm. `optionalDependencies` is the exact vector for the same-name collision. | 0 today (regression guard). | +| `published-dep-needs-version-range` | A published→published workspace dep uses a concrete range, never loose `*`/`workspace:*`-style ranges, unless the packages are in the same declared lockstep release group or the non-peer dependency is bundled. | 0 today (regression guard). | +| `public-needs-publish-wiring` | Hygiene: a public package with no release workflow or no `repository.directory` has no publish path — it cannot be published as-is (`warning`). Whether a published package actually _needs_ it on npm is decided from real imports by `imported-workspace-dep-unresolvable`, not from declarations. | 0 today (regression guard). | +| `release-workflow-maps-to-package` | Every release workflow targets an existing, non-private (or pypi) package — no drift between workflow and packages. | 0 | +| `lockstep-release-group-valid` | Every `prepare-lockstep-release` workflow group has a concrete version, at least two unique public npm packages, and publish steps for every prepared package. | 0 | +| `no-cross-package-relative-import` | No source file imports a sibling package by a relative path that escapes its own directory (e.g. `../../mcp-oauth/dist/index.js`) — it bypasses the dependency graph and breaks once published. Error in shipped code, warning in tests. | 0 today (regression guard). | +| `imported-workspace-dep-unresolvable` | Import-driven: every workspace package a published package's shipped source **actually imports** (runtime, non-type-only) is vendored (`bundledDependencies`) or itself reaches npm. Catches **undeclared** imports the package.json rules can't see. | 0 today (regression guard). | +| `exports-subpath-resolvable` | Import-driven: a bare subpath import of a workspace package (e.g. `toolcraft/cli`) must be a subpath the target's `exports` map exposes — Node gates `exports`, so an unlisted subpath is `ERR_PACKAGE_PATH_NOT_EXPORTED` once published (masked in-repo by test/bundle aliases). | 0 today (54 subpath imports across 19 exports-mapped packages all resolve — regression guard). | +| `bundle-self-contained` _(build-aware)_ | The bundled entry (`dist/index.js`, `agent.js`, `providers/*`) inlines every referenced workspace package and externalizes nothing absent from root `dependencies`. Consumes the esbuild metafile. | 0 (bundle is clean) | +| `published-bin-must-be-executable` | Every genuinely published npm package with a `bin` runs `scripts/set-bin-executable.mjs` in `prepack`, so compiler-emitted bin files ship with executable bits. | 0 | + +The vendoring guarantee is layered: `shipped-dist-deps-unresolvable` (static, package.json) catches shipped-bin dependency breaks without a build; `imported-workspace-dep-unresolvable` and `no-cross-package-relative-import` parse the **real** `src` import graph with the TypeScript compiler's own scanner (the engine `typescript-eslint` runs on), catching undeclared/cross-boundary imports declarations can't see; `bundle-self-contained` (build-aware) consumes the metafile. Private packages that nothing in the published surface imports (`worktree`, `e2e-test-runner`, `cached-resource`, `agent-child-process`, `py-poe-spawn`) are correctly _not_ vendored and raise nothing. ## 3. Implementation details and technical decisions @@ -214,21 +194,21 @@ export function resolveBundleGraph(rootDir, packageJsons): { entryPoints: string ### Tests - **Unit (memfs, no disk, no network)** — one `*.test.ts` per rule. Each builds a synthetic in-memory workspace and asserts a positive (violation raised) and a negative (clean) case. Proves each rule's logic in isolation. Fast (< a few ms each). -- **Integration baseline (`repo-baseline.test.ts`)** — runs `loadWorkspace` + `runRules` against the _real_ repo and asserts the violation set equals committed `baseline.json`. The baseline is the catalogue of the real issues found here (46 today); it is both regression guard and the fix checklist. Reads real files and parses `src` (no build needed — build-aware rules skip). +- **Integration baseline (`repo-baseline.test.ts`)** — runs `loadWorkspace` + `runRules` against the _real_ repo and asserts the violation set equals committed `baseline.json`. The baseline is currently empty; it is both regression guard and the accepted-violation checklist if a future rollout intentionally allows a violation. Reads real files and parses `src` (no build needed — build-aware rules skip). - **Build-aware rule** — a focused test feeds a synthetic `metafile.json` fixture to `bundle-self-contained` (positive + negative); no real build in unit tests. - **Manual QA (markdown, not a script)** — `docs/qa/package-lint.md`: run `npm run lint:packages`, confirm the rendered report matches the failing rules; run `-- --json` and confirm shape; run after `npm run build` and confirm `bundle-self-contained` participates. ### Rollout -Fix-then-hard-fail. Order: land the analyzer with `baseline.json` capturing today's 46 violations (test green against the baseline) → fix violations in a follow-up, shrinking `baseline.json` toward `[]` → once empty, chain `lint:packages` into the `lint` aggregate and make any violation fail `lint`. CI runs `npm run lint`, so chaining now would fail it — that step waits until the baseline is empty. +Fix-then-hard-fail. The analyzer landed with a baseline and follow-up fixes reduced `packages/package-lint/baseline.json` to `[]`. `npm run lint:packages` now fails on any new violation; wiring it into the aggregate `npm run lint` remains a separate rollout choice. ### Autonomy checklist - Build the package, rules, reporter, CLI from the signatures above. - Generate `baseline.json` by running the analyzer against the repo (committed as the starting state). -- Wire `lint:packages` into root scripts (chaining into the `lint` aggregate is deferred to the hard-fail flip, per rollout). +- Wire `lint:packages` into root scripts (chaining into the `lint` aggregate remains a separate rollout choice). - Persist `dist/metafile.json` from `bundle.mjs` via the shared `resolveBundleGraph` helper. -- Verify: `npm run lint:packages` exits 1 and lists exactly the baseline; unit tests green; `npm run lint:packages -- --json` parses. +- Verify: `npm run lint:packages` exits 0 on the empty baseline; unit tests green; `npm run lint:packages -- --json` parses. ## 5. Code plan @@ -256,17 +236,17 @@ Fix-then-hard-fail. Order: land the analyzer with `baseline.json` capturing toda | `src/index.ts` | Public API re-exports. | | `src/rules/*.test.ts` | Per-rule memfs unit tests. | | `src/repo-baseline.test.ts` | Baseline integration test. | -| `packages/package-lint/baseline.json` | Committed real-violation snapshot (46 found). | +| `packages/package-lint/baseline.json` | Committed real-violation snapshot, currently empty after the bundle and release-wiring fixes. | | `scripts/bundle-graph.mjs` | Shared `resolveBundleGraph` extracted from `bundle.mjs`. | | `docs/qa/package-lint.md` | Manual QA steps. | ### Change -| File | Change | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `scripts/bundle.mjs` | Import `resolveBundleGraph` from `scripts/bundle-graph.mjs` (replace the inline alias/external computation); write `dist/metafile.json` after the main build. | -| `package.json` (root) | Add `"lint:packages": "poe-package-lint"`; add `@poe-code/package-lint` devDependency. Chaining it into the `lint` aggregate is deferred to the hard-fail flip (rollout), so CI stays green while the baseline is non-empty. | -| `turbo.json` | No change. The root bundle runs `bundle.mjs` outside turbo (only `packages/*` builds are turbo tasks), so a `dist/metafile.json` output entry would be inert; per-package `dist/**` already covers package dists. | +| File | Change | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `scripts/bundle.mjs` | Import `resolveBundleGraph` from `scripts/bundle-graph.mjs` (replace the inline alias/external computation); write `dist/metafile.json` after the main build. | +| `package.json` (root) | Add `"lint:packages": "poe-package-lint"`; add `@poe-code/package-lint` devDependency. Chaining it into the `lint` aggregate remains a separate rollout choice. | +| `turbo.json` | No change. The root bundle runs `bundle.mjs` outside turbo (only `packages/*` builds are turbo tasks), so a `dist/metafile.json` output entry would be inert; per-package `dist/**` already covers package dists. | ### Build order (keeps the branch green) @@ -275,4 +255,4 @@ Fix-then-hard-fail. Order: land the analyzer with `baseline.json` capturing toda 3. `report.ts` + `cli.ts` + `index.ts`; wire root `lint:packages`. 4. Extract `scripts/bundle-graph.mjs`, point `bundle.mjs` at it, persist `dist/metafile.json`; add `bundle-self-contained` + its fixture test. 5. Generate and commit `baseline.json`; add `repo-baseline.test.ts` (green against baseline). -6. Follow-up (separate change): fix the 34 violations, shrink `baseline.json` to `[]`, flip `lint` to hard-fail. +6. Follow-up: fix the reported violations and shrink `baseline.json` to `[]` (now complete); aggregate `lint` wiring remains separate. diff --git a/docs/qa/package-lint.md b/docs/qa/package-lint.md index 9735c2ec37..fdbe88e6bc 100644 --- a/docs/qa/package-lint.md +++ b/docs/qa/package-lint.md @@ -10,10 +10,12 @@ npm run lint:packages Expect: -- A header: `package-lint · 9 rules · packages`. -- Failing rules grouped under a red `■` header with a `(count)`; each violation - lists the package, the `via` field in parentheses, a one-line message, and a - `↳ fix:` hint on the following line. +- A header: `package-lint · 11 rules · packages`. +- Clean rules render ` ✓`; the current baseline is empty, so the + normal summary is `✓ all 11 rules passed` and the exit code is `0`. +- If a regression introduces violations, failing rules are grouped under a red + `■` header with a `(count)`; each violation lists the package, the `via` field + in parentheses, a one-line message, and a `↳ fix:` hint on the following line. - `public-needs-publish-wiring` is a hygiene warning (`▲`): a public package with no release workflow / `repository.directory` has no publish path. - `no-cross-package-relative-import` flags relative imports that escape into a @@ -25,9 +27,15 @@ Expect: - `exports-subpath-resolvable` flags a bare subpath import of a workspace package (e.g. `toolcraft/cli`) that the target's `exports` map does not expose (clean today — a regression guard). -- Rules with no violations render ` ✓`. -- A summary line: ` rules failed · violations` (with `(k warnings)` when any). -- Exit code is `1` (violations present). Confirm with `echo $?`. +- `lockstep-release-group-valid` validates every `prepare-lockstep-release` + workflow group: concrete version, at least two unique public npm packages, and + publish steps for every prepared package. +- `published-bin-must-be-executable` requires genuinely published packages with + `bin` entries to run `scripts/set-bin-executable.mjs` in `prepack`, preventing + `tsc`-emitted bins from shipping without executable bits. +- When violations exist, the summary line is ` rules failed · violations` + (with `(k warnings)` when any) and the exit code is `1`. Confirm the current + clean run exits `0` with `echo $?`. The import-driven rules parse real `src` imports with the TypeScript compiler, so they catch undeclared imports that the package.json-based rules cannot. @@ -38,7 +46,7 @@ so they catch undeclared imports that the package.json-based rules cannot. npm run lint:packages -- --json ``` -Expect valid JSON with `summary` (`packages`, `rules`, `violations`, `ok: false`), +Expect valid JSON with `summary` (`packages`, `rules`, `violations`, `ok: true` on the current clean tree), a `violations` array (each with `rule`, `package`, `severity`, optional `via`, `detail`, `message`), and `skipped`. Pipe through `node -e` or `jq` to confirm it parses. @@ -73,5 +81,6 @@ npx vitest run packages/package-lint/src/repo-baseline.test.ts ``` Expect green. This asserts the analyzer still finds exactly the violation set in -`packages/package-lint/baseline.json`. When a violation is fixed, regenerate the -baseline so the set shrinks toward `[]`. +`packages/package-lint/baseline.json`. The current baseline is empty; if a new +violation is intentionally accepted during rollout, regenerate the baseline and +include the reason in the change. diff --git a/packages/package-lint/README.md b/packages/package-lint/README.md index d974bd8951..e566a02893 100644 --- a/packages/package-lint/README.md +++ b/packages/package-lint/README.md @@ -31,13 +31,15 @@ malformed `package.json`). | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shipped-dist-deps-unresolvable` | Every runtime dependency of a shipped, tsc-emitted bin entry resolves from the published tarball — it is in root `dependencies`, a Node builtin, or itself a shipped package. | | `no-published-to-private-dep` | No published package depends (deps / peer / optional) on a private workspace package. | -| `published-dep-needs-version-range` | A published → published workspace dependency uses a concrete range, never `*` / `workspace:*`. | +| `published-dep-needs-version-range` | A published → published workspace dependency uses a concrete range, never loose ranges such as `*`, `latest`, or unbounded `workspace:*`; declared lockstep release groups and bundled non-peer deps are exempt. | | `public-needs-publish-wiring` | Hygiene: a public package with no release workflow or no `repository.directory` has no publish path (warning). Whether it is actually needed on npm is decided from real imports below, not declarations. | | `release-workflow-maps-to-package` | Every release workflow publishes an existing, non-private (or pypi) package. | +| `lockstep-release-group-valid` | Every `prepare-lockstep-release` workflow group has a concrete version, at least two unique package directories, only public npm packages, and publishes every package it prepares. | | `no-cross-package-relative-import` | No source file imports a sibling package by a relative path that escapes its own directory (e.g. `../../mcp-oauth/dist/index.js`); import the sibling by package name. Error in shipped code, warning in tests. | | `imported-workspace-dep-unresolvable` | Import-driven: every workspace package a published package's shipped source actually imports (runtime, non-type-only) is vendored (`bundledDependencies`) or itself reaches npm. Catches undeclared imports of private packages. | | `exports-subpath-resolvable` | Import-driven: a bare subpath import of a workspace package (e.g. `toolcraft/cli`) is a subpath the target's `exports` map exposes. Node gates `exports` — an unlisted subpath is `ERR_PACKAGE_PATH_NOT_EXPORTED` once published. | | `bundle-self-contained` _(build-aware)_ | The bundled entry inlines every referenced workspace package and externalizes nothing absent from root `dependencies`. Consumes `dist/metafile.json`; skipped when absent. | +| `published-bin-must-be-executable` | Every genuinely published npm package with a `bin` restores executable bits in `prepack` through `scripts/set-bin-executable.mjs`, so `tsc`-emitted bins do not ship with mode `0644`. | Imports are parsed with the TypeScript compiler's own scanner (the engine `typescript-eslint` runs on) over each package's `src`, so the import-driven @@ -46,6 +48,17 @@ rules reflect what the code actually imports, not what `package.json` declares. A package with a Python project file (`pyproject.toml` / `setup.py` / `setup.cfg`) is tagged `pypi` and exempt from the npm rules. +Lockstep release groups are discovered from `.github/actions/prepare-lockstep-release` +usage in release workflows. Packages in the same valid group may keep loose +intra-group ranges because the release action rewrites every package version and +every intra-group dependency to the same concrete version immediately before +publish. + +Published packages that declare `bin` entries should add +`node ../../scripts/set-bin-executable.mjs` to `prepack`. The helper derives bin +paths from `package.json`, fails if a declared target is missing, and writes +progress to stderr so `npm pack --json` stdout remains parseable. + ## Configuration No environment variables and no config file. Behavior is controlled entirely by diff --git a/packages/tiny-http-mcp-server/README.md b/packages/tiny-http-mcp-server/README.md index 1eb5ff516f..853591a656 100644 --- a/packages/tiny-http-mcp-server/README.md +++ b/packages/tiny-http-mcp-server/README.md @@ -242,7 +242,7 @@ npx tiny-http-mcp-server --stateless ## API Reference -The package re-exports the base server helpers from `tiny-stdio-mcp-server`, so you can import `defineSchema`, `createServer`, `Image`, `Audio`, `File`, and related types from here as well. +The package re-exports the base server helpers from `tiny-stdio-mcp-server`, so you can import `defineSchema`, `createServer`, `Image`, `Audio`, `File`, and related prompt/resource types from here as well. HTTP servers advertise the same prompt and resource capabilities as the stdio server. ### `createHttpServer(options)` @@ -259,7 +259,10 @@ const server = createHttpServer({ Returned `HttpServer` instances support: -- `.tool(name, description, schema, handler)` to register tools +- `.tool(name, description, schema, handler)` and `.registerTool(definition, handler)` to register tools +- `.prompt(definition, handler)` to register reusable prompts +- `.resource(definition, handler)` and `.resourceTemplate(definition, handler)` to register readable resources +- `.notifyToolsChanged()`, `.notifyPromptsChanged()`, `.notifyResourcesChanged()`, and `.notifyResourceUpdated(uri)` for initialized clients - `.listenHttp(options?)` to start a standalone Node HTTP server - `.handleRequest(req, res)` to plug into an existing HTTP stack @@ -267,13 +270,16 @@ Returned `HttpServer` instances support: `createHttpServer()` accepts the base `ServerOptions` from `tiny-stdio-mcp-server` plus HTTP transport options: -| Option | Type | Default | Description | -| -------------------- | -------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- | -| `name` | `string` | none | MCP server name exposed during initialization. | -| `version` | `string` | none | MCP server version exposed during initialization. | -| `sessionIdGenerator` | `(() => string) \| undefined` | built-in visible ASCII generator | Generates new session ids. Pass `undefined` to disable sessions entirely. | -| `enableJsonResponse` | `boolean` | `false` | Return `application/json` bodies for `POST` responses instead of `text/event-stream`. | -| `oauth` | `TinyHttpMcpServerOAuthOptions \| undefined` | `undefined` | Enables OAuth protected-resource metadata and bearer-token verification for the MCP endpoint. | +| Option | Type | Default | Description | +| ------------------------------ | -------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- | +| `name` | `string` | none | MCP server name exposed during initialization. | +| `version` | `string` | none | MCP server version exposed during initialization. | +| `validateToolArguments` | `boolean` | `true` | Validate tool call arguments against each tool input schema. | +| `supportNotifications` | `boolean` | `true` | Advertise tools/prompts/resources list-change notifications. | +| `supportResourceSubscriptions` | `boolean` | `true` | Advertise resource subscription support and enable resource update notifications. | +| `sessionIdGenerator` | `(() => string) \| undefined` | built-in visible ASCII generator | Generates new session ids. Pass `undefined` to disable sessions entirely. | +| `enableJsonResponse` | `boolean` | `false` | Return `application/json` bodies for `POST` responses instead of `text/event-stream`. | +| `oauth` | `TinyHttpMcpServerOAuthOptions \| undefined` | `undefined` | Enables OAuth protected-resource metadata and bearer-token verification for the MCP endpoint. | ### `createExpressMiddleware(server)` @@ -442,6 +448,7 @@ Creates a ready-made `HttpServer` for integration and conformance tests. It incl - `get_image`, `get_audio`, `get_file`, `get_mixed` — binary/resource content blocks - `throw_sync`, `throw_async` — error handling scenarios - `empty_result`, `slow`, `large_output` — edge-case coverage +- prompt/resource fixtures for `prompts/list`, `prompts/get`, `resources/list`, `resources/read`, resource templates, subscriptions, and list/update notifications Supported options: diff --git a/packages/tiny-stdio-mcp-server/README.md b/packages/tiny-stdio-mcp-server/README.md index 394801f2e4..85633d1b9e 100644 --- a/packages/tiny-stdio-mcp-server/README.md +++ b/packages/tiny-stdio-mcp-server/README.md @@ -1,6 +1,6 @@ # tiny-stdio-mcp-server -Minimal [Model Context Protocol](https://modelcontextprotocol.io) server for Node.js. Zero runtime dependencies, type-safe tool definitions, rich content helpers for images/audio/files. +Minimal [Model Context Protocol](https://modelcontextprotocol.io) server for Node.js. Zero runtime dependencies, type-safe tool definitions, prompt and resource registries, rich content helpers for images/audio/files. ## Install @@ -14,7 +14,7 @@ npm install tiny-stdio-mcp-server import { createServer, defineSchema } from "tiny-stdio-mcp-server"; const schema = defineSchema({ - text: { type: "string", description: "Text to reverse" }, + text: { type: "string", description: "Text to reverse" } }); createServer({ name: "my-server", version: "1.0.0" }) @@ -49,7 +49,7 @@ Register a tool. The handler receives typed args matching the schema and returns ```ts const schema = defineSchema({ query: { type: "string", description: "Search query" }, - limit: { type: "number", description: "Max results", optional: true }, + limit: { type: "number", description: "Max results", optional: true } }); server.tool("search", "Search for things", schema, async ({ query, limit }) => { @@ -58,6 +58,50 @@ server.tool("search", "Search for things", schema, async ({ query, limit }) => { }); ``` +### `.prompt(definition, handler)` + +Register a reusable MCP prompt. Prompt arguments arrive as strings and required +arguments declared in `definition.arguments` are validated before the handler +runs. + +```ts +server.prompt( + { + name: "review", + description: "Create a code review prompt", + arguments: [{ name: "diff", required: true }] + }, + ({ diff }) => ({ + messages: [ + { + role: "user", + content: { type: "text", text: `Review this diff:\n${diff}` } + } + ] + }) +); +``` + +Clients call `prompts/list` and `prompts/get` to discover and render prompts. + +### `.resource(definition, handler)` / `.resourceTemplate(definition, handler)` + +Register static resources by URI or templated resources by URI template. +Handlers return MCP `contents` with either `text` or base64 `blob` payloads. + +```ts +server + .resource({ uri: "memo://welcome", name: "welcome", mimeType: "text/plain" }, () => ({ + contents: [{ uri: "memo://welcome", mimeType: "text/plain", text: "Welcome" }] + })) + .resourceTemplate({ uriTemplate: "memo://{id}", name: "memo" }, (uri) => ({ + contents: [{ uri, mimeType: "text/plain", text: `Loaded ${uri}` }] + })); +``` + +Clients call `resources/list`, `resources/templates/list`, `resources/read`, +`resources/subscribe`, and `resources/unsubscribe`. + ### `.listen()` Start listening on stdin/stdout (standard MCP stdio transport). @@ -82,9 +126,14 @@ Connect using an SDK-compatible in-memory transport (for testing). await server.connectSDK(sdkTransport); ``` -### `.removeTool(name)` / `.notifyToolsChanged()` +### Dynamic registries and notifications -Dynamically add/remove tools at runtime and notify connected clients. +Use `.removeTool(name)`, `.removePrompt(name)`, `.removeResource(uri)`, and +`.removeResourceTemplate(uriTemplate)` to mutate registries at runtime. After a +change, notify initialized clients with `.notifyToolsChanged()`, +`.notifyPromptsChanged()`, `.notifyResourcesChanged()`, or +`.notifyResourceUpdated(uri)`. Resource update notifications are sent only to +clients subscribed to that URI. ## `defineSchema(definition)` @@ -93,13 +142,28 @@ Type-safe schema builder. Returns a JSON Schema object with inferred TypeScript ```ts const schema = defineSchema({ name: { type: "string", description: "User name" }, - age: { type: "number", description: "User age", optional: true }, + age: { type: "number", description: "User age", optional: true } }); // Handler receives: { name: string; age?: number } ``` Supported types: `string`, `number`, `boolean`, `object`, `array`. +## Configuration + +`createServer()` accepts these options: + +| Option | Default | Description | +| ------------------------------ | ------- | ------------------------------------------------------------------------- | +| `name` | none | MCP server name exposed during initialization. | +| `version` | none | MCP server version exposed during initialization. | +| `validateToolArguments` | `true` | Validate tool arguments against each tool input schema. | +| `supportNotifications` | `true` | Advertise list-change notifications for tools, prompts, and resources. | +| `supportResourceSubscriptions` | `true` | Advertise resource subscription support and enable `resources/subscribe`. | + +The server advertises MCP protocol `2025-11-25` by default and also accepts +clients requesting `2025-03-26` or `2025-06-18`. + ## Content helpers Tool handlers can return rich content beyond plain text. @@ -162,8 +226,12 @@ Use `createTestPair` with the official MCP SDK for in-memory testing: ```ts import { createTestPair } from "tiny-stdio-mcp-server/testing"; -const server = createServer({ name: "test", version: "1.0.0" }) - .tool("ping", "Ping", defineSchema({}), () => "pong"); +const server = createServer({ name: "test", version: "1.0.0" }).tool( + "ping", + "Ping", + defineSchema({}), + () => "pong" +); const { client, cleanup } = await createTestPair(server); @@ -175,6 +243,11 @@ await cleanup(); Requires `@modelcontextprotocol/sdk` as a dev dependency. +## Environment Variables + +This package does not use any environment variables. All runtime configuration +is passed through `createServer()` options and registry methods. + ## License MIT diff --git a/scripts/README.md b/scripts/README.md index 659ee4337e..c96e42a452 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -16,11 +16,11 @@ npm run screenshot-poe-code -- [args...] ### Options -| Option | Description | -|--------|-------------| +| Option | Description | +| --------------------- | -------------------------------------------------------------- | | `-o, --output ` | Custom output file path (default: `screenshots/.png`) | -| `--no-header` | Skip the `% command args` header line | -| `--poe-code` | Run via `npm run dev` with TTY emulation | +| `--no-header` | Skip the `% command args` header line | +| `--poe-code` | Run via `npm run dev` with TTY emulation | ### How It Works @@ -49,15 +49,15 @@ Supported key tokens include `up`, `down`, `left`, `right`, `shift-up`, `shift-d The tool kills the spawned process after a timeout and saves whatever output was captured up to that point. -| Variable | Default | Description | -|----------|---------|-------------| -| `POE_SCREENSHOT_TIMEOUT_MS` | `60000` (60s) | Maximum time to wait for the command to exit | -| `POE_SCREENSHOT_PTY` | unset | Set to `1` to capture the visible PTY screen instead of piped transcript output | -| `POE_SCREENSHOT_COLUMNS` | `120` in PTY mode, `80` for TTY emulation | Terminal width for PTY or forced-TTY captures | -| `POE_SCREENSHOT_ROWS` | `40` in PTY mode, `24` for TTY emulation | Terminal height for PTY or forced-TTY captures | -| `POE_SCREENSHOT_KEYS` | unset | Comma-separated key tokens to send before capture | -| `POE_SCREENSHOT_KEY_DELAY_MS` | `250` | Delay before sending the first key | -| `POE_SCREENSHOT_KEY_INTERVAL_MS` | `75` | Delay between sent keys | +| Variable | Default | Description | +| -------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------- | +| `POE_SCREENSHOT_TIMEOUT_MS` | `60000` (60s) | Maximum time to wait for the command to exit | +| `POE_SCREENSHOT_PTY` | unset | Set to `1` to capture the visible PTY screen instead of piped transcript output | +| `POE_SCREENSHOT_COLUMNS` | `120` in PTY mode, `80` for TTY emulation | Terminal width for PTY or forced-TTY captures | +| `POE_SCREENSHOT_ROWS` | `40` in PTY mode, `24` for TTY emulation | Terminal height for PTY or forced-TTY captures | +| `POE_SCREENSHOT_KEYS` | unset | Comma-separated key tokens to send before capture | +| `POE_SCREENSHOT_KEY_DELAY_MS` | `250` | Delay before sending the first key | +| `POE_SCREENSHOT_KEY_INTERVAL_MS` | `75` | Delay between sent keys | ```bash # Short timeout for fast commands @@ -79,3 +79,33 @@ The tool forces color output regardless of the user's terminal settings: - `POE_NO_SPINNER=1` - disables animated spinners When `--poe-code` is used, `force-tty.cjs` is injected via `NODE_OPTIONS --require` to emulate a TTY environment (sets `isTTY`, `columns=80`, `rows=24`). + +## Release Helpers + +### `prepare-lockstep-release.mjs` + +Sets one concrete semantic version across a lockstep release group and rewrites +all intra-group `dependencies`, `peerDependencies`, and `optionalDependencies` +to that same version. The script is driven by environment variables and is +usually invoked through `.github/actions/prepare-lockstep-release` from release +workflows. + +| Variable | Description | +| --------------------------- | ------------------------------------------------------- | +| `LOCKSTEP_RELEASE_VERSION` | Concrete semver version to write. | +| `LOCKSTEP_RELEASE_PACKAGES` | JSON array of package directories in the release group. | + +### `set-bin-executable.mjs` + +Restores mode `0755` on every file declared in a package `bin` field. Run it +from a package `prepack` script after building so binaries emitted by `tsc` ship +with executable bits. Progress is written to stderr to keep `npm pack --json` +stdout parseable. + +```json +{ + "scripts": { + "prepack": "npm run build && node ../../scripts/set-bin-executable.mjs" + } +} +``` From 18699d1353b3ec0ef30f3107a09baf7aef1103c5 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 00:38:28 +0000 Subject: [PATCH 05/10] docs: document recent prompt and approval updates --- packages/agent-spawn/README.md | 6 +++++- packages/config-extends/README.md | 3 +++ packages/design-system/README.md | 9 ++++++++- packages/toolcraft/README.md | 9 ++++++--- 4 files changed, 22 insertions(+), 5 deletions(-) diff --git a/packages/agent-spawn/README.md b/packages/agent-spawn/README.md index 5d0000b171..0e7930e9ce 100644 --- a/packages/agent-spawn/README.md +++ b/packages/agent-spawn/README.md @@ -35,6 +35,10 @@ Mode-specific args and env vars are declared in each agent config. Goose uses `G Pass `mcpServers` as a map of server names to `{ command, args?, env?, timeout? }`. The package serializes that declarative config into the agent-specific CLI args or environment variables. `listMcpSupportedAgents()` reports the current agents with spawn-time MCP support. +## Prompt transport + +Agents with stdin support can receive prompts through stdin by passing `useStdin: true`. When an agent config allows automatic fallback, prompts larger than 64 KiB, or prompts containing NUL bytes, are sent through stdin instead of as a CLI argument. Provider configs can opt out of the large-prompt automatic fallback when their stdin protocol requires a different payload format. + ## Autonomous streaming `spawnAutonomous(streamSpawn, options)` drives a streaming ACP spawn to completion, renders events through the design-system ACP writer, and retries activity timeouts. It is shared by SDK autonomous spawn flows and loop runners. @@ -83,7 +87,7 @@ vi.mock("@poe-code/agent-spawn", spawnMock.factory); | `args` | `string[]` | Extra args forwarded to the agent process. | | `mcpServers` | `Record` | MCP servers injected into the spawned agent. | | `middlewares` | `AcpMiddleware[]` | Wrap `spawnStreaming`/`spawnAcp` execution for telemetry, logging, or post-processing. | -| `useStdin` | `boolean` | Send the prompt through stdin when the agent supports it. | +| `useStdin` | `boolean` | Force stdin prompt transport when the agent supports it. | | `interactive` | `boolean` | Spawn the agent in interactive TUI mode. | | `activityTimeoutMs` | `number` | Kill/retry inactive streaming processes after this many milliseconds. | | `logPath` / `logDir` / `logFileName` | `string` | Persist spawn logs. `logPath` takes precedence. | diff --git a/packages/config-extends/README.md b/packages/config-extends/README.md index 941925757a..61638da978 100644 --- a/packages/config-extends/README.md +++ b/packages/config-extends/README.md @@ -18,6 +18,7 @@ A chain must contain exactly one document layer. Data layers before and after th - With `autoExtend: true`, documents that do not set `extends` try to inherit from matching bases automatically. - Optional auto-extend discovery is ignored when it finds the document itself, so a document can safely live in a configured base directory without creating a circular extends error. - Prompt values can compose with the `{{yield}}` token across resolved base layers. +- Prompt partials such as `{{> shared-rules}}` are loaded from prompt document directories, expanded before rendering, and included in the resolved `chain`. ## Environment variables @@ -29,6 +30,8 @@ This package does not read or expose any environment variables. - `fs`: file system implementation with `readFile(path, encoding)` - `autoExtend?`: automatically inherit from bases even when a document does not set `extends: true` +- `view?`: values used for one-pass prompt template rendering +- `validate?`: fail when prompt rendering references variables missing from `view` ### `ResolvePromptDocumentInput` diff --git a/packages/design-system/README.md b/packages/design-system/README.md index dc5e192c61..02dc48a8fe 100644 --- a/packages/design-system/README.md +++ b/packages/design-system/README.md @@ -8,7 +8,8 @@ Shared terminal UI components, themes, prompt primitives, and static renderers f - `helpFormatter`: usage, command, and option formatting for CLI help. - `renderTable`: tabular and detail-style row rendering. - `renderDetailCard`: title, subtitle, prose, badge, section, and label/value rendering for rich command results. -- `renderTemplate`: Mustache-backed text rendering with configured escaping. +- `renderTemplate`: Mustache-backed text rendering with configured escaping, optional validation, `{{yield}}`, and Markdown-style partial expansion. +- `getTemplatePartialNames` / `resolveTemplatePartials`: inspect and expand `{{> partial}}` references for prompt-document callers. - `prompts`: themed select, multiselect, text, password, confirm, spinner, and note helpers. - `dashboard` / `explorer`: interactive terminal layouts. - `terminal-markdown`: Markdown parsing and terminal rendering. @@ -38,6 +39,12 @@ const output = renderDetailCard({ The renderer wraps long values, aligns labels, formats optional prose blocks, and skips empty sections. +## Template rendering + +`renderTemplate(template, view, options)` supports normal escaped variables, triple-mustache unescaped variables, sections, inverted sections, lambdas, `{{yield}}`, and partial tags such as `{{> shared-rules}}`. Pass `partials` as a name-to-template map. Set `validate: true` to fail when a referenced variable is missing from the active view. + +`getTemplatePartialNames(template)` returns the partial names referenced by a template. `resolveTemplatePartials(template, partials)` expands partials recursively and reports missing, circular, or too-deep partial graphs. + ## Environment variables | Env var | Behavior | diff --git a/packages/toolcraft/README.md b/packages/toolcraft/README.md index b81171d154..41adce8262 100644 --- a/packages/toolcraft/README.md +++ b/packages/toolcraft/README.md @@ -357,7 +357,9 @@ A built-in `approvals` group is auto-merged into every root: - `approvals show --approval-id ` — show one task. - `approvals run --approval-id ` — execute one queued task. CLI-only; used by the detached runner. -The name `approvals` is reserved. Defining your own `approvals` group fails at startup. +Pass `approvals: false` to `runCLI`, `createMCPServer`/`runMCP`, or `createSDK` to omit these approval-management commands while keeping `humanInLoop` execution behavior available for commands that request approval. + +The name `approvals` is reserved when the built-in group is enabled. Defining your own `approvals` group fails at startup. The async runner re-execs your binary (`process.execPath` + `process.argv[1]` by default; override via `humanInLoop.binPath`). Re-exec calls the same toolcraft entrypoint with the same `humanInLoop` options — do not branch on `argv` before calling `runCLI`/`runMCP`/`createSDK`. @@ -465,20 +467,21 @@ If you have an existing MCP server you want to keep running, use the MCP proxy: - `presets?: boolean` — enables `--preset ` for loading parameter defaults from JSON files. - `apiVersion?: string` — for `requires.apiVersion`. - `humanInLoop?: HumanInLoopRuntimeOptions` +- `approvals?: boolean` — set to `false` to omit the built-in approval-management commands. - `errorReports?: boolean | { dir?: string }` - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`). ### `createSDK(root, options)` - `casing?: "camel"` — generated SDK member style. -- `services?` / `humanInLoop?` / `apiVersion?` / `errorReports?` +- `services?` / `humanInLoop?` / `apiVersion?` / `approvals?` / `errorReports?` - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`). ### `createMCPServer(root, options)` / `runMCP(root, options)` - `name: string` - `version: string` -- `services?` / `humanInLoop?` / `apiVersion?` / `errorReports?` +- `services?` / `humanInLoop?` / `apiVersion?` / `approvals?` / `errorReports?` - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`). - `tools?: string[]` — allowlist of MCP tool names or group prefixes. Tool names are `__`-joined snake_case path segments (`root__bot__create`); a prefix like `root__bot` includes every descendant tool. - `omitRootToolNamePrefix?: boolean` — defaults to `false`. Set to `true` to omit the root group name from single-root MCP tool names (`bot__create`). From fc7b45e912ea90c3f92bac4b5e516e539eee8187 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 00:45:03 +0000 Subject: [PATCH 06/10] test(e2e): pass explicit spawn modes --- e2e/goose.test.ts | 60 +++++++++++++++++++++++--------------------- e2e/mcp-tool.test.ts | 58 +++++++++++++++++++++--------------------- e2e/opencode.test.ts | 50 ++++++++++++++++++------------------ 3 files changed, 86 insertions(+), 82 deletions(-) diff --git a/e2e/goose.test.ts b/e2e/goose.test.ts index 87595bb887..ac0abd5a1e 100644 --- a/e2e/goose.test.ts +++ b/e2e/goose.test.ts @@ -1,33 +1,33 @@ -import path from 'path'; -import { describe, it, expect, beforeAll, beforeEach } from 'vitest'; -import { execSync } from 'child_process'; -import { parse as parseYaml } from 'yaml'; -import { useContainer } from '@poe-code/e2e-test-runner'; -import { DEFAULT_GOOSE_MODEL } from '../src/cli/constants.js'; +import path from "path"; +import { describe, it, expect, beforeAll, beforeEach } from "vitest"; +import { execSync } from "child_process"; +import { parse as parseYaml } from "yaml"; +import { useContainer } from "@poe-code/e2e-test-runner"; +import { DEFAULT_GOOSE_MODEL } from "../src/cli/constants.js"; -const bin = path.resolve(__dirname, '..', 'dist', 'bin.cjs'); +const bin = path.resolve(__dirname, "..", "dist", "bin.cjs"); -describe('goose', () => { - const container = useContainer({ testName: 'goose' }); +describe("goose", () => { + const container = useContainer({ testName: "goose" }); beforeAll(() => { - execSync(`node ${bin} install goose`, { stdio: 'pipe' }); + execSync(`node ${bin} install goose`, { stdio: "pipe" }); }); beforeEach(async () => { - const installResult = await container.exec('poe-code install goose'); + const installResult = await container.exec("poe-code install goose"); expect(installResult).toHaveExitCode(0); }); - it('configure and test', async () => { - const configureResult = await container.exec('poe-code configure goose --yes'); + it("configure and test", async () => { + const configureResult = await container.exec("poe-code configure goose --yes"); expect(configureResult).toHaveExitCode(0); await expect(container).toHaveFile(`${container.home}/.config/goose/config.yaml`); const config = parseYaml( await container.readFile(`${container.home}/.config/goose/config.yaml`) ) as Record; - expect(config.GOOSE_PROVIDER).toBe('custom_poe'); + expect(config.GOOSE_PROVIDER).toBe("custom_poe"); expect(config.GOOSE_MODEL).toBe(DEFAULT_GOOSE_MODEL); await expect(container).toHaveFile( @@ -36,42 +36,44 @@ describe('goose', () => { const provider = JSON.parse( await container.readFile(`${container.home}/.config/goose/custom_providers/custom_poe.json`) ) as Record; - expect(provider.name).toBe('custom_poe'); - expect(provider.api_key_env).toBe('CUSTOM_POE_API_KEY'); - expect(provider.base_url).toBe('https://api.poe.com/v1/chat/completions'); + expect(provider.name).toBe("custom_poe"); + expect(provider.api_key_env).toBe("CUSTOM_POE_API_KEY"); + expect(provider.base_url).toBe("https://api.poe.com/v1/chat/completions"); expect(provider.headers).toBeUndefined(); await expect(container).toHaveFile(`${container.home}/.config/goose/secrets.yaml`); const secrets = parseYaml( await container.readFile(`${container.home}/.config/goose/secrets.yaml`) ) as Record; - expect(secrets.CUSTOM_POE_API_KEY).toBeTypeOf('string'); + expect(secrets.CUSTOM_POE_API_KEY).toBeTypeOf("string"); - const testResult = await container.exec('env -u POE_API_KEY poe-code test goose'); - expect(testResult).toSucceedWith('Tested Goose.'); + const testResult = await container.exec("env -u POE_API_KEY poe-code test goose"); + expect(testResult).toSucceedWith("Tested Goose."); }); - it('test --isolated', async () => { - const result = await container.exec('poe-code test goose --isolated'); - expect(result).toSucceedWith('Tested Goose.'); + it("test --isolated", async () => { + const result = await container.exec("poe-code test goose --isolated"); + expect(result).toSucceedWith("Tested Goose."); - await expect(container).toHaveFile(`${container.home}/.poe-code/goose/.config/goose/secrets.yaml`); + await expect(container).toHaveFile( + `${container.home}/.poe-code/goose/.config/goose/secrets.yaml` + ); const isolatedSecrets = parseYaml( await container.readFile(`${container.home}/.poe-code/goose/.config/goose/secrets.yaml`) ) as Record; - expect(isolatedSecrets.CUSTOM_POE_API_KEY).toBeTypeOf('string'); + expect(isolatedSecrets.CUSTOM_POE_API_KEY).toBeTypeOf("string"); }); - it('spawn creates a file', async () => { - const configureResult = await container.exec('poe-code configure goose --yes'); + it("spawn creates a file", async () => { + const configureResult = await container.exec("poe-code configure goose --yes"); expect(configureResult).toHaveExitCode(0); const prompt = `Create a file called ${container.workspace}/spawn-test.txt with the exact content: hello`; - const spawnResult = await container.exec(`poe-code spawn goose "${prompt}"`); + const spawnResult = await container.exec(`poe-code spawn goose "${prompt}" --mode yolo`); expect(spawnResult).toHaveExitCode(0); await expect(container).toHaveFile(`${container.workspace}/spawn-test.txt`); const content = await container.readFile(`${container.workspace}/spawn-test.txt`); - expect(content).toContain('hello'); + expect(content).toContain("hello"); }); }); diff --git a/e2e/mcp-tool.test.ts b/e2e/mcp-tool.test.ts index 374f76504d..24e0c75e43 100644 --- a/e2e/mcp-tool.test.ts +++ b/e2e/mcp-tool.test.ts @@ -1,5 +1,5 @@ -import { describe, it, expect, beforeEach } from 'vitest'; -import { useContainer, shellQuote } from '@poe-code/e2e-test-runner'; +import { describe, it, expect, beforeEach } from "vitest"; +import { useContainer, shellQuote } from "@poe-code/e2e-test-runner"; interface AgentMcpSpawnTest { name: string; @@ -9,37 +9,39 @@ interface AgentMcpSpawnTest { const agents: AgentMcpSpawnTest[] = [ { - name: 'claude-code', + name: "claude-code", expectSpawnSuccess: true, // Claude requires explicit tool permission for MCP tools. - spawnArgs: ['--allowedTools', 'Bash,Read,mcp__tiny-stdio-mcp-test-server__word_of_the_day'], + spawnArgs: ["--allowedTools", "Bash,Read,mcp__tiny-stdio-mcp-test-server__word_of_the_day"] }, { - name: 'codex', - expectSpawnSuccess: true, + name: "codex", + expectSpawnSuccess: true }, { - name: 'opencode', - expectSpawnSuccess: true, + name: "opencode", + expectSpawnSuccess: true }, { - name: 'kimi', - expectSpawnSuccess: true, + name: "kimi", + expectSpawnSuccess: true }, { - name: 'goose', - expectSpawnSuccess: true, - }, + name: "goose", + expectSpawnSuccess: true + } ]; -const mcpConfig = shellQuote(JSON.stringify({ - 'tiny-stdio-mcp-test-server': { - command: 'tiny-stdio-mcp-test-server', - args: ['serve', 'word-of-the-day'], - }, -})); +const mcpConfig = shellQuote( + JSON.stringify({ + "tiny-stdio-mcp-test-server": { + command: "tiny-stdio-mcp-test-server", + args: ["serve", "word-of-the-day"] + } + }) +); -describe.each(agents)('spawn --mcp-config: $name', ({ name, expectSpawnSuccess, spawnArgs }) => { +describe.each(agents)("spawn --mcp-config: $name", ({ name, expectSpawnSuccess, spawnArgs }) => { const container = useContainer({ testName: `spawn-mcp-${name}` }); beforeEach(async () => { @@ -47,26 +49,24 @@ describe.each(agents)('spawn --mcp-config: $name', ({ name, expectSpawnSuccess, expect(installResult).toHaveExitCode(0); }); - it('uses tiny MCP server and validates output', async () => { + it("uses tiny MCP server and validates output", async () => { const configResult = await container.exec(`poe-code configure ${name} --yes`); expect(configResult).toHaveExitCode(0); - const prompt = 'Call the word_of_the_day tool and return only the exact tool output.'; - const extraArgs = spawnArgs - ? ` -- ${spawnArgs.map((arg) => shellQuote(arg)).join(' ')}` - : ''; - const command = `poe-code spawn --mcp-config ${mcpConfig} ${name} ${shellQuote(prompt)}${extraArgs}`; + const prompt = "Call the word_of_the_day tool and return only the exact tool output."; + const extraArgs = spawnArgs ? ` -- ${spawnArgs.map((arg) => shellQuote(arg)).join(" ")}` : ""; + const command = `poe-code spawn --mcp-config ${mcpConfig} ${name} ${shellQuote(prompt)} --mode yolo${extraArgs}`; const spawnResult = await container.exec(command); if (!expectSpawnSuccess) { expect(spawnResult).toFail(); - expect(spawnResult).toHaveStderr('does not support MCP servers at spawn time'); - expect(spawnResult).toHaveStderr('claude-code, codex, kimi'); + expect(spawnResult).toHaveStderr("does not support MCP servers at spawn time"); + expect(spawnResult).toHaveStderr("claude-code, codex, kimi"); return; } expect(spawnResult).toHaveExitCode(0); const output = `${spawnResult.stdout}\n${spawnResult.stderr}`.toLowerCase(); - expect(output).toContain('bumfuzzle'); + expect(output).toContain("bumfuzzle"); }); }); diff --git a/e2e/opencode.test.ts b/e2e/opencode.test.ts index 9440214737..bb2c8e0921 100644 --- a/e2e/opencode.test.ts +++ b/e2e/opencode.test.ts @@ -1,62 +1,64 @@ -import { describe, it, expect, beforeEach } from 'vitest'; -import { useContainer } from '@poe-code/e2e-test-runner'; +import { describe, it, expect, beforeEach } from "vitest"; +import { useContainer } from "@poe-code/e2e-test-runner"; -describe('opencode', () => { - const container = useContainer({ testName: 'opencode' }); +describe("opencode", () => { + const container = useContainer({ testName: "opencode" }); beforeEach(async () => { - const installResult = await container.exec('poe-code install opencode'); + const installResult = await container.exec("poe-code install opencode"); expect(installResult).toHaveExitCode(0); }); - it('configure and test', async () => { - const result = await container.exec('poe-code configure opencode --yes'); + it("configure and test", async () => { + const result = await container.exec("poe-code configure opencode --yes"); expect(result).toHaveExitCode(0); await expect(container).toHaveFile(`${container.home}/.config/opencode/config.json`); const raw = await container.readFile(`${container.home}/.config/opencode/config.json`); const config = JSON.parse(raw); - expect(config).toHaveProperty('model'); - expect(config).toHaveProperty('enabled_providers'); + expect(config).toHaveProperty("model"); + expect(config).toHaveProperty("enabled_providers"); await expect(container).toHaveFile(`${container.home}/.local/share/opencode/auth.json`); const authRaw = await container.readFile(`${container.home}/.local/share/opencode/auth.json`); const auth = JSON.parse(authRaw); - expect(auth).toHaveProperty('poe.type'); - expect(auth).toHaveProperty('poe.key'); + expect(auth).toHaveProperty("poe.type"); + expect(auth).toHaveProperty("poe.key"); - const testResult = await container.exec('poe-code test opencode'); - expect(testResult).toSucceedWith('Tested OpenCode CLI.'); + const testResult = await container.exec("poe-code test opencode"); + expect(testResult).toSucceedWith("Tested OpenCode CLI."); }); - it('test --isolated', async () => { - const result = await container.exec('poe-code test opencode --isolated'); - expect(result).toSucceedWith('Tested OpenCode CLI.'); + it("test --isolated", async () => { + const result = await container.exec("poe-code test opencode --isolated"); + expect(result).toSucceedWith("Tested OpenCode CLI."); }); - it('spawn creates a file', async () => { - const configResult = await container.exec('poe-code configure opencode --yes'); + it("spawn creates a file", async () => { + const configResult = await container.exec("poe-code configure opencode --yes"); expect(configResult).toHaveExitCode(0); const prompt = `Create a file called ${container.workspace}/spawn-test.txt with the exact content: hello`; - const spawnResult = await container.exec(`poe-code spawn opencode "${prompt}"`); + const spawnResult = await container.exec(`poe-code spawn opencode "${prompt}" --mode yolo`); expect(spawnResult).toHaveExitCode(0); await expect(container).toHaveFile(`${container.workspace}/spawn-test.txt`); const content = await container.readFile(`${container.workspace}/spawn-test.txt`); - expect(content).toContain('hello'); + expect(content).toContain("hello"); }); - it('spawn creates a file with gpt-5.2', async () => { - const configResult = await container.exec('poe-code configure opencode --yes'); + it("spawn creates a file with gpt-5.2", async () => { + const configResult = await container.exec("poe-code configure opencode --yes"); expect(configResult).toHaveExitCode(0); const prompt = `Create a file called ${container.workspace}/spawn-gpt-test.txt with the exact content: hello`; - const spawnResult = await container.exec(`poe-code spawn opencode "${prompt}" --model openai/gpt-5.2`); + const spawnResult = await container.exec( + `poe-code spawn opencode "${prompt}" --model openai/gpt-5.2 --mode yolo` + ); expect(spawnResult).toHaveExitCode(0); await expect(container).toHaveFile(`${container.workspace}/spawn-gpt-test.txt`); const content = await container.readFile(`${container.workspace}/spawn-gpt-test.txt`); - expect(content).toContain('hello'); + expect(content).toContain("hello"); }); }); From dcea300e1f2d532256c25d23e7849f30010d1a41 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 00:53:42 +0000 Subject: [PATCH 07/10] test(e2e): use stable opencode health model --- e2e/opencode.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/e2e/opencode.test.ts b/e2e/opencode.test.ts index bb2c8e0921..831952f68a 100644 --- a/e2e/opencode.test.ts +++ b/e2e/opencode.test.ts @@ -25,12 +25,12 @@ describe("opencode", () => { expect(auth).toHaveProperty("poe.type"); expect(auth).toHaveProperty("poe.key"); - const testResult = await container.exec("poe-code test opencode"); + const testResult = await container.exec("poe-code test opencode --model openai/gpt-5.2"); expect(testResult).toSucceedWith("Tested OpenCode CLI."); }); it("test --isolated", async () => { - const result = await container.exec("poe-code test opencode --isolated"); + const result = await container.exec("poe-code test opencode --isolated --model openai/gpt-5.2"); expect(result).toSucceedWith("Tested OpenCode CLI."); }); From 5ea95daab5c9ce794a7387b25a8f0ff44d50fe24 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 01:04:02 +0000 Subject: [PATCH 08/10] fix(opencode): stabilize health check output --- src/providers/opencode.ts | 3 ++- src/providers/providers.test.ts | 4 ++-- src/utils/command-checks.ts | 5 +++-- src/utils/utils.test.ts | 19 +++++++++++++++++++ 4 files changed, 26 insertions(+), 5 deletions(-) diff --git a/src/providers/opencode.ts b/src/providers/opencode.ts index d7b05e92a0..28b5b7fcf7 100644 --- a/src/providers/opencode.ts +++ b/src/providers/opencode.ts @@ -148,7 +148,8 @@ export const openCodeService = createProvider({ return context.runCheck( createSpawnHealthCheck("opencode", { model: context.model, - expectedOutput: "OPEN_CODE_OK" + prompt: "Output exactly: OPEN_CODE_OK", + expectedOutput: '"type":"step_start"' }) ); }, diff --git a/src/providers/providers.test.ts b/src/providers/providers.test.ts index 3a6e466abc..42ee22fcca 100644 --- a/src/providers/providers.test.ts +++ b/src/providers/providers.test.ts @@ -1707,7 +1707,7 @@ describe("opencode service", () => { it("runs the OpenCode health check via runCommand when test is invoked", async () => { const runCommand = vi.fn().mockResolvedValue({ - stdout: '{"type":"text","text":"OPEN_CODE_OK"}\n', + stdout: '{"type":"step_start"}\n', stderr: "", exitCode: 0 }); @@ -1751,7 +1751,7 @@ describe("opencode service", () => { }); const { context } = createProviderTestContext(runCommand); - await expect(opencodeService.openCodeService.test?.(context)).rejects.toThrow(/OPEN_CODE_OK/); + await expect(opencodeService.openCodeService.test?.(context)).rejects.toThrow(/step_start/); }); }); diff --git a/src/utils/command-checks.ts b/src/utils/command-checks.ts index 56d3ace4f6..9ce298cd56 100644 --- a/src/utils/command-checks.ts +++ b/src/utils/command-checks.ts @@ -149,6 +149,7 @@ export function createSpawnHealthCheck( agentId: string, options: { model?: string; + prompt?: string; expectedOutput: string; hooks?: HookBridgeOptions; invocation?: { command: string; args: string[]; env?: Record }; @@ -171,7 +172,7 @@ export function createSpawnHealthCheck( "--mode", "yolo", agentId, - `Output exactly: ${options.expectedOutput}` + options.prompt ?? `Output exactly: ${options.expectedOutput}` ], env: undefined } @@ -182,7 +183,7 @@ export function createSpawnHealthCheck( env: options.invocation.env } : buildSpawnArgs(agentId, { - prompt: `Output exactly: ${options.expectedOutput}`, + prompt: options.prompt ?? `Output exactly: ${options.expectedOutput}`, model: options.model, mode: "yolo" }); diff --git a/src/utils/utils.test.ts b/src/utils/utils.test.ts index 58614a6b6a..dc8bb9c215 100644 --- a/src/utils/utils.test.ts +++ b/src/utils/utils.test.ts @@ -462,6 +462,25 @@ describe("createSpawnHealthCheck", () => { ); }); + it("allows health checks to use a prompt that differs from the expected output", async () => { + const runCommand = vi.fn().mockResolvedValue({ + stdout: '{"type":"step_start"}\n', + stderr: "", + exitCode: 0 + }); + + const check = createSpawnHealthCheck("opencode", { + prompt: "Output exactly: OPEN_CODE_OK", + expectedOutput: '"type":"step_start"' + }); + await check.run({ isDryRun: false, runCommand }); + + expect(runCommand).toHaveBeenCalledWith( + "opencode", + expect.arrayContaining(["run", "Output exactly: OPEN_CODE_OK"]) + ); + }); + it("runs hook-enabled health checks through poe-code spawn", async () => { const runCommand = vi.fn().mockResolvedValue({ stdout: [ From 5e9316f1c99cec3c828415574c4895a91fad03ec Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Wed, 10 Jun 2026 00:42:04 +0000 Subject: [PATCH 09/10] docs: document recent package updates --- docs/README_FULL.md | 10 ++++++++ packages/agent-harness/README.md | 2 ++ packages/agent-maestro/README.md | 15 ++++++------ packages/agent-script/README.md | 34 ++++++++++++++++++---------- packages/task-list/README.md | 12 ++++++++++ packages/toolcraft-design/README.md | 3 ++- packages/toolcraft-openapi/README.md | 19 ++++++++++++++-- 7 files changed, 73 insertions(+), 22 deletions(-) diff --git a/docs/README_FULL.md b/docs/README_FULL.md index 36a9b92218..b070730cb5 100644 --- a/docs/README_FULL.md +++ b/docs/README_FULL.md @@ -399,6 +399,10 @@ poe-code spawn [prompt] [agentArgs...] | `--resume-thread-id ` | None | Resume a prior provider thread/session before sending the prompt. | | `--log-dir ` | Default log dir | Directory override for ACP JSONL spawn logs. | | `--log-file-name ` | Generated | Filename override for the spawn log. Requires `--log-dir`. | +| `--log-content` | `false` | Include message and tool content in ACP JSONL spawn logs. Logs are redacted by default. | +| `--capture-otel` | `false` | Capture native OpenTelemetry emitted by the spawned agent when supported. | +| `--capture-otel-content` | `false` | Include prompt and tool content in captured native OpenTelemetry. | +| `--activity-timeout-ms ` | None | Kill the agent after this many milliseconds of stdout/stderr inactivity. | | `--mcp-servers ` | None | MCP servers to inject at spawn time. Accepts inline JSON or `@path/to/file.json`. Supports `command`, optional `args`, `env`, and `timeout` (seconds). Deprecated alias: `--mcp-config`. | **Behavior:** @@ -1346,6 +1350,8 @@ interface SpawnOptions { mode?: SpawnMode; /** Additional arguments forwarded to the CLI */ args?: string[]; + /** Environment overrides applied only to this spawned run */ + env?: Record; /** MCP servers passed at spawn time */ mcpServers?: McpSpawnConfig; /** Resume a prior provider thread/session before sending the prompt */ @@ -1356,6 +1362,10 @@ interface SpawnOptions { logFileName?: string; /** Include message/tool content in ACP JSONL logs. Defaults to redacted logs */ logContent?: boolean; + /** Capture native OTLP telemetry emitted internally by the spawned agent */ + captureOtel?: boolean; + /** Include prompt and tool content in native OTLP telemetry */ + captureOtelContent?: boolean; /** Send the prompt over stdin when the provider supports it */ useStdin?: boolean; /** Kill the process after this many milliseconds of stdout/stderr inactivity */ diff --git a/packages/agent-harness/README.md b/packages/agent-harness/README.md index 4f35583fa6..e3d8f04c80 100644 --- a/packages/agent-harness/README.md +++ b/packages/agent-harness/README.md @@ -27,6 +27,8 @@ poe-code harness run harness.md --snapshot-path .poe-code/harnesses/demo/snapsho poe-code harness new coverage-demo coverage.md ``` +When `poe-code harness run` executes real agents, spawn lifecycle events are printed as progress lines. Retryable child-agent failures are retried up to five attempts with backoff; permanent configuration, unsupported-agent, and credential errors fail immediately. + ## Built-in templates `listBuiltinTemplates()` exposes template metadata with `kind`, `mdPath`, and `ajsPath`. `poe-code harness new ` copies both files into a new harness pair. diff --git a/packages/agent-maestro/README.md b/packages/agent-maestro/README.md index d7460ef8f5..13ebccc1d9 100644 --- a/packages/agent-maestro/README.md +++ b/packages/agent-maestro/README.md @@ -52,13 +52,14 @@ State definition fields: -| Field | Type | Default | Behavior | -| ---------- | ---------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- | -| `prompt` | string | unset | Prompt template for this state. Presence makes the state active and eligible for dispatch. | -| `agent` | string | workflow `agent.service` | Agent service for this state. Falls back to the workflow-level `agent.service` when omitted. | -| `model` | string | agent runner default | Model for this state. Falls back to the agent runner's default when omitted. | -| `mode` | `"yolo" \| "edit" \| "read"` | `"yolo"` | Spawn mode for this state. | -| `terminal` | boolean | `false` | Marks this state as terminal. Terminal states are not dispatched and their workspaces are removed. | +| Field | Type | Default | Behavior | +| ---------- | ---------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| `prompt` | string | unset | Prompt template for this state. Presence makes the state active and eligible for dispatch. | +| `agent` | string | workflow `agent.service` | Agent service for this state. Falls back to the workflow-level `agent.service` when omitted. | +| `model` | string | agent runner default | Model for this state. Falls back to the agent runner's default when omitted. | +| `mode` | `"yolo" \| "edit" \| "read"` | `"yolo"` | Spawn mode for this state. | +| `terminal` | boolean | `false` | Marks this state as terminal. Terminal states are not dispatched and their workspaces are removed. | +| `gate` | boolean | `false` | Marks a human approval gate. `poe-code tasks next` and `tasks set-state` will not cross or leave this state unless `--force` is passed. | ### Template variables diff --git a/packages/agent-script/README.md b/packages/agent-script/README.md index 524b834da3..5e132c4c79 100644 --- a/packages/agent-script/README.md +++ b/packages/agent-script/README.md @@ -18,7 +18,7 @@ It is the engine behind Poe Code's pipelines, experiment loops, and superintende Agent-script runs untrusted-by-default code. The interpreter ships **no** `fs`, `exec`, `process`, or network primitives, and there is no escape hatch: no `eval`, no `Function`, no dynamic `import()`, no `globalThis`. A script can only touch the host through modules the caller registers in `run({ modules })`. -When you need filesystem, subprocess, or HTTP capability, build a host module with the *exact* surface you want to expose (the specific paths, commands, or URLs) and register it explicitly. Don't ship a generic `fs` module — narrow the capability to what this harness actually needs. The bundled modules (`agent`, `git`, `harness`, `log`, `metric`, `mcp`, `env`, `time`, `fail`) follow that rule; treat them as the model for anything you add. +When you need filesystem, subprocess, or HTTP capability, build a host module with the _exact_ surface you want to expose (the specific paths, commands, or URLs) and register it explicitly. Don't ship a generic `fs` module — narrow the capability to what this harness actually needs. The bundled modules (`agent`, `git`, `harness`, `log`, `metric`, `mcp`, `env`, `time`, `fail`) follow that rule; treat them as the model for anything you add. ## Scripts are JavaScript @@ -123,21 +123,25 @@ What is **not** available as a global: `Promise` constructor, `Date`, `RegExp`, Method coverage on plain values follows ECMAScript with a few removals: `String#split` / `replace` / `replaceAll` reject regex separators and function replacers, and `Array#sort` only accepts an arrow comparator returning a number. See `src/interp/methods/` for the full list. +## Import surfaces + +Use the package root for the full harness/runtime API. Use `@poe-code/agent-script/core` when a consumer only needs the lightweight interpreter surface: `lint`, `run`, `Budget`, and the related core types. The `./core` subpath avoids loading the bundled agent-spawn integration and is intended for codemods, linters, and other tooling that should not import provider/runtime adapters. + ## Built-in host modules Registered by the caller via the factory functions exported from the package. None of them are auto-installed — you choose which to wire up per run. -| Import | Factory | What it gives the script | -| --------- | -------------------------------------- | -------------------------------------------------------------------------------------------- | -| `agent` | `makeAgentModule(spawnAgent)` | `spawn(definition, { prompt, mode, model, mcp, cwd, timeoutMs })` | -| `git` | `makeGitModule(cwd)` | `head`, `checkpoint`, `commit`, `revert`, `diff` | -| `harness` | `makeHarnessModule(frontmatter, meta)` | `tasks`, `agents`, `meta` (kind, version, filepath, frontmatter), `applyConstraints(prompt)` | -| `log` | `makeLogModule(sink?)` | `info`, `error`, `event` (JSONL by default) | -| `metric` | `makeMetricModule(npmRunner)` | `run(name)` — runs an npm script and parses its last numeric line | -| `mcp` | `makeMcpModule(connectMcp)` | `server(handle)`, `client(handle)` → `{ tools(), tool(name, args) }` | -| `env` | `makeEnvModule(allowList)` | `get(name)` — only for names in the allowlist | -| `time` | `makeTimeModule({ now?, random? })` | `now`, `uuid` | -| `fail` | `makeFailModule()` | `default(message)` — throws `HarnessFailure` | +| Import | Factory | What it gives the script | +| --------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `agent` | `makeAgentModule(spawnAgent, options?)` | `spawn(definition, { prompt, mode, model, mcp, cwd, timeoutMs })`; `spawn.retry(...)` adds per-call retry control | +| `git` | `makeGitModule(cwd)` | `head`, `checkpoint`, `commit`, `revert`, `diff` | +| `harness` | `makeHarnessModule(frontmatter, meta)` | `tasks`, `agents`, `meta` (kind, version, filepath, frontmatter), `applyConstraints(prompt)` | +| `log` | `makeLogModule(sink?)` | `info`, `error`, `event` (JSONL by default) | +| `metric` | `makeMetricModule(npmRunner)` | `run(name)` — runs an npm script and parses its last numeric line | +| `mcp` | `makeMcpModule(connectMcp)` | `server(handle)`, `client(handle)` → `{ tools(), tool(name, args) }` | +| `env` | `makeEnvModule(allowList)` | `get(name)` — only for names in the allowlist | +| `time` | `makeTimeModule({ now?, random? })` | `now`, `uuid` | +| `fail` | `makeFailModule()` | `default(message)` — throws `HarnessFailure` | ## Quick start @@ -218,6 +222,12 @@ from the example registry. `runHarness()` derives the same `modules` metadata fr same `filename`, `modules`, `allowedExportNames`, and any extra `allowedGlobals` as the runner they are mirroring. +### Agent spawn retries + +`makeAgentModule(spawnAgent, { defaultRetry, onEvent })` can wrap every `agent.spawn(...)` call in retry handling. Scripts can also call `agent.spawn.retry(definition, options, { maxAttempts, backoffMs })` for a single spawn. Retry attempts are capped at five, cancellation stops retrying, and `onEvent` receives `spawn.started`, `spawn.retry`, `spawn.succeeded`, `spawn.failed`, and `spawn.cancelled` lifecycle events for progress logging. + +Poe Code's `poe-code harness run` command enables this by default for real agent runs: retryable spawn failures are attempted up to five times with backoff, while permanent configuration and credential errors fail immediately. + ### `run(source, options?)` Executes a script module. Resolves to: diff --git a/packages/task-list/README.md b/packages/task-list/README.md index d4ad30d2b9..0dce2db04a 100644 --- a/packages/task-list/README.md +++ b/packages/task-list/README.md @@ -268,6 +268,18 @@ poe-code tasks sync --workflow ./WORKFLOW.md --repo octo-org/octo-repo -- `` and `--project` both use `/` project syntax. `--workflow` defaults to `./WORKFLOW.md`. `--repo` overrides the task repository from workflow frontmatter. `--states` overrides the required state list from workflow frontmatter. `--title` sets the human-readable project title when sync must create a missing project. `--json` prints the report object as JSON. `--yes` confirms non-interactive sync; it is only used by `poe-code tasks sync`. +### Human-gated workflow transitions + +For workflow-backed CLI commands, states declared in `WORKFLOW.md` as `gate: true` are human gates. `poe-code tasks next` and `poe-code tasks set-state` refuse to move a task out of a gate state or across a gate state, so an automated worker cannot skip approval by advancing directly to a later state. Move the task from the GitHub Project board, or pass `--force` when an operator intentionally overrides the gate. + +```yaml +states: + awaiting-build: + gate: true + build: + prompt: Implement the approved plan. +``` + | Option | Commands | Behavior | | -------------------------- | ---------------- | --------------------------------------------------- | | `--workflow ` | `verify`, `sync` | Workflow file path. Defaults to `./WORKFLOW.md`. | diff --git a/packages/toolcraft-design/README.md b/packages/toolcraft-design/README.md index 2dd5aedbe1..d3506e8e94 100644 --- a/packages/toolcraft-design/README.md +++ b/packages/toolcraft-design/README.md @@ -35,6 +35,7 @@ The package does not expose public subpath imports. - `formatColumns`, `formatCommand`, `formatUsage`, `formatOption`, `formatCommandList`, `formatOptionList`: individual help-formatting functions. - `formatCommandNotFound`, `formatCommandNotFoundPanel`: command error rendering. - `renderTable`, `renderDetailCard`: tabular and detail-card rendering. +- `renderCatalog`: grouped catalog rendering with metrics and terminal/Markdown/JSON output-format support. - `getTemplatePartialNames`, `renderTemplate`, `resolveTemplatePartials`: template rendering utilities. - `openExternal`: opens a URL or file with the platform browser command. - Types: `Color`, `LoggerOutput`, `CommandInfo`, `OptionInfo`, `FormatColumnsOptions`, `TableColumn`, `RenderTableOptions`, `DetailCardRow`, `DetailCardSection`, `RenderDetailCardOptions`, `RenderTemplateOptions`, `TemplateEscape`. @@ -153,5 +154,5 @@ This package has no file-based configuration. Configure it in-process before ren - `configureTheme({ brand?, label? })` sets the current brand and label. - `brands[name] = brand` registers additional brand palettes for later selection. -- Component options such as `theme`, `width`, `columns`, `rows`, prompt option objects, dashboard options, and explorer config objects control individual renderers. +- Component options such as `theme`, `width`, `columns`, `rows`, prompt option objects, dashboard options, explorer config objects, and catalog `groups`/`metrics` control individual renderers. - `withOutputFormat(format, fn)` temporarily selects `terminal`, `markdown`, or `json` rendering for components that use the output-format resolver. diff --git a/packages/toolcraft-openapi/README.md b/packages/toolcraft-openapi/README.md index f3f8c16485..b878a49716 100644 --- a/packages/toolcraft-openapi/README.md +++ b/packages/toolcraft-openapi/README.md @@ -18,12 +18,15 @@ const auth = bearerTokenAuth({ ## Generator CLI -`toolcraft-openapi-generate` reads an OpenAPI document from disk or a URL, writes generated -command files. +`toolcraft-openapi-generate` reads an OpenAPI document from disk or a URL and writes generated command files. Inputs may be OpenAPI 3.x or Swagger 2.0 documents; Swagger query/body parameters are normalized before generation. - `--input ` — OpenAPI document to read. Defaults to `openapi.json`. - `--output ` — directory for generated files. Defaults to `src/generated`. - `--check` — exits non-zero when generated files would change. +- `--inspect` — reports which operations can be generated without writing files. +- `--output-format ` — output format for `--inspect`. Defaults to `terminal`. + +Generated commands preserve original OpenAPI parameter names, use the first tag as the command group, derive stable names from slash-delimited or duplicated `operationId` values, and support common real-world schemas including nullable scalars/enums, object request bodies, same-shape `oneOf`/`anyOf`, and query arrays serialized as `form` or `pipeDelimited`. Unsupported operations are reported as user errors, and `--inspect` can be used before generation to identify them. ### CI drift check @@ -31,10 +34,22 @@ command files. toolcraft-openapi-generate --check ``` +### Inspect compatibility + +```sh +toolcraft-openapi-generate --input ./openapi.json --inspect --output-format markdown +``` + ## Exports - `bearerTokenAuth(opts)` - `requestJson(options)` +- `generate(options)` +- `inspectOpenApiDocument(document)` +- `inspectOpenApiSource(source, options?)` +- `renderOpenApiInspection(report)` +- `commandsFromSpec(options)` +- `defineClientFromSpec(options)` - `HttpError` - `TokenSource` - `CommandContributor` From 9131b489ce623b118eb834a4da752ecfe69c8a98 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Fri, 12 Jun 2026 00:45:48 +0000 Subject: [PATCH 10/10] docs: document cursor and toolcraft updates --- README.md | 8 +- docs/DESIGN_LANGUAGE.md | 137 ++-- docs/DESIGN_LANGUAGE_JSON.md | 190 +++-- docs/DESIGN_LANGUAGE_MARKDOWN.md | 243 +++--- docs/README_FULL.md | 1144 +++++++++++++++------------ docs/development/NPM_PUBLISHING.md | 4 +- packages/agent-spawn/README.md | 8 +- packages/terminal-pilot/README.md | 2 +- packages/toolcraft-design/README.md | 16 +- packages/toolcraft/README.md | 26 +- 10 files changed, 966 insertions(+), 812 deletions(-) diff --git a/README.md b/README.md index a695f22388..c5256e258c 100644 --- a/README.md +++ b/README.md @@ -80,8 +80,11 @@ Utilities are especially useful for scripting and CI/CD. ```bash npx poe-code@latest spawn codex "Say hello" +npx poe-code@latest spawn cursor "Say hello from Cursor" ``` +Cursor spawns use the authenticated `cursor-agent` installation and your Cursor account; Poe Code does not inject Poe credentials into Cursor. + #### Spawn against a GitHub repository ```bash @@ -121,6 +124,9 @@ npx poe-code@latest install codex # OpenCode npx poe-code@latest install opencode +# Cursor +npx poe-code@latest install cursor + # Kimi npx poe-code@latest install kimi @@ -249,7 +255,7 @@ console.log(run.output); Runs a single prompt through a configured service CLI. -- `service` – Service identifier (`claude-code`, `codex`, `opencode`, `kimi`, `goose`) +- `service` – Service identifier (`claude-code`, `codex`, `cursor`, `opencode`, `kimi`, `goose`) - `options.prompt` – The prompt to send - `options.cwd` – Working directory or workspace locator (optional). Supports local paths and `github://owner/repo[#ref[:subdir]]` locators. See [@poe-code/workspace-resolver](packages/workspace-resolver/) for the full locator syntax. - `options.model` – Model identifier override (optional) diff --git a/docs/DESIGN_LANGUAGE.md b/docs/DESIGN_LANGUAGE.md index e13cd89db6..d6e7aa34c6 100644 --- a/docs/DESIGN_LANGUAGE.md +++ b/docs/DESIGN_LANGUAGE.md @@ -6,43 +6,44 @@ This document is auto-generated. Run `npm run generate:design-docs` to regenerat ## Package Overview -The `toolcraft-design` package provides consistent visual styling for the poe-code CLI. +The public `toolcraft/design` export provides consistent visual styling for the poe-code CLI. ```typescript // Import components -import { text, symbols, intro, outro, log } from "toolcraft-design"; +import { text, symbols, intro, outro, log } from "toolcraft/design"; // Import tokens for advanced customization -import { brand, dark, light, spacing, typography, widths } from "toolcraft-design"; +import { brand, dark, light, spacing, typography, widths } from "toolcraft/design"; ``` ## Design Tokens Foundational values that ensure consistency: -| Token | Value | Description | -|-------|-------|-------------| -| `brand` | `#a200ff` | Primary brand color (Poe purple) | -| `spacing.sm` | `1` | Small spacing unit | -| `spacing.md` | `2` | Medium spacing unit | -| `spacing.lg` | `4` | Large spacing unit | -| `widths.header` | `60` | Header line width | -| `widths.helpColumn` | `24` | Help text column width | -| `widths.maxLine` | `80` | Maximum line width | +| Token | Value | Description | +| ------------------- | --------- | -------------------------------- | +| `brand` | `#a200ff` | Primary brand color (Poe purple) | +| `spacing.sm` | `1` | Small spacing unit | +| `spacing.md` | `2` | Medium spacing unit | +| `spacing.lg` | `4` | Large spacing unit | +| `widths.header` | `60` | Header line width | +| `widths.helpColumn` | `24` | Help text column width | +| `widths.maxLine` | `80` | Maximum line width | ## Theme Palettes The design system supports dark and light themes, auto-detected from environment: ```typescript -import { getTheme, resolveThemeName } from "toolcraft-design"; +import { getTheme, resolveThemeName } from "toolcraft/design"; const themeName = resolveThemeName(); // 'dark' or 'light' const palette = getTheme(); -console.log(palette.header('Title')); +console.log(palette.header("Title")); ``` **Environment variables checked (in order):** + - `POE_CODE_THEME` - explicit override ('dark' or 'light') - `APPLE_INTERFACE_STYLE` - macOS appearance - `VSCODE_COLOR_THEME_KIND` - VS Code theme @@ -57,7 +58,7 @@ Standard command layout patterns. These show complete UI flows from start to fin Core layout: intro banner, info messages, resolved prompts, success message ```typescript -import { intro, outro, log, symbols } from "toolcraft-design"; +import { intro, outro, log, symbols } from "toolcraft/design"; intro("Configure"); log.message("Configuring...", { symbol: symbols.info }); @@ -73,7 +74,7 @@ outro("Configuration complete."); Full layout with note and outro: intro, resolved prompts, success, note box, outro ```typescript -import { intro, outro, note, log, symbols } from "toolcraft-design"; +import { intro, outro, note, log, symbols } from "toolcraft/design"; intro("configure claude-code"); log.message("Claude Code default model\n Claude-Opus-4.6", { symbol: symbols.resolved }); @@ -86,15 +87,15 @@ outro("Problems? https://..."); ## Text Styles -Semantic text styling functions for consistent CLI output. Import from `toolcraft-design`. +Semantic text styling functions for consistent CLI output. Import from `toolcraft/design`. ### intro Prominent introductory banners with brand background ```typescript -import { text } from "toolcraft-design"; -text.intro("Configure") +import { text } from "toolcraft/design"; +text.intro("Configure"); ``` ![intro](design-language/intro.png) @@ -104,8 +105,8 @@ text.intro("Configure") Section headings with brand accent color ```typescript -import { text } from "toolcraft-design"; -text.heading("Available Commands") +import { text } from "toolcraft/design"; +text.heading("Available Commands"); ``` ![heading](design-language/heading.png) @@ -115,8 +116,8 @@ text.heading("Available Commands") Bold text for subsection labels ```typescript -import { text } from "toolcraft-design"; -text.section("Options:") +import { text } from "toolcraft/design"; +text.section("Options:"); ``` ![section](design-language/section.png) @@ -126,8 +127,8 @@ text.section("Options:") CLI command names in accent color ```typescript -import { text } from "toolcraft-design"; -text.command("poe-code configure") +import { text } from "toolcraft/design"; +text.command("poe-code configure"); ``` ![command](design-language/command.png) @@ -137,8 +138,8 @@ text.command("poe-code configure") Command arguments (dimmed) ```typescript -import { text } from "toolcraft-design"; -text.argument("") +import { text } from "toolcraft/design"; +text.argument(""); ``` ![argument](design-language/argument.png) @@ -148,8 +149,8 @@ text.argument("") CLI flags and options in yellow ```typescript -import { text } from "toolcraft-design"; -text.option("--dry-run") +import { text } from "toolcraft/design"; +text.option("--dry-run"); ``` ![option](design-language/option.png) @@ -159,8 +160,8 @@ text.option("--dry-run") Example text (dimmed) ```typescript -import { text } from "toolcraft-design"; -text.example("$ poe-code configure claude") +import { text } from "toolcraft/design"; +text.example("$ poe-code configure claude"); ``` ![example](design-language/example.png) @@ -170,8 +171,8 @@ text.example("$ poe-code configure claude") Commands in usage examples (green) ```typescript -import { text } from "toolcraft-design"; -text.usageCommand("npm install -g poe-code") +import { text } from "toolcraft/design"; +text.usageCommand("npm install -g poe-code"); ``` ![usageCommand](design-language/usageCommand.png) @@ -181,8 +182,8 @@ text.usageCommand("npm install -g poe-code") Hyperlinks and references ```typescript -import { text } from "toolcraft-design"; -text.link("https://poe.com") +import { text } from "toolcraft/design"; +text.link("https://poe.com"); ``` ![link](design-language/link.png) @@ -192,8 +193,8 @@ text.link("https://poe.com") De-emphasized text ```typescript -import { text } from "toolcraft-design"; -text.muted("(optional)") +import { text } from "toolcraft/design"; +text.muted("(optional)"); ``` ![muted](design-language/muted.png) @@ -207,7 +208,7 @@ Status indicators and visual markers. Use with `log.message()` for structured ou Information indicator (magenta dot) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuring claude-code...", { symbol: symbols.info }); ``` @@ -218,7 +219,7 @@ log.message("Configuring claude-code...", { symbol: symbols.info }); Success indicator (magenta diamond) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuration complete!", { symbol: symbols.success }); ``` @@ -229,7 +230,7 @@ log.message("Configuration complete!", { symbol: symbols.success }); Resolved/completed indicator (hollow diamond) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); ``` @@ -240,7 +241,7 @@ log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); Error with details indicator (red square) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved }); ``` @@ -255,7 +256,7 @@ Structured logging with appropriate visual weight. Import `log` from the prompts Informational messages during operations ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuring claude-code...", { symbol: symbols.info }); ``` @@ -266,7 +267,7 @@ log.message("Configuring claude-code...", { symbol: symbols.info }); Success confirmation messages ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuration complete!", { symbol: symbols.success }); ``` @@ -277,7 +278,7 @@ log.message("Configuration complete!", { symbol: symbols.success }); Warning messages for non-critical issues ```typescript -import { log } from "toolcraft-design"; +import { log } from "toolcraft/design"; log.warn("API key expires in 7 days"); ``` @@ -288,7 +289,7 @@ log.warn("API key expires in 7 days"); Error messages for failures ```typescript -import { log } from "toolcraft-design"; +import { log } from "toolcraft/design"; log.error("Failed to write config file"); ``` @@ -296,14 +297,14 @@ log.error("Failed to write config file"); ## Prompts -Interactive prompts for user input. Import from `toolcraft-design`. +Interactive prompts for user input. Import from `toolcraft/design`. ### prompt-intro Command intro banner with animation ```typescript -import { intro } from "toolcraft-design"; +import { intro } from "toolcraft/design"; intro("Configure"); ``` @@ -314,7 +315,7 @@ intro("Configure"); Boxed note for next steps or important info ```typescript -import { note } from "toolcraft-design"; +import { note } from "toolcraft/design"; note("Run poe-code test", "Next steps."); ``` @@ -325,7 +326,7 @@ note("Run poe-code test", "Next steps."); Command outro with feedback link ```typescript -import { outro } from "toolcraft-design"; +import { outro } from "toolcraft/design"; outro("Problems? https://..."); ``` @@ -336,7 +337,7 @@ outro("Problems? https://..."); Resolved prompt value display ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); ``` @@ -347,7 +348,7 @@ log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); Error with details display ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved }); ``` @@ -358,7 +359,7 @@ log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved Interactive select prompt for choosing options ```typescript -import { select } from "toolcraft-design"; +import { select } from "toolcraft/design"; const choice = await select({ message: "Pick an agent:", options: [ @@ -379,7 +380,7 @@ Utilities for rendering UI elements as static strings (for screenshots, tests, o Animated dots spinner for async operations ```typescript -import { spinner } from "toolcraft-design"; +import { spinner } from "toolcraft/design"; const s = spinner(); s.start("Configuring..."); await doWork(); @@ -393,7 +394,7 @@ s.stop("Done!"); Timer spinner showing elapsed time ```typescript -import { renderSpinnerFrame, renderSpinnerStopped } from "toolcraft-design"; +import { renderSpinnerFrame, renderSpinnerStopped } from "toolcraft/design"; const frame = renderSpinnerFrame({ message: "Processing...", timer: "1s" }); const stopped = renderSpinnerStopped({ message: "Complete!", timer: "2s" }); ``` @@ -405,17 +406,15 @@ const stopped = renderSpinnerStopped({ message: "Complete!", timer: "2s" }); Styled terminal table with themed borders and column alignment ```typescript -import { renderTable, getTheme } from "toolcraft-design"; +import { renderTable, getTheme } from "toolcraft/design"; const output = renderTable({ theme: getTheme(), columns: [ { name: "Model", title: "Model", alignment: "left", maxLen: 30 }, - { name: "Context", title: "Context", alignment: "right", maxLen: 9 }, - ], - rows: [ - { Model: "anthropic/claude-sonnet-4", Context: "200K" }, + { name: "Context", title: "Context", alignment: "right", maxLen: 9 } ], + rows: [{ Model: "anthropic/claude-sonnet-4", Context: "200K" }] }); ``` @@ -426,7 +425,7 @@ const output = renderTable({ Unified diff display for file changes (used in --dry-run) ```typescript -import { color, log } from "toolcraft-design"; +import { color, log } from "toolcraft/design"; const diffLines = [ color.gray("--- config.json"), color.red('- "model": "gpt-4",'), @@ -446,7 +445,7 @@ Full-screen interactive terminal dashboard with output pane, stats pane, and key Two-pane dashboard layout with scrollable output on the left, live stats on the right, and keyboard hints in the footer ```typescript -import { createDashboard } from "toolcraft-design"; +import { createDashboard } from "toolcraft/design"; const dashboard = createDashboard({ title: "Agent Output", @@ -455,7 +454,13 @@ const dashboard = createDashboard({ dashboard.start(); dashboard.appendOutput({ kind: "info", text: "Analyzing repository state", ts: Date.now() }); -dashboard.updateStats({ status: "running", iterations: 5, tokensIn: 685, tokensOut: 445, elapsedMs: 5000 }); +dashboard.updateStats({ + status: "running", + iterations: 5, + tokensIn: 685, + tokensOut: 445, + elapsedMs: 5000 +}); ``` ![dashboard](design-language/dashboard.png) @@ -469,7 +474,7 @@ Reference demos for the terminal markdown renderer, covering both the full showc Full markdown renderer showcase with headings, lists, tables, blockquotes, alerts, links, and footnotes. ```typescript -import { renderMarkdown } from "toolcraft-design"; +import { renderMarkdown } from "toolcraft/design"; const markdown = [ "# Design System Markdown", @@ -489,8 +494,8 @@ process.stdout.write(renderMarkdown(markdown)); Compact markdown renderer sample for quick validation of headings, prose, and fenced code blocks. -```typescript -import { renderMarkdown } from "toolcraft-design"; +````typescript +import { renderMarkdown } from "toolcraft/design"; const markdown = [ "# Markdown Minimal", @@ -503,6 +508,6 @@ const markdown = [ ].join("\n"); process.stdout.write(renderMarkdown(markdown)); -``` +```` ![terminal-markdown-minimal](design-language/terminal-markdown-minimal.png) diff --git a/docs/DESIGN_LANGUAGE_JSON.md b/docs/DESIGN_LANGUAGE_JSON.md index 2b37d15c48..e081360a0e 100644 --- a/docs/DESIGN_LANGUAGE_JSON.md +++ b/docs/DESIGN_LANGUAGE_JSON.md @@ -6,43 +6,44 @@ This document is auto-generated. Run `npm run generate:design-docs:json` to rege ## Package Overview -The `toolcraft-design` package provides consistent visual styling for the poe-code CLI. +The public `toolcraft/design` export provides consistent visual styling for the poe-code CLI. ```typescript // Import components -import { text, symbols, intro, outro, log } from "toolcraft-design"; +import { text, symbols, intro, outro, log } from "toolcraft/design"; // Import tokens for advanced customization -import { brand, dark, light, spacing, typography, widths } from "toolcraft-design"; +import { brand, dark, light, spacing, typography, widths } from "toolcraft/design"; ``` ## Design Tokens Foundational values that ensure consistency: -| Token | Value | Description | -|-------|-------|-------------| -| `brand` | `#a200ff` | Primary brand color (Poe purple) | -| `spacing.sm` | `1` | Small spacing unit | -| `spacing.md` | `2` | Medium spacing unit | -| `spacing.lg` | `4` | Large spacing unit | -| `widths.header` | `60` | Header line width | -| `widths.helpColumn` | `24` | Help text column width | -| `widths.maxLine` | `80` | Maximum line width | +| Token | Value | Description | +| ------------------- | --------- | -------------------------------- | +| `brand` | `#a200ff` | Primary brand color (Poe purple) | +| `spacing.sm` | `1` | Small spacing unit | +| `spacing.md` | `2` | Medium spacing unit | +| `spacing.lg` | `4` | Large spacing unit | +| `widths.header` | `60` | Header line width | +| `widths.helpColumn` | `24` | Help text column width | +| `widths.maxLine` | `80` | Maximum line width | ## Theme Palettes The design system supports dark and light themes, auto-detected from environment: ```typescript -import { getTheme, resolveThemeName } from "toolcraft-design"; +import { getTheme, resolveThemeName } from "toolcraft/design"; const themeName = resolveThemeName(); // 'dark' or 'light' const palette = getTheme(); -console.log(palette.header('Title')); +console.log(palette.header("Title")); ``` **Environment variables checked (in order):** + - `POE_CODE_THEME` - explicit override ('dark' or 'light') - `APPLE_INTERFACE_STYLE` - macOS appearance - `VSCODE_COLOR_THEME_KIND` - VS Code theme @@ -59,7 +60,7 @@ Standard command layout patterns. These show complete UI flows from start to fin Core layout: intro banner, info messages, resolved prompts, success message ```typescript -import { intro, outro, log, symbols } from "toolcraft-design"; +import { intro, outro, log, symbols } from "toolcraft/design"; intro("Configure"); log.message("Configuring...", { symbol: symbols.info }); @@ -80,7 +81,7 @@ outro("Configuration complete."); Full layout with note and outro: intro, resolved prompts, success, note box, outro ```typescript -import { intro, outro, note, log, symbols } from "toolcraft-design"; +import { intro, outro, note, log, symbols } from "toolcraft/design"; intro("configure claude-code"); log.message("Claude Code default model\n Claude-Opus-4.6", { symbol: symbols.resolved }); @@ -98,15 +99,15 @@ outro("Problems? https://..."); ## Text Styles -Semantic text styling functions for consistent CLI output. Import from `toolcraft-design`. +Semantic text styling functions for consistent CLI output. Import from `toolcraft/design`. ### intro Prominent introductory banners with brand background ```typescript -import { text } from "toolcraft-design"; -text.intro("Configure") +import { text } from "toolcraft/design"; +text.intro("Configure"); ``` ```json @@ -118,8 +119,8 @@ text.intro("Configure") Section headings with brand accent color ```typescript -import { text } from "toolcraft-design"; -text.heading("Available Commands") +import { text } from "toolcraft/design"; +text.heading("Available Commands"); ``` ```json @@ -131,8 +132,8 @@ Available Commands Bold text for subsection labels ```typescript -import { text } from "toolcraft-design"; -text.section("Options:") +import { text } from "toolcraft/design"; +text.section("Options:"); ``` ```json @@ -144,8 +145,8 @@ Options: CLI command names in accent color ```typescript -import { text } from "toolcraft-design"; -text.command("poe-code configure") +import { text } from "toolcraft/design"; +text.command("poe-code configure"); ``` ```json @@ -157,8 +158,8 @@ poe-code configure Command arguments (dimmed) ```typescript -import { text } from "toolcraft-design"; -text.argument("") +import { text } from "toolcraft/design"; +text.argument(""); ``` ```json @@ -170,8 +171,8 @@ text.argument("") CLI flags and options in yellow ```typescript -import { text } from "toolcraft-design"; -text.option("--dry-run") +import { text } from "toolcraft/design"; +text.option("--dry-run"); ``` ```json @@ -183,8 +184,8 @@ text.option("--dry-run") Example text (dimmed) ```typescript -import { text } from "toolcraft-design"; -text.example("$ poe-code configure claude") +import { text } from "toolcraft/design"; +text.example("$ poe-code configure claude"); ``` ```json @@ -196,8 +197,8 @@ $ poe-code configure claude Commands in usage examples (green) ```typescript -import { text } from "toolcraft-design"; -text.usageCommand("npm install -g poe-code") +import { text } from "toolcraft/design"; +text.usageCommand("npm install -g poe-code"); ``` ```json @@ -209,8 +210,8 @@ npm install -g poe-code Hyperlinks and references ```typescript -import { text } from "toolcraft-design"; -text.link("https://poe.com") +import { text } from "toolcraft/design"; +text.link("https://poe.com"); ``` ```json @@ -222,8 +223,8 @@ https://poe.com De-emphasized text ```typescript -import { text } from "toolcraft-design"; -text.muted("(optional)") +import { text } from "toolcraft/design"; +text.muted("(optional)"); ``` ```json @@ -239,12 +240,12 @@ Status indicators and visual markers. Use with `log.message()` for structured ou Information indicator (magenta dot) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuring claude-code...", { symbol: symbols.info }); ``` ```json -{"level":"message","message":"info"} +{ "level": "message", "message": "info" } ``` ### success @@ -252,12 +253,12 @@ log.message("Configuring claude-code...", { symbol: symbols.info }); Success indicator (magenta diamond) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuration complete!", { symbol: symbols.success }); ``` ```json -{"level":"message","message":"success"} +{ "level": "message", "message": "success" } ``` ### resolved @@ -265,12 +266,12 @@ log.message("Configuration complete!", { symbol: symbols.success }); Resolved/completed indicator (hollow diamond) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); ``` ```json -{"level":"message","message":"resolved"} +{ "level": "message", "message": "resolved" } ``` ### errorResolved @@ -278,12 +279,12 @@ log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); Error with details indicator (red square) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved }); ``` ```json -{"level":"message","message":"errorResolved"} +{ "level": "message", "message": "errorResolved" } ``` ## Log Messages @@ -295,12 +296,12 @@ Structured logging with appropriate visual weight. Import `log` from the prompts Informational messages during operations ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuring claude-code...", { symbol: symbols.info }); ``` ```json -{"level":"info","message":"Configuring claude-code..."} +{ "level": "info", "message": "Configuring claude-code..." } ``` ### log-success @@ -308,12 +309,12 @@ log.message("Configuring claude-code...", { symbol: symbols.info }); Success confirmation messages ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuration complete!", { symbol: symbols.success }); ``` ```json -{"level":"success","message":"Configuration complete!"} +{ "level": "success", "message": "Configuration complete!" } ``` ### log-warn @@ -321,12 +322,12 @@ log.message("Configuration complete!", { symbol: symbols.success }); Warning messages for non-critical issues ```typescript -import { log } from "toolcraft-design"; +import { log } from "toolcraft/design"; log.warn("API key expires in 7 days"); ``` ```json -{"level":"warn","message":"API key expires in 7 days"} +{ "level": "warn", "message": "API key expires in 7 days" } ``` ### log-error @@ -334,24 +335,24 @@ log.warn("API key expires in 7 days"); Error messages for failures ```typescript -import { log } from "toolcraft-design"; +import { log } from "toolcraft/design"; log.error("Failed to write config file"); ``` ```json -{"level":"error","message":"Failed to write config file"} +{ "level": "error", "message": "Failed to write config file" } ``` ## Prompts -Interactive prompts for user input. Import from `toolcraft-design`. +Interactive prompts for user input. Import from `toolcraft/design`. ### prompt-intro Command intro banner with animation ```typescript -import { intro } from "toolcraft-design"; +import { intro } from "toolcraft/design"; intro("Configure"); ``` @@ -364,12 +365,16 @@ intro("Configure"); Boxed note for next steps or important info ```typescript -import { note } from "toolcraft-design"; +import { note } from "toolcraft/design"; note("Run poe-code test", "Next steps."); ``` ```json -{"type":"note","title":"Next steps.","message":"Run the following command to test:\n poe-code test claude-code"} +{ + "type": "note", + "title": "Next steps.", + "message": "Run the following command to test:\n poe-code test claude-code" +} ``` ### prompt-outro @@ -377,12 +382,12 @@ note("Run poe-code test", "Next steps."); Command outro with feedback link ```typescript -import { outro } from "toolcraft-design"; +import { outro } from "toolcraft/design"; outro("Problems? https://..."); ``` ```json -{"type":"outro","message":"Problems? https://github.com/poe-platform/poe-code/issues"} +{ "type": "outro", "message": "Problems? https://github.com/poe-platform/poe-code/issues" } ``` ### prompt-resolved @@ -390,12 +395,12 @@ outro("Problems? https://..."); Resolved prompt value display ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); ``` ```json -{"level":"message","message":"API Key\n poe-abc...xyz\n Expires: 2026-12-31"} +{ "level": "message", "message": "API Key\n poe-abc...xyz\n Expires: 2026-12-31" } ``` ### prompt-errorResolved @@ -403,12 +408,15 @@ log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); Error with details display ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved }); ``` ```json -{"level":"message","message":"Configuration Failed\n Missing API key\n Check your .env file or run poe-code login"} +{ + "level": "message", + "message": "Configuration Failed\n Missing API key\n Check your .env file or run poe-code login" +} ``` ### menu @@ -416,7 +424,7 @@ log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved Interactive select prompt for choosing options ```typescript -import { select } from "toolcraft-design"; +import { select } from "toolcraft/design"; const choice = await select({ message: "Pick an agent:", options: [ @@ -427,7 +435,16 @@ const choice = await select({ ``` ```json -{"type":"menu","message":"Pick an agent:","options":[{"value":"claude-code","label":"Claude Code"},{"value":"codex","label":"Codex CLI"},{"value":"aider","label":"Aider"}],"selected":0} +{ + "type": "menu", + "message": "Pick an agent:", + "options": [ + { "value": "claude-code", "label": "Claude Code" }, + { "value": "codex", "label": "Codex CLI" }, + { "value": "aider", "label": "Aider" } + ], + "selected": 0 +} ``` ## Static Rendering @@ -439,7 +456,7 @@ Utilities for rendering UI elements as static strings (for screenshots, tests, o Animated dots spinner for async operations ```typescript -import { spinner } from "toolcraft-design"; +import { spinner } from "toolcraft/design"; const s = spinner(); s.start("Configuring..."); await doWork(); @@ -457,7 +474,7 @@ s.stop("Done!"); Timer spinner showing elapsed time ```typescript -import { renderSpinnerFrame, renderSpinnerStopped } from "toolcraft-design"; +import { renderSpinnerFrame, renderSpinnerStopped } from "toolcraft/design"; const frame = renderSpinnerFrame({ message: "Processing...", timer: "1s" }); const stopped = renderSpinnerStopped({ message: "Complete!", timer: "2s" }); ``` @@ -473,17 +490,15 @@ const stopped = renderSpinnerStopped({ message: "Complete!", timer: "2s" }); Styled terminal table with themed borders and column alignment ```typescript -import { renderTable, getTheme } from "toolcraft-design"; +import { renderTable, getTheme } from "toolcraft/design"; const output = renderTable({ theme: getTheme(), columns: [ { name: "Model", title: "Model", alignment: "left", maxLen: 30 }, - { name: "Context", title: "Context", alignment: "right", maxLen: 9 }, - ], - rows: [ - { Model: "anthropic/claude-sonnet-4", Context: "200K" }, + { name: "Context", title: "Context", alignment: "right", maxLen: 9 } ], + rows: [{ Model: "anthropic/claude-sonnet-4", Context: "200K" }] }); ``` @@ -512,7 +527,7 @@ const output = renderTable({ Unified diff display for file changes (used in --dry-run) ```typescript -import { color, log } from "toolcraft-design"; +import { color, log } from "toolcraft/design"; const diffLines = [ color.gray("--- config.json"), color.red('- "model": "gpt-4",'), @@ -522,7 +537,10 @@ log.message(diffLines.join("\n"), { symbol: color.yellow("~") }); ``` ```json -{"level":"message","message":"--- config.json\n+++ config.json\n@@ -1,3 +1,5 @@\n {\n- \"model\": \"gpt-4\",\n+ \"model\": \"claude-sonnet-4\",\n \"temperature\": 0.7\n+ \"maxTokens\": 4096\n }"} +{ + "level": "message", + "message": "--- config.json\n+++ config.json\n@@ -1,3 +1,5 @@\n {\n- \"model\": \"gpt-4\",\n+ \"model\": \"claude-sonnet-4\",\n \"temperature\": 0.7\n+ \"maxTokens\": 4096\n }" +} ``` ## Dashboard @@ -534,7 +552,7 @@ Full-screen interactive terminal dashboard with output pane, stats pane, and key Two-pane dashboard layout with scrollable output on the left, live stats on the right, and keyboard hints in the footer ```typescript -import { createDashboard } from "toolcraft-design"; +import { createDashboard } from "toolcraft/design"; const dashboard = createDashboard({ title: "Agent Output", @@ -543,7 +561,13 @@ const dashboard = createDashboard({ dashboard.start(); dashboard.appendOutput({ kind: "info", text: "Analyzing repository state", ts: Date.now() }); -dashboard.updateStats({ status: "running", iterations: 5, tokensIn: 685, tokensOut: 445, elapsedMs: 5000 }); +dashboard.updateStats({ + status: "running", + iterations: 5, + tokensIn: 685, + tokensOut: 445, + elapsedMs: 5000 +}); ``` ```json @@ -578,7 +602,7 @@ Reference demos for the terminal markdown renderer, covering both the full showc Full markdown renderer showcase with headings, lists, tables, blockquotes, alerts, links, and footnotes. ```typescript -import { renderMarkdown } from "toolcraft-design"; +import { renderMarkdown } from "toolcraft/design"; const markdown = [ "# Design System Markdown", @@ -622,10 +646,10 @@ reference[1]. active completed task inactive pending task - Feature Alignment Status + Feature Alignment Status ├──────────┼───────────┼────────┤ - Headings center Ready - Tables aligned 100% + Headings center Ready + Tables aligned 100% Note Alerts are rendered as styled notes. @@ -639,8 +663,8 @@ reference[1]. Compact markdown renderer sample for quick validation of headings, prose, and fenced code blocks. -```typescript -import { renderMarkdown } from "toolcraft-design"; +````typescript +import { renderMarkdown } from "toolcraft/design"; const markdown = [ "# Markdown Minimal", @@ -653,7 +677,7 @@ const markdown = [ ].join("\n"); process.stdout.write(renderMarkdown(markdown)); -``` +```` ```json Markdown Minimal diff --git a/docs/DESIGN_LANGUAGE_MARKDOWN.md b/docs/DESIGN_LANGUAGE_MARKDOWN.md index 3df7e3b081..08ed98fdd9 100644 --- a/docs/DESIGN_LANGUAGE_MARKDOWN.md +++ b/docs/DESIGN_LANGUAGE_MARKDOWN.md @@ -6,43 +6,44 @@ This document is auto-generated. Run `npm run generate:design-docs:markdown` to ## Package Overview -The `toolcraft-design` package provides consistent visual styling for the poe-code CLI. +The public `toolcraft/design` export provides consistent visual styling for the poe-code CLI. ```typescript // Import components -import { text, symbols, intro, outro, log } from "toolcraft-design"; +import { text, symbols, intro, outro, log } from "toolcraft/design"; // Import tokens for advanced customization -import { brand, dark, light, spacing, typography, widths } from "toolcraft-design"; +import { brand, dark, light, spacing, typography, widths } from "toolcraft/design"; ``` ## Design Tokens Foundational values that ensure consistency: -| Token | Value | Description | -|-------|-------|-------------| -| `brand` | `#a200ff` | Primary brand color (Poe purple) | -| `spacing.sm` | `1` | Small spacing unit | -| `spacing.md` | `2` | Medium spacing unit | -| `spacing.lg` | `4` | Large spacing unit | -| `widths.header` | `60` | Header line width | -| `widths.helpColumn` | `24` | Help text column width | -| `widths.maxLine` | `80` | Maximum line width | +| Token | Value | Description | +| ------------------- | --------- | -------------------------------- | +| `brand` | `#a200ff` | Primary brand color (Poe purple) | +| `spacing.sm` | `1` | Small spacing unit | +| `spacing.md` | `2` | Medium spacing unit | +| `spacing.lg` | `4` | Large spacing unit | +| `widths.header` | `60` | Header line width | +| `widths.helpColumn` | `24` | Help text column width | +| `widths.maxLine` | `80` | Maximum line width | ## Theme Palettes The design system supports dark and light themes, auto-detected from environment: ```typescript -import { getTheme, resolveThemeName } from "toolcraft-design"; +import { getTheme, resolveThemeName } from "toolcraft/design"; const themeName = resolveThemeName(); // 'dark' or 'light' const palette = getTheme(); -console.log(palette.header('Title')); +console.log(palette.header("Title")); ``` **Environment variables checked (in order):** + - `POE_CODE_THEME` - explicit override ('dark' or 'light') - `APPLE_INTERFACE_STYLE` - macOS appearance - `VSCODE_COLOR_THEME_KIND` - VS Code theme @@ -59,7 +60,7 @@ Standard command layout patterns. These show complete UI flows from start to fin Core layout: intro banner, info messages, resolved prompts, success message ```typescript -import { intro, outro, log, symbols } from "toolcraft-design"; +import { intro, outro, log, symbols } from "toolcraft/design"; intro("Configure"); log.message("Configuring...", { symbol: symbols.info }); @@ -72,9 +73,11 @@ outro("Configuration complete."); # Configure - **info:** Configuring claude-code... -- Provider claude -- API Key poe-abc...xyz +- Provider claude +- API Key poe-abc...xyz + --- + Configuration complete. ``` @@ -83,7 +86,7 @@ Configuration complete. Full layout with note and outro: intro, resolved prompts, success, note box, outro ```typescript -import { intro, outro, note, log, symbols } from "toolcraft-design"; +import { intro, outro, note, log, symbols } from "toolcraft/design"; intro("configure claude-code"); log.message("Claude Code default model\n Claude-Opus-4.6", { symbol: symbols.resolved }); @@ -95,26 +98,28 @@ outro("Problems? https://..."); ```markdown # configure claude-code -- Claude Code default model Claude-Opus-4.6 +- Claude Code default model Claude-Opus-4.6 - **success:** Configured Claude Code. -> **Next steps.** -> If using VSCode - Open the Disable Login Prompt setting and check the box. -> vscode://settings/claudeCode.disableLoginPrompt + > **Next steps.** + > If using VSCode - Open the Disable Login Prompt setting and check the box. + > vscode://settings/claudeCode.disableLoginPrompt + --- + Problems? https://github.com/poe-platform/poe-code/issues ``` ## Text Styles -Semantic text styling functions for consistent CLI output. Import from `toolcraft-design`. +Semantic text styling functions for consistent CLI output. Import from `toolcraft/design`. ### intro Prominent introductory banners with brand background ```typescript -import { text } from "toolcraft-design"; -text.intro("Configure") +import { text } from "toolcraft/design"; +text.intro("Configure"); ``` ```markdown @@ -126,8 +131,8 @@ text.intro("Configure") Section headings with brand accent color ```typescript -import { text } from "toolcraft-design"; -text.heading("Available Commands") +import { text } from "toolcraft/design"; +text.heading("Available Commands"); ``` ```markdown @@ -139,8 +144,8 @@ text.heading("Available Commands") Bold text for subsection labels ```typescript -import { text } from "toolcraft-design"; -text.section("Options:") +import { text } from "toolcraft/design"; +text.section("Options:"); ``` ```markdown @@ -152,8 +157,8 @@ text.section("Options:") CLI command names in accent color ```typescript -import { text } from "toolcraft-design"; -text.command("poe-code configure") +import { text } from "toolcraft/design"; +text.command("poe-code configure"); ``` ```markdown @@ -165,8 +170,8 @@ text.command("poe-code configure") Command arguments (dimmed) ```typescript -import { text } from "toolcraft-design"; -text.argument("") +import { text } from "toolcraft/design"; +text.argument(""); ``` ```markdown @@ -178,8 +183,8 @@ text.argument("") CLI flags and options in yellow ```typescript -import { text } from "toolcraft-design"; -text.option("--dry-run") +import { text } from "toolcraft/design"; +text.option("--dry-run"); ``` ```markdown @@ -191,8 +196,8 @@ text.option("--dry-run") Example text (dimmed) ```typescript -import { text } from "toolcraft-design"; -text.example("$ poe-code configure claude") +import { text } from "toolcraft/design"; +text.example("$ poe-code configure claude"); ``` ```markdown @@ -204,8 +209,8 @@ text.example("$ poe-code configure claude") Commands in usage examples (green) ```typescript -import { text } from "toolcraft-design"; -text.usageCommand("npm install -g poe-code") +import { text } from "toolcraft/design"; +text.usageCommand("npm install -g poe-code"); ``` ```markdown @@ -217,8 +222,8 @@ text.usageCommand("npm install -g poe-code") Hyperlinks and references ```typescript -import { text } from "toolcraft-design"; -text.link("https://poe.com") +import { text } from "toolcraft/design"; +text.link("https://poe.com"); ``` ```markdown @@ -230,12 +235,12 @@ text.link("https://poe.com") De-emphasized text ```typescript -import { text } from "toolcraft-design"; -text.muted("(optional)") +import { text } from "toolcraft/design"; +text.muted("(optional)"); ``` ```markdown -*(optional)* +_(optional)_ ``` ## Symbols @@ -247,7 +252,7 @@ Status indicators and visual markers. Use with `log.message()` for structured ou Information indicator (magenta dot) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuring claude-code...", { symbol: symbols.info }); ``` @@ -260,7 +265,7 @@ log.message("Configuring claude-code...", { symbol: symbols.info }); Success indicator (magenta diamond) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuration complete!", { symbol: symbols.success }); ``` @@ -273,7 +278,7 @@ log.message("Configuration complete!", { symbol: symbols.success }); Resolved/completed indicator (hollow diamond) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); ``` @@ -286,7 +291,7 @@ log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); Error with details indicator (red square) ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved }); ``` @@ -303,7 +308,7 @@ Structured logging with appropriate visual weight. Import `log` from the prompts Informational messages during operations ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuring claude-code...", { symbol: symbols.info }); ``` @@ -316,7 +321,7 @@ log.message("Configuring claude-code...", { symbol: symbols.info }); Success confirmation messages ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Configuration complete!", { symbol: symbols.success }); ``` @@ -329,7 +334,7 @@ log.message("Configuration complete!", { symbol: symbols.success }); Warning messages for non-critical issues ```typescript -import { log } from "toolcraft-design"; +import { log } from "toolcraft/design"; log.warn("API key expires in 7 days"); ``` @@ -342,7 +347,7 @@ log.warn("API key expires in 7 days"); Error messages for failures ```typescript -import { log } from "toolcraft-design"; +import { log } from "toolcraft/design"; log.error("Failed to write config file"); ``` @@ -352,14 +357,14 @@ log.error("Failed to write config file"); ## Prompts -Interactive prompts for user input. Import from `toolcraft-design`. +Interactive prompts for user input. Import from `toolcraft/design`. ### prompt-intro Command intro banner with animation ```typescript -import { intro } from "toolcraft-design"; +import { intro } from "toolcraft/design"; intro("Configure"); ``` @@ -372,14 +377,14 @@ intro("Configure"); Boxed note for next steps or important info ```typescript -import { note } from "toolcraft-design"; +import { note } from "toolcraft/design"; note("Run poe-code test", "Next steps."); ``` ```markdown > **Next steps.** > Run the following command to test: -> poe-code test claude-code +> poe-code test claude-code ``` ### prompt-outro @@ -387,12 +392,13 @@ note("Run poe-code test", "Next steps."); Command outro with feedback link ```typescript -import { outro } from "toolcraft-design"; +import { outro } from "toolcraft/design"; outro("Problems? https://..."); ``` ```markdown --- + Problems? https://github.com/poe-platform/poe-code/issues ``` @@ -401,12 +407,12 @@ Problems? https://github.com/poe-platform/poe-code/issues Resolved prompt value display ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); ``` ```markdown -- API Key poe-abc...xyz Expires: 2026-12-31 +- API Key poe-abc...xyz Expires: 2026-12-31 ``` ### prompt-errorResolved @@ -414,12 +420,12 @@ log.message("API Key\n poe-abc...xyz", { symbol: symbols.resolved }); Error with details display ```typescript -import { log, symbols } from "toolcraft-design"; +import { log, symbols } from "toolcraft/design"; log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved }); ``` ```markdown -- Configuration Failed Missing API key Check your .env file or run poe-code login +- Configuration Failed Missing API key Check your .env file or run poe-code login ``` ### menu @@ -427,7 +433,7 @@ log.message("Config Failed\n Missing API key", { symbol: symbols.errorResolved Interactive select prompt for choosing options ```typescript -import { select } from "toolcraft-design"; +import { select } from "toolcraft/design"; const choice = await select({ message: "Pick an agent:", options: [ @@ -439,6 +445,7 @@ const choice = await select({ ```markdown **Pick an agent:** + - [x] Claude Code - [ ] Codex CLI - [ ] Aider @@ -453,7 +460,7 @@ Utilities for rendering UI elements as static strings (for screenshots, tests, o Animated dots spinner for async operations ```typescript -import { spinner } from "toolcraft-design"; +import { spinner } from "toolcraft/design"; const s = spinner(); s.start("Configuring..."); await doWork(); @@ -471,7 +478,7 @@ s.stop("Done!"); Timer spinner showing elapsed time ```typescript -import { renderSpinnerFrame, renderSpinnerStopped } from "toolcraft-design"; +import { renderSpinnerFrame, renderSpinnerStopped } from "toolcraft/design"; const frame = renderSpinnerFrame({ message: "Processing...", timer: "1s" }); const stopped = renderSpinnerStopped({ message: "Complete!", timer: "2s" }); ``` @@ -487,26 +494,24 @@ const stopped = renderSpinnerStopped({ message: "Complete!", timer: "2s" }); Styled terminal table with themed borders and column alignment ```typescript -import { renderTable, getTheme } from "toolcraft-design"; +import { renderTable, getTheme } from "toolcraft/design"; const output = renderTable({ theme: getTheme(), columns: [ { name: "Model", title: "Model", alignment: "left", maxLen: 30 }, - { name: "Context", title: "Context", alignment: "right", maxLen: 9 }, - ], - rows: [ - { Model: "anthropic/claude-sonnet-4", Context: "200K" }, + { name: "Context", title: "Context", alignment: "right", maxLen: 9 } ], + rows: [{ Model: "anthropic/claude-sonnet-4", Context: "200K" }] }); ``` ```markdown -| Model | Context | $/MTok In/Out | -| :--- | ---: | ---: | -| anthropic/claude-sonnet-4 | 200K | $3.00/$15.00 | -| openai/gpt-4o | 128K | $2.50/$10.00 | -| google/gemini-2.0-flash | 1M | $0.10/$0.40 | +| Model | Context | $/MTok In/Out | +| :------------------------ | ------: | ------------: | +| anthropic/claude-sonnet-4 | 200K | $3.00/$15.00 | +| openai/gpt-4o | 128K | $2.50/$10.00 | +| google/gemini-2.0-flash | 1M | $0.10/$0.40 | ``` ### diff @@ -514,7 +519,7 @@ const output = renderTable({ Unified diff display for file changes (used in --dry-run) ```typescript -import { color, log } from "toolcraft-design"; +import { color, log } from "toolcraft/design"; const diffLines = [ color.gray("--- config.json"), color.red('- "model": "gpt-4",'), @@ -524,7 +529,7 @@ log.message(diffLines.join("\n"), { symbol: color.yellow("~") }); ``` ```markdown -- --- config.json +++ config.json @@ -1,3 +1,5 @@ { - "model": "gpt-4", + "model": "claude-sonnet-4", "temperature": 0.7 + "maxTokens": 4096 } +- --- config.json +++ config.json @@ -1,3 +1,5 @@ { - "model": "gpt-4", + "model": "claude-sonnet-4", "temperature": 0.7 + "maxTokens": 4096 } ``` ## Dashboard @@ -536,7 +541,7 @@ Full-screen interactive terminal dashboard with output pane, stats pane, and key Two-pane dashboard layout with scrollable output on the left, live stats on the right, and keyboard hints in the footer ```typescript -import { createDashboard } from "toolcraft-design"; +import { createDashboard } from "toolcraft/design"; const dashboard = createDashboard({ title: "Agent Output", @@ -545,29 +550,35 @@ const dashboard = createDashboard({ dashboard.start(); dashboard.appendOutput({ kind: "info", text: "Analyzing repository state", ts: Date.now() }); -dashboard.updateStats({ status: "running", iterations: 5, tokensIn: 685, tokensOut: 445, elapsedMs: 5000 }); +dashboard.updateStats({ + status: "running", + iterations: 5, + tokensIn: 685, + tokensOut: 445, + elapsedMs: 5000 +}); ``` ```markdown ┌─ Agent Output ─────────────────────────────────────┬─ Stats ─────────────────┐ -│◇ Analyzing repository state │Status Running│ -││ Running npm test -- --runInBand │Iteration 5│ -│◆ Generated provider config │Elapsed 00:00:05│ -│● Streaming model response │ │ -│◇ Inspecting agent configuration │Tokens In 685│ -││ Executing npm run lint:types │Tokens Out 445│ -│■ Retrying transient network request │Total 1,130│ -│◆ Updated dashboard layout │ │ -│◇ Collecting recent command output │Current: │ -│● Waiting for follow-up task │ Executing tool call │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ -│ │ │ +│◇ Analyzing repository state │Status Running│ +││ Running npm test -- --runInBand │Iteration 5│ +│◆ Generated provider config │Elapsed 00:00:05│ +│● Streaming model response │ │ +│◇ Inspecting agent configuration │Tokens In 685│ +││ Executing npm run lint:types │Tokens Out 445│ +│■ Retrying transient network request │Total 1,130│ +│◆ Updated dashboard layout │ │ +│◇ Collecting recent command output │Current: │ +│● Waiting for follow-up task │ Executing tool call │ +│ │ │ +│ │ │ +│ │ │ +│ │ │ +│ │ │ +│ │ │ ├────────────────────────────────────────────────────┴─────────────────────────┤ -│ q Quit e Edit l Log p Pause r Retry │ +│ q Quit e Edit l Log p Pause r Retry │ └──────────────────────────────────────────────────────────────────────────────┘ ``` @@ -580,7 +591,7 @@ Reference demos for the terminal markdown renderer, covering both the full showc Full markdown renderer showcase with headings, lists, tables, blockquotes, alerts, links, and footnotes. ```typescript -import { renderMarkdown } from "toolcraft-design"; +import { renderMarkdown } from "toolcraft/design"; const markdown = [ "# Design System Markdown", @@ -606,43 +617,43 @@ Paragraph with bold, italic, strikethrough, code span, a docs link (https://example.com/docs), an image [image: System diagram], and a footnote reference[1]. - ───────────────────────── - const agent = "poe-code"; - console.log(agent); - ───────────────────────── +───────────────────────── +const agent = "poe-code"; +console.log(agent); +───────────────────────── | Outer quote | | | Nested quote - • unordered item - • another unordered item +• unordered item +• another unordered item - 1. ordered item - 2. another ordered item +1. ordered item +2. another ordered item - [x] completed task - [ ] pending task +[x] completed task +[ ] pending task -| Feature | Alignment | Status | +| Feature | Alignment | Status | ├──────────┼───────────┼────────┤ -| Headings | center | Ready | -| Tables | aligned | 100% | +| Headings | center | Ready | +| Tables | aligned | 100% | | Note | Alerts are rendered as styled notes. ──────────────────────────────────────────────────────────────────────────────── - [1] Footnote definition for the markdown demo. +[1] Footnote definition for the markdown demo. ``` ### terminal-markdown-minimal Compact markdown renderer sample for quick validation of headings, prose, and fenced code blocks. -```typescript -import { renderMarkdown } from "toolcraft-design"; +````typescript +import { renderMarkdown } from "toolcraft/design"; const markdown = [ "# Markdown Minimal", @@ -655,7 +666,7 @@ const markdown = [ ].join("\n"); process.stdout.write(renderMarkdown(markdown)); -``` +```` ```markdown Markdown Minimal @@ -663,7 +674,7 @@ Markdown Minimal Quick validation paragraph. - ──────────────────── - console.log("demo"); - ──────────────────── +──────────────────── +console.log("demo"); +──────────────────── ``` diff --git a/docs/README_FULL.md b/docs/README_FULL.md index 57f6cd4fe3..a354a5c40a 100644 --- a/docs/README_FULL.md +++ b/docs/README_FULL.md @@ -2,7 +2,7 @@ > **Audience**: AI agents and developers who need to understand and use every feature of the `poe-code` library — CLI, SDK, MCP server, providers, and internals. -`poe-code` is a CLI tool and Node.js SDK that configures coding agents (Claude Code, Codex, OpenCode, Kimi, Goose) to route their API calls through the [Poe API](https://poe.com/api). Instead of managing multiple provider accounts, a single Poe subscription powers all your coding agents. +`poe-code` is a CLI tool and Node.js SDK that configures coding agents (Claude Code, Codex, OpenCode, Kimi, Goose) to route their API calls through the [Poe API](https://poe.com/api), and can spawn Cursor through the authenticated `cursor-agent` installation. For Poe-backed agents, a single Poe subscription replaces separate provider accounts. **Repository**: https://github.com/poe-platform/poe-code @@ -49,6 +49,7 @@ - [Claude Code](#claude-code-provider) - [Codex](#codex-provider) - [OpenCode](#opencode-provider) + - [Cursor](#cursor-provider) - [Kimi](#kimi-provider) - [Goose](#goose-provider) - [Provider Architecture](#provider-architecture) @@ -139,13 +140,13 @@ npx poe-code@latest logout Every command supports these flags: -| Flag | Description | -|------|-------------| -| `-y, --yes` | Accept all defaults without prompting. Mainly for CI/CD. | -| `--dry-run` | Simulate the command. Shows every file mutation without writing to disk. Redacts sensitive values (API keys). | -| `--verbose` | Show detailed log output. | -| `-h, --help` | Display help for the command. | -| `-V, --version` | Show current version and check for updates. | +| Flag | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------- | +| `-y, --yes` | Accept all defaults without prompting. Mainly for CI/CD. | +| `--dry-run` | Simulate the command. Shows every file mutation without writing to disk. Redacts sensitive values (API keys). | +| `--verbose` | Show detailed log output. | +| `-h, --help` | Display help for the command. | +| `-V, --version` | Show current version and check for updates. | Boolean flags also accept explicit values (`--flag true` / `--flag false`) in addition to `--flag` / `--no-flag`. @@ -161,18 +162,18 @@ poe-code configure [agent] **Arguments:** -| Argument | Required | Description | -|----------|----------|-------------| -| `agent` | No | Agent to configure: `claude`, `claude-code`, `codex`, `opencode`, `kimi`, `goose`. Prompts if omitted. With `--yes`, uses `core.defaultAgent` / `POE_DEFAULT_AGENT` when set; otherwise uses `claude-code`. | +| Argument | Required | Description | +| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `agent` | No | Agent to configure: `claude`, `claude-code`, `codex`, `opencode`, `kimi`, `goose`; Cursor is available for spawn/test/install and uses the authenticated Cursor account. Prompts if omitted. With `--yes`, uses `core.defaultAgent` / `POE_DEFAULT_AGENT` when set; otherwise uses `claude-code`. | **Options:** -| Option | Description | -|--------|-------------| -| `--api-key ` | API key for the selected provider. Also reads `POE_API_KEY` for Poe provider flows. | -| `--model ` | Model identifier (e.g., `sonnet`, `opus`, `openai/gpt-5.2`). Prompts from agent-specific choices if omitted. | +| Option | Description | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------- | +| `--api-key ` | API key for the selected provider. Also reads `POE_API_KEY` for Poe provider flows. | +| `--model ` | Model identifier (e.g., `sonnet`, `opus`, `openai/gpt-5.2`). Prompts from agent-specific choices if omitted. | | `--reasoning-effort ` | Reasoning effort level for agents that support it (Codex). Values: `low`, `medium`, `high`. Default: `medium`. | -| `--provider ` | Provider ID to use for this agent (e.g., `poe`, `anthropic`). Overrides `POE_CODE_PROVIDER`. | +| `--provider ` | Provider ID to use for this agent (e.g., `poe`, `anthropic`). Overrides `POE_CODE_PROVIDER`. | **Behavior:** @@ -216,9 +217,9 @@ poe-code unconfigure **Arguments:** -| Argument | Required | Description | -|----------|----------|-------------| -| `agent` | Yes | Agent to unconfigure. | +| Argument | Required | Description | +| -------- | -------- | --------------------- | +| `agent` | Yes | Agent to unconfigure. | **Behavior:** @@ -247,8 +248,8 @@ poe-code login **Options:** -| Option | Description | -|--------|-------------| +| Option | Description | +| ----------------- | ------------------------------------- | | `--api-key ` | Poe API key. Prompts if not provided. | **Behavior:** @@ -296,13 +297,13 @@ Running `poe-code auth` with no subcommand is the same as `poe-code auth status` **Subcommands:** -| Subcommand | Description | -|------------|-------------| -| `status` | Show whether a stored Poe credential is valid and print the account name/handle. Honors `--dry-run` by skipping the `/whoami` request. | -| `api-key` | Print the stored Poe API key only. Exits with code `1` when no key is stored. | -| `whoami` | Call Poe `/whoami` and print the raw identity JSON to stdout. Resolves `POE_API_KEY` first, then the stored credential. Exits with code `1` when no key is available. | -| `login` | Store a Poe API key for reuse across commands. Same behavior as top-level `poe-code login`. | -| `logout` | Remove all configuration and credentials. Same behavior as top-level `poe-code logout`. | +| Subcommand | Description | +| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `status` | Show whether a stored Poe credential is valid and print the account name/handle. Honors `--dry-run` by skipping the `/whoami` request. | +| `api-key` | Print the stored Poe API key only. Exits with code `1` when no key is stored. | +| `whoami` | Call Poe `/whoami` and print the raw identity JSON to stdout. Resolves `POE_API_KEY` first, then the stored credential. Exits with code `1` when no key is available. | +| `login` | Store a Poe API key for reuse across commands. Same behavior as top-level `poe-code login`. | +| `logout` | Remove all configuration and credentials. Same behavior as top-level `poe-code logout`. | **Examples:** @@ -325,11 +326,11 @@ poe-code provider **Subcommands:** -| Subcommand | Description | -|------------|-------------| -| `list` | Show available providers, login status, and supported agents. A non-empty provider env var, such as `POE_API_KEY` for the Poe provider, counts as logged in. | -| `login ` | Store provider credentials. Uses `--api-key`, then that provider's env var, then an interactive secret prompt. | -| `logout ` | Remove stored credentials for that provider. An exported provider env var can still make the provider appear logged in. | +| Subcommand | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `list` | Show available providers, login status, and supported agents. A non-empty provider env var, such as `POE_API_KEY` for the Poe provider, counts as logged in. | +| `login ` | Store provider credentials. Uses `--api-key`, then that provider's env var, then an interactive secret prompt. | +| `logout ` | Remove stored credentials for that provider. An exported provider env var can still make the provider appear logged in. | **Examples:** @@ -355,11 +356,11 @@ poe-code approvals **Subcommands:** -| Subcommand | Description | -|------------|-------------| -| `list [--state ]` | List queued approval tasks, optionally filtered by state. | -| `show --approval-id ` | Show one queued approval task. | -| `run --approval-id ` | Ask the configured approval provider, then execute one pending queued task when approved. | +| Subcommand | Description | +| ------------------------- | ----------------------------------------------------------------------------------------- | +| `list [--state ]` | List queued approval tasks, optionally filtered by state. | +| `show --approval-id ` | Show one queued approval task. | +| `run --approval-id ` | Ask the configured approval provider, then execute one pending queued task when approved. | **Examples:** @@ -381,29 +382,29 @@ poe-code spawn [prompt] [agentArgs...] **Arguments:** -| Argument | Required | Description | -|----------|----------|-------------| -| `agent` | Yes | Agent to spawn: `claude-code`, `codex`, `opencode`, `kimi`, `goose` | -| `prompt` | No | Prompt text. Use `-` to read from stdin, or `@path/to/file` to load prompt text from a file. | -| `agentArgs` | No | Additional arguments forwarded directly to the agent CLI. | +| Argument | Required | Description | +| ----------- | -------- | -------------------------------------------------------------------------------------------- | +| `agent` | Yes | Agent to spawn: `claude-code`, `codex`, `cursor`, `opencode`, `kimi`, `goose` | +| `prompt` | No | Prompt text. Use `-` to read from stdin, or `@path/to/file` to load prompt text from a file. | +| `agentArgs` | No | Additional arguments forwarded directly to the agent CLI. | **Options:** -| Option | Default | Description | -|--------|---------|-------------| -| `--model ` | Agent default | Model identifier override. | -| `-C, --cwd ` | Current dir | Working directory for the agent. | -| `--stdin` | `false` | Read the prompt from stdin. | -| `-i, --interactive` | `false` | Launch in interactive TUI mode (inherits stdio). | -| `--mode ` | Prompts (`--yes`: `yolo`) | Permission mode: `yolo` (full access), `edit` (file edits only), `read` (read-only). Non-TTY runs must pass `--mode` or `--yes`. | -| `--resume-thread-id ` | None | Resume a prior provider thread/session before sending the prompt. | -| `--log-dir ` | Default log dir | Directory override for ACP JSONL spawn logs. | -| `--log-file-name ` | Generated | Filename override for the spawn log. Requires `--log-dir`. | -| `--log-content` | `false` | Include message and tool content in ACP JSONL spawn logs. Logs are redacted by default. | -| `--capture-otel` | `false` | Capture native OpenTelemetry emitted by the spawned agent when supported. | -| `--capture-otel-content` | `false` | Include prompt and tool content in captured native OpenTelemetry. | -| `--activity-timeout-ms ` | None | Kill the agent after this many milliseconds of stdout/stderr inactivity. | -| `--mcp-servers ` | None | MCP servers to inject at spawn time. Accepts inline JSON or `@path/to/file.json`. Supports `command`, optional `args`, `env`, and `timeout` (seconds). Deprecated alias: `--mcp-config`. | +| Option | Default | Description | +| ----------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--model ` | Agent default | Model identifier override. | +| `-C, --cwd ` | Current dir | Working directory for the agent. | +| `--stdin` | `false` | Read the prompt from stdin. | +| `-i, --interactive` | `false` | Launch in interactive TUI mode (inherits stdio). | +| `--mode ` | Prompts (`--yes`: `yolo`) | Permission mode: `yolo` (full access), `edit` (file edits only), `read` (read-only). Non-TTY runs must pass `--mode` or `--yes`. | +| `--resume-thread-id ` | None | Resume a prior provider thread/session before sending the prompt. | +| `--log-dir ` | Default log dir | Directory override for ACP JSONL spawn logs. | +| `--log-file-name ` | Generated | Filename override for the spawn log. Requires `--log-dir`. | +| `--log-content` | `false` | Include message and tool content in ACP JSONL spawn logs. Logs are redacted by default. | +| `--capture-otel` | `false` | Capture native OpenTelemetry emitted by the spawned agent when supported. | +| `--capture-otel-content` | `false` | Include prompt and tool content in captured native OpenTelemetry. | +| `--activity-timeout-ms ` | None | Kill the agent after this many milliseconds of stdout/stderr inactivity. | +| `--mcp-servers ` | None | MCP servers to inject at spawn time. Accepts inline JSON or `@path/to/file.json`. Supports `command`, optional `args`, `env`, and `timeout` (seconds). Deprecated alias: `--mcp-config`. | **Behavior:** @@ -468,15 +469,15 @@ poe-code code-review **Subcommands:** -| Subcommand | Description | -|------------|-------------| -| `install` | Install repo-local reviewer profiles and prompts. | -| `profiles` | List repo-local reviewer profiles. | -| `ingest ` | Build a runtime reviewer profile from GitHub review history. | -| `run ` | Fetch a PR, run reviewer agents, and create a YAML draft. | -| `drafts ` | Read the active YAML draft for a PR. | -| `commit ` | Validate and publish the merged draft to GitHub; use `--dry-run` to preview. | -| `agent-mcp` | Run the stdio MCP server used by spawned review agents. | +| Subcommand | Description | +| -------------------------- | ---------------------------------------------------------------------------- | +| `install` | Install repo-local reviewer profiles and prompts. | +| `profiles` | List repo-local reviewer profiles. | +| `ingest ` | Build a runtime reviewer profile from GitHub review history. | +| `run ` | Fetch a PR, run reviewer agents, and create a YAML draft. | +| `drafts ` | Read the active YAML draft for a PR. | +| `commit ` | Validate and publish the merged draft to GitHub; use `--dry-run` to preview. | +| `agent-mcp` | Run the stdio MCP server used by spawned review agents. | **Examples:** @@ -498,16 +499,16 @@ poe-code research [prompt] [agentArgs...] **Options:** -| Option | Default | Description | -|--------|---------|-------------| -| `--agent ` | Prompts | Agent to use for research. | -| `--model ` | Agent default | Model override. | -| `--mode ` | `read` | Permission mode (defaults to `read`, more restrictive than `spawn`). | -| `-C, --cwd ` | Current dir | Working directory. | -| `--path ` | None | Local directory to research. | -| `--github ` | None | Clone and research a GitHub repo. | -| `--stdin` | `false` | Read prompt from stdin. | -| `--keep` | `false` | Keep the cloned repo when using `--github`. | +| Option | Default | Description | +| ------------------ | ------------- | -------------------------------------------------------------------- | +| `--agent ` | Prompts | Agent to use for research. | +| `--model ` | Agent default | Model override. | +| `--mode ` | `read` | Permission mode (defaults to `read`, more restrictive than `spawn`). | +| `-C, --cwd ` | Current dir | Working directory. | +| `--path ` | None | Local directory to research. | +| `--github ` | None | Clone and research a GitHub repo. | +| `--stdin` | `false` | Read prompt from stdin. | +| `--keep` | `false` | Keep the cloned repo when using `--github`. | **Examples:** @@ -537,10 +538,10 @@ poe-code wrap [agentArgs...] **Arguments:** -| Argument | Required | Description | -|----------|----------|-------------| -| `agent` | Yes | Agent to wrap. | -| `agentArgs` | No | Arguments forwarded to the agent CLI. | +| Argument | Required | Description | +| ----------- | -------- | ------------------------------------- | +| `agent` | Yes | Agent to wrap. | +| `agentArgs` | No | Arguments forwarded to the agent CLI. | **Behavior:** @@ -575,28 +576,29 @@ poe-code test [agent] **Arguments:** -| Argument | Required | Description | -|----------|----------|-------------| -| `agent` | No | Agent to test. Prompts if omitted. | +| Argument | Required | Description | +| -------- | -------- | ---------------------------------- | +| `agent` | No | Agent to test. Prompts if omitted. | **Options:** -| Option | Description | -|--------|-------------| -| `--isolated` | Run the health check using isolated configuration instead of global config. | -| `--model ` | Model override for the health check. | +| Option | Description | +| ----------------- | --------------------------------------------------------------------------- | +| `--isolated` | Run the health check using isolated configuration instead of global config. | +| `--model ` | Model override for the health check. | **Behavior:** Each agent has a health check that spawns the agent with a known prompt and validates the expected output: -| Agent | Expected Output | -|-------|----------------| +| Agent | Expected Output | +| ----------- | ---------------- | | Claude Code | `CLAUDE_CODE_OK` | -| Codex | `CODEX_OK` | -| OpenCode | `OPEN_CODE_OK` | -| Kimi | `KIMI_OK` | -| Goose | `GOOSE_OK` | +| Codex | `CODEX_OK` | +| OpenCode | `OPEN_CODE_OK` | +| Kimi | `KIMI_OK` | +| Goose | `GOOSE_OK` | +| Cursor | `CURSOR_OK` | **Examples:** @@ -604,6 +606,7 @@ Each agent has a health check that spawns the agent with a known prompt and vali poe-code test claude-code poe-code test codex --isolated poe-code test opencode --model anthropic/claude-sonnet-4.6 +poe-code test cursor poe-code test goose ``` @@ -619,19 +622,20 @@ poe-code install [agent] **Arguments:** -| Argument | Required | Description | -|----------|----------|-------------| -| `agent` | No | Agent to install. Prompts if omitted. | +| Argument | Required | Description | +| -------- | -------- | ------------------------------------- | +| `agent` | No | Agent to install. Prompts if omitted. | **Installation methods per agent:** -| Agent | Method | -|-------|--------| -| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` (Unix) or PowerShell (Windows) | -| Codex | `npm install -g @openai/codex` | -| OpenCode | `npm install -g opencode-ai` | -| Kimi | `uv tool install --python 3.13 kimi-cli` | -| Goose | `brew install block-goose-cli` (macOS) or `curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh \| CONFIGURE=false bash` | +| Agent | Method | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` (Unix) or PowerShell (Windows) | +| Codex | `npm install -g @openai/codex` | +| OpenCode | `npm install -g opencode-ai` | +| Kimi | `uv tool install --python 3.13 kimi-cli` | +| Goose | `brew install block-goose-cli` (macOS) or `curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh \| CONFIGURE=false bash` | +| Cursor | `curl https://cursor.com/install -fsS \| bash` (macOS/Linux) | **Examples:** @@ -639,6 +643,7 @@ poe-code install [agent] poe-code install claude-code poe-code install codex poe-code install opencode +poe-code install cursor poe-code install kimi poe-code install goose ``` @@ -659,20 +664,20 @@ poe-code generate audio [prompt] **Options (all subcommands):** -| Option | Description | -|--------|-------------| -| `--model ` | Model identifier. Uses type-specific defaults if omitted. | -| `--param ` | Additional parameters (repeatable). Passed as `extra_body` to the API. | +| Option | Description | +| --------------------- | ------------------------------------------------------------------------------ | +| `--model ` | Model identifier. Uses type-specific defaults if omitted. | +| `--param ` | Additional parameters (repeatable). Passed as `extra_body` to the API. | | `-o, --output ` | Output file path (media subcommands only). Auto-generates filename if omitted. | **Default models:** -| Type | Default Model | Environment Override | -|------|---------------|---------------------| -| Text | `anthropic/claude-sonnet-4.6` | `POE_TEXT_MODEL` | -| Image | `google/nano-banana-pro` | `POE_IMAGE_MODEL` | -| Video | `google/veo-3.1` | `POE_VIDEO_MODEL` | -| Audio | `elevenlabs/elevenlabs-v3` | `POE_AUDIO_MODEL` | +| Type | Default Model | Environment Override | +| ----- | ----------------------------- | -------------------- | +| Text | `anthropic/claude-sonnet-4.6` | `POE_TEXT_MODEL` | +| Image | `google/nano-banana-pro` | `POE_IMAGE_MODEL` | +| Video | `google/veo-3.1` | `POE_VIDEO_MODEL` | +| Audio | `elevenlabs/elevenlabs-v3` | `POE_AUDIO_MODEL` | **Examples:** @@ -724,10 +729,10 @@ Display usage history with filtering and pagination. **Options:** -| Option | Description | -|--------|-------------| -| `--filter ` | Filter results by model name (substring match). | -| `--pages ` | Number of pages to auto-load. Prompts for "Load more?" if not specified. | +| Option | Description | +| ------------------ | ------------------------------------------------------------------------ | +| `--filter ` | Filter results by model name (substring match). | +| `--pages ` | Number of pages to auto-load. Prompts for "Load more?" if not specified. | **Output columns:** Date, Model, Cost (USD), Cost (Points), Input Tokens, Output Tokens, Cache Discount Tokens @@ -759,27 +764,27 @@ poe-code models **Options:** -| Option | Description | -|--------|-------------| -| `--provider ` | Filter by provider (substring match). | -| `--model ` | Filter by model ID (exact match, case-insensitive). | -| `--search ` | Search model ID and provider name (substring match). | -| `--feature ` | Filter by feature: `tools`, `web_search`, `reasoning` (exact match). | -| `--endpoint ` | Filter by supported endpoint, for example `/v1/responses` or `/v1/chat/completions`. | -| `--input ` | Filter by input modalities: `text`, `image` (comma-separated). | -| `--output ` | Filter by output modalities: `text`, `image`, `video`, `audio` (comma-separated). | -| `--tools` | Shorthand for `--feature tools`. | -| `--since ` | Show models added within duration: `7d`, `2w`, `3mo`, `1y`. | -| `--view ` | Table view mode. See below. | +| Option | Description | +| ----------------------- | ------------------------------------------------------------------------------------ | +| `--provider ` | Filter by provider (substring match). | +| `--model ` | Filter by model ID (exact match, case-insensitive). | +| `--search ` | Search model ID and provider name (substring match). | +| `--feature ` | Filter by feature: `tools`, `web_search`, `reasoning` (exact match). | +| `--endpoint ` | Filter by supported endpoint, for example `/v1/responses` or `/v1/chat/completions`. | +| `--input ` | Filter by input modalities: `text`, `image` (comma-separated). | +| `--output ` | Filter by output modalities: `text`, `image`, `video`, `audio` (comma-separated). | +| `--tools` | Shorthand for `--feature tools`. | +| `--since ` | Show models added within duration: `7d`, `2w`, `3mo`, `1y`. | +| `--view ` | Table view mode. See below. | **View modes:** -| View | Description | -|------|-------------| -| `capabilities` (default) | Model name, date, modalities, context window, reasoning, features. | -| `pricing` | Per-model pricing: input/output $/MTok, cache read/write, per-request cost. | -| `parameters` | Model parameters with types, defaults, and value ranges. | -| `raw` | Full model data in YAML format. | +| View | Description | +| ------------------------ | --------------------------------------------------------------------------- | +| `capabilities` (default) | Model name, date, modalities, context window, reasoning, features. | +| `pricing` | Per-model pricing: input/output $/MTok, cache read/write, per-request cost. | +| `parameters` | Model parameters with types, defaults, and value ranges. | +| `raw` | Full model data in YAML format. | **Examples:** @@ -834,18 +839,18 @@ poe-code mcp serve **Options:** -| Option | Default | Description | -|--------|---------|-------------| -| `--output-format ` | `url` | Preferred media output format(s). Values: `url`, `base64`, `markdown`, `markdown_instructions`. Comma-separated for fallback chain. | +| Option | Default | Description | +| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `--output-format ` | `url` | Preferred media output format(s). Values: `url`, `base64`, `markdown`, `markdown_instructions`. Comma-separated for fallback chain. | **Output format details:** -| Format | Description | -|--------|-------------| -| `url` | Returns media URL directly. | -| `base64` | Returns base64-encoded content as an MCP Image/Audio content block. Not supported for video. | -| `markdown` | Returns markdown-formatted link: `![Image](url)` for images, `[filename](url)` for video/audio. | -| `markdown_instructions` | Returns instructions for the agent to render the media in chat. | +| Format | Description | +| ----------------------- | ----------------------------------------------------------------------------------------------- | +| `url` | Returns media URL directly. | +| `base64` | Returns base64-encoded content as an MCP Image/Audio content block. Not supported for video. | +| `markdown` | Returns markdown-formatted link: `![Image](url)` for images, `[filename](url)` for video/audio. | +| `markdown_instructions` | Returns instructions for the agent to render the media in chat. | **Examples:** @@ -873,28 +878,30 @@ poe-code mcp configure [agent] **Options:** -| Option | Description | -|--------|-------------| +| Option | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `-y, --yes` | Skip agent prompt. Uses `core.defaultAgent` / `POE_DEFAULT_AGENT` when set; otherwise defaults to `claude-code`. Without `--yes`, an omitted agent always prompts and non-TTY runs must pass an agent. | **Supported agents and their MCP config locations:** -| Agent | Config File | Config Key | -|-------|------------|------------| -| Claude Code | `~/.claude.json` | `mcpServers` | -| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | `mcpServers` | -| Claude Desktop (Windows) | `~/AppData/Roaming/Claude/claude_desktop_config.json` | `mcpServers` | -| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` | -| Codex | `~/.codex/config.toml` | `mcp_servers` | -| OpenCode | `~/.config/opencode/opencode.json` | `mcp` | -| Kimi | `~/.kimi/mcp.json` | `mcpServers` | -| Goose | `~/.config/goose/config.yaml` | `extensions` | +| Agent | Config File | Config Key | +| ------------------------ | ----------------------------------------------------------------- | ------------- | +| Claude Code | `~/.claude.json` | `mcpServers` | +| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | `mcpServers` | +| Claude Desktop (Windows) | `~/AppData/Roaming/Claude/claude_desktop_config.json` | `mcpServers` | +| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` | +| Codex | `~/.codex/config.toml` | `mcp_servers` | +| OpenCode | `~/.config/opencode/opencode.json` | `mcp` | +| Cursor | `~/.cursor/mcp.json` | `mcpServers` | +| Kimi | `~/.kimi/mcp.json` | `mcpServers` | +| Goose | `~/.config/goose/config.yaml` | `extensions` | **Examples:** ```bash poe-code mcp configure claude-code poe-code mcp configure codex +poe-code mcp configure cursor poe-code mcp configure goose poe-code mcp configure --yes # uses configured default, or claude-code when none is set ``` @@ -923,11 +930,11 @@ poe-code skill configure [agent] **Options:** -| Option | Description | -|--------|-------------| +| Option | Description | +| ---------------- | -------------------------------------------- | | `--agent ` | Agent to configure (alias for the argument). | -| `--local` | Use local scope (project directory). | -| `--global` | Use global scope (home directory). | +| `--local` | Use local scope (project directory). | +| `--global` | Use global scope (home directory). | #### `skill unconfigure` @@ -939,12 +946,12 @@ poe-code skill unconfigure [agent] **Options:** -| Option | Description | -|--------|-------------| -| `--agent ` | Agent to unconfigure. | -| `--local` | Local scope. | -| `--global` | Global scope. | -| `--force` | Remove directory even if it contains files. | +| Option | Description | +| ---------------- | ------------------------------------------- | +| `--agent ` | Agent to unconfigure. | +| `--local` | Local scope. | +| `--global` | Global scope. | +| `--force` | Remove directory even if it contains files. | **Examples:** @@ -976,15 +983,15 @@ poe-code pipeline run [--plan | --plans ] **Options:** -| Option | Description | -|--------|-------------| -| `--agent ` | Agent for pipeline steps. Without `--yes`, omission prompts even when a default agent is configured. With `--yes`, omission uses `core.defaultAgent` / `POE_DEFAULT_AGENT` when set, otherwise `claude-code`. | -| `--model ` | Model override passed to the selected agent. | -| `--tui` / `--no-tui` | Enable or disable the live pipeline dashboard for this run. | -| `--task ` | Run only a single task ID from the plan. | -| `--plan ` | Run one pipeline plan file. | -| `--plans ` | Run multiple plan files sequentially. | -| `--max-runs ` | Stop after `n` agent executions. | +| Option | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--agent ` | Agent for pipeline steps. Without `--yes`, omission prompts even when a default agent is configured. With `--yes`, omission uses `core.defaultAgent` / `POE_DEFAULT_AGENT` when set, otherwise `claude-code`. | +| `--model ` | Model override passed to the selected agent. | +| `--tui` / `--no-tui` | Enable or disable the live pipeline dashboard for this run. | +| `--task ` | Run only a single task ID from the plan. | +| `--plan ` | Run one pipeline plan file. | +| `--plans ` | Run multiple plan files sequentially. | +| `--max-runs ` | Stop after `n` agent executions. | #### `pipeline init` @@ -996,11 +1003,11 @@ poe-code pipeline init [question] [--source | --sources ] **Options:** -| Option | Description | -|--------|-------------| -| `--agent ` | Agent used to generate plans. | -| `--model ` | Model override passed to that agent. | -| `--source ` | Convert one source markdown file. | +| Option | Description | +| ---------------------- | --------------------------------------- | +| `--agent ` | Agent used to generate plans. | +| `--model ` | Model override passed to that agent. | +| `--source ` | Convert one source markdown file. | | `--sources ` | Convert multiple source markdown files. | **Behavior notes:** @@ -1051,14 +1058,14 @@ poe-code memory **Subcommands:** -| Subcommand | Description | -|------------|-------------| -| `init` | Create `.poe-code/memory/` with `INDEX.md`, `LOG.md`, and `pages/`. | -| `ls` | List memory pages with one-line descriptions. | -| `show ` | Print a memory page (path relative to `pages/`). | -| `search ` | Search memory files for a substring. | -| `status [--no-tokens]` | Show counts/size and optional token stats. | -| `clear` | Delete all memory content and reinitialize `INDEX.md`/`LOG.md`. | +| Subcommand | Description | +| ---------------------- | ------------------------------------------------------------------- | +| `init` | Create `.poe-code/memory/` with `INDEX.md`, `LOG.md`, and `pages/`. | +| `ls` | List memory pages with one-line descriptions. | +| `show ` | Print a memory page (path relative to `pages/`). | +| `search ` | Search memory files for a substring. | +| `status [--no-tokens]` | Show counts/size and optional token stats. | +| `clear` | Delete all memory content and reinitialize `INDEX.md`/`LOG.md`. | **Behavior notes:** @@ -1102,18 +1109,18 @@ function spawn( **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `service` | `string` | Agent identifier: `"claude-code"`, `"codex"`, `"opencode"`, `"kimi"` | -| `prompt` | `string` | The prompt to send to the agent | -| `options` | `SpawnOptions` | See [SpawnOptions](#spawnoptions) | +| Parameter | Type | Description | +| --------- | -------------- | ------------------------------------------------------------------------------------------- | +| `service` | `string` | Agent identifier: `"claude-code"`, `"codex"`, `"cursor"`, `"opencode"`, `"kimi"`, `"goose"` | +| `prompt` | `string` | The prompt to send to the agent | +| `options` | `SpawnOptions` | See [SpawnOptions](#spawnoptions) | **Return value:** ```typescript { - events: AsyncIterable; // Stream of ACP events (empty for non-streaming agents) - result: Promise; // Final result with stdout, stderr, exitCode + events: AsyncIterable; // Stream of ACP events (empty for non-streaming agents) + result: Promise; // Final result with stdout, stderr, exitCode } ``` @@ -1151,10 +1158,10 @@ const { result: r2 } = spawn("codex", { const { result: r3 } = spawn("claude-code", { prompt: "Use the filesystem tool to list files", mcpServers: { - "filesystem": { + filesystem: { command: "/usr/local/bin/fs-mcp-server", args: ["--root", "/tmp"], - env: { "DEBUG": "true" } + env: { DEBUG: "true" } } } }); @@ -1234,11 +1241,11 @@ console.log(result.content); // Generated text **Parameters:** -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | The generation prompt. | -| `options.model` | `string` | No | Model override. Default: `anthropic/claude-sonnet-4.6` or `POE_TEXT_MODEL` env. | -| `options.params` | `Record` | No | Extra parameters passed as `extra_body` to the API. | +| Parameter | Type | Required | Description | +| ---------------- | ------------------------ | -------- | ------------------------------------------------------------------------------- | +| `prompt` | `string` | Yes | The generation prompt. | +| `options.model` | `string` | No | Model override. Default: `anthropic/claude-sonnet-4.6` or `POE_TEXT_MODEL` env. | +| `options.params` | `Record` | No | Extra parameters passed as `extra_body` to the API. | **Returns:** `Promise` with `{ content: string }` @@ -1253,17 +1260,17 @@ const result = await generateImage("A futuristic city at sunset", { model: "google/nano-banana-pro" }); -console.log(result.url); // URL to the generated image +console.log(result.url); // URL to the generated image console.log(result.mimeType); // e.g., "image/png" ``` **Parameters:** -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | Image generation prompt. | -| `options.model` | `string` | No | Default: `google/nano-banana-pro` or `POE_IMAGE_MODEL` env. | -| `options.params` | `Record` | No | Extra parameters. | +| Parameter | Type | Required | Description | +| ---------------- | ------------------------ | -------- | ----------------------------------------------------------- | +| `prompt` | `string` | Yes | Image generation prompt. | +| `options.model` | `string` | No | Default: `google/nano-banana-pro` or `POE_IMAGE_MODEL` env. | +| `options.params` | `Record` | No | Extra parameters. | **Returns:** `Promise` with `{ url: string, mimeType?: string }` @@ -1451,22 +1458,22 @@ interface McpSpawnServer { ### Claude Code Provider -| Property | Value | -|----------|-------| -| ID | `claude-code` | -| Aliases | `claude` | -| Binary | `claude` | -| Config File | `~/.claude/settings.json` | -| Config Format | JSON | -| Branding | `#C15F3C` | +| Property | Value | +| ------------- | ------------------------- | +| ID | `claude-code` | +| Aliases | `claude` | +| Binary | `claude` | +| Config File | `~/.claude/settings.json` | +| Config Format | JSON | +| Branding | `#C15F3C` | **Models:** -| Choice Label | Model ID | -|-------------|----------| -| haiku | `anthropic/claude-haiku-4.5` | +| Choice Label | Model ID | +| ---------------- | ----------------------------- | +| haiku | `anthropic/claude-haiku-4.5` | | sonnet (default) | `anthropic/claude-sonnet-4.6` | -| opus | `anthropic/claude-opus-4.7` | +| opus | `anthropic/claude-opus-4.7` | **Configuration mutations (configure):** @@ -1485,6 +1492,7 @@ interface McpSpawnServer { **Unconfigure mutations:** Prune these keys from `~/.claude/settings.json`: + - `apiKeyHelper` - `env.ANTHROPIC_BASE_URL` - `env.ANTHROPIC_DEFAULT_HAIKU_MODEL` @@ -1494,38 +1502,39 @@ Prune these keys from `~/.claude/settings.json`: **Isolated environment:** -| Variable | Type | Description | -|----------|------|-------------| -| `POE_API_KEY` | `poeApiKey` | API key from credentials | -| `ANTHROPIC_BASE_URL` (via cliSettings) | `poeBaseUrl` | Poe API base URL | +| Variable | Type | Description | +| -------------------------------------- | ------------ | ------------------------ | +| `POE_API_KEY` | `poeApiKey` | API key from credentials | +| `ANTHROPIC_BASE_URL` (via cliSettings) | `poeBaseUrl` | Poe API base URL | CLI settings: `apiKeyHelper: "echo $POE_API_KEY"` Config not required for isolation (`requiresConfig: false`). **Post-configure message:** + > If using VSCode - Open the Disable Login Prompt setting and check the box. vscode://settings/claudeCode.disableLoginPrompt **Spawn configuration:** -| Property | Value | -|----------|-------| -| Prompt flag | `-p` | -| Model flag | `--model` | -| Strip provider prefix | Yes | -| Model transform | Replace `.` with `-` (e.g., `claude-sonnet-4.6` → `claude-sonnet-4-6`) | -| Default args | `--output-format stream-json --verbose` | -| Stdin mode | Omit prompt, add `--input-format text` | -| Interactive args | (empty — defaults only) | -| Resume command | `--resume ` | +| Property | Value | +| --------------------- | ---------------------------------------------------------------------- | +| Prompt flag | `-p` | +| Model flag | `--model` | +| Strip provider prefix | Yes | +| Model transform | Replace `.` with `-` (e.g., `claude-sonnet-4.6` → `claude-sonnet-4-6`) | +| Default args | `--output-format stream-json --verbose` | +| Stdin mode | Omit prompt, add `--input-format text` | +| Interactive args | (empty — defaults only) | +| Resume command | `--resume ` | **Permission mode args:** -| Mode | Args | -|------|------| -| `yolo` | `--dangerously-skip-permissions` | +| Mode | Args | +| ------ | ------------------------------------------------------------------------------------------ | +| `yolo` | `--dangerously-skip-permissions` | | `edit` | `--permission-mode acceptEdits --allowedTools Bash,Read,Write,Edit,Glob,Grep,NotebookEdit` | -| `read` | `--permission-mode plan` | +| `read` | `--permission-mode plan` | **MCP args:** JSON format via `--mcp-servers` (also accepts `@path/to/file.json`; `--mcp-config` is deprecated alias) @@ -1533,24 +1542,24 @@ Config not required for isolation (`requiresConfig: false`). ### Codex Provider -| Property | Value | -|----------|-------| -| ID | `codex` | -| Binary | `codex` | -| Config File | `~/.codex/config.toml` | -| Config Format | TOML | -| Branding | Dark: `#D5D9DF`, Light: `#7A7F86` | +| Property | Value | +| ------------- | --------------------------------- | +| ID | `codex` | +| Binary | `codex` | +| Config File | `~/.codex/config.toml` | +| Config Format | TOML | +| Branding | Dark: `#D5D9DF`, Light: `#7A7F86` | **Models:** -| Model ID | Default | -|----------|---------| -| `openai/gpt-5.2-codex` | Yes | -| `openai/gpt-5.2` | | -| `openai/gpt-5.2-chat` | | -| `openai/gpt-5.2-pro` | | -| `openai/gpt-5.1` | | -| `openai/gpt-5.1-codex-mini` | | +| Model ID | Default | +| --------------------------- | ------- | +| `openai/gpt-5.2-codex` | Yes | +| `openai/gpt-5.2` | | +| `openai/gpt-5.2-chat` | | +| `openai/gpt-5.2-pro` | | +| `openai/gpt-5.1` | | +| `openai/gpt-5.1-codex-mini` | | **Additional prompts:** Reasoning effort (`low`, `medium`, `high`). Default: `medium`. @@ -1564,38 +1573,39 @@ Config not required for isolation (`requiresConfig: false`). **Unconfigure mutations:** Transform `~/.codex/config.toml`: + - Remove `model_provider` if it equals `"poe"` - Remove `model`, `model_reasoning_effort`, and provider config - Delete entire file if empty after pruning **Isolated environment:** -| Variable | Type | -|----------|------| -| `CODEX_HOME` | `isolatedDir` | +| Variable | Type | +| ----------------- | ------------- | +| `CODEX_HOME` | `isolatedDir` | | `XDG_CONFIG_HOME` | `isolatedDir` | Config probe: `config.toml` (isolated file). **Spawn configuration:** -| Property | Value | -|----------|-------| -| Prompt flag | `exec` (positional subcommand) | -| Model flag | `--model` | -| Strip provider prefix | Yes | -| Default args | `--skip-git-repo-check --json` | -| Stdin mode | Omit prompt, add `-` | -| Interactive args | `-a never` | -| Resume command | `resume -C ` | +| Property | Value | +| --------------------- | ------------------------------ | +| Prompt flag | `exec` (positional subcommand) | +| Model flag | `--model` | +| Strip provider prefix | Yes | +| Default args | `--skip-git-repo-check --json` | +| Stdin mode | Omit prompt, add `-` | +| Interactive args | `-a never` | +| Resume command | `resume -C ` | **Permission mode args:** -| Mode | Args | -|------|------| +| Mode | Args | +| ------ | ----------------------- | | `yolo` | `-s danger-full-access` | -| `edit` | `-s workspace-write` | -| `read` | `-s read-only` | +| `edit` | `-s workspace-write` | +| `read` | `-s read-only` | **MCP args:** TOML format via `-c` flags with inline table syntax @@ -1603,22 +1613,22 @@ Config probe: `config.toml` (isolated file). ### OpenCode Provider -| Property | Value | -|----------|-------| -| ID | `opencode` | -| Binary | `opencode` | -| Config Files | `~/.config/opencode/config.json`, `~/.local/share/opencode/auth.json` | -| Config Format | JSON | -| Branding | Dark: `#4A4F55`, Light: `#2F3338` | +| Property | Value | +| ------------- | --------------------------------------------------------------------- | +| ID | `opencode` | +| Binary | `opencode` | +| Config Files | `~/.config/opencode/config.json`, `~/.local/share/opencode/auth.json` | +| Config Format | JSON | +| Branding | Dark: `#4A4F55`, Light: `#2F3338` | **Models:** -| Model ID | -|----------| -| `anthropic/claude-opus-4.7` | +| Model ID | +| ----------------------------- | +| `anthropic/claude-opus-4.7` | | `anthropic/claude-sonnet-4.6` | -| `openai/gpt-5.2` | -| `google/gemini-3-pro` | +| `openai/gpt-5.2` | +| `google/gemini-3-pro` | Default: `anthropic/claude-sonnet-4.6` @@ -1651,10 +1661,10 @@ Default: `anthropic/claude-sonnet-4.6` **Isolated environment:** -| Variable | Type | Relative Path | -|----------|------|---------------| -| `XDG_CONFIG_HOME` | `isolatedDir` | `.config` | -| `XDG_DATA_HOME` | `isolatedDir` | `.local/share` | +| Variable | Type | Relative Path | +| ----------------- | ------------- | -------------- | +| `XDG_CONFIG_HOME` | `isolatedDir` | `.config` | +| `XDG_DATA_HOME` | `isolatedDir` | `.local/share` | Config probe: `.config/opencode/config.json` @@ -1662,43 +1672,93 @@ Config probe: `.config/opencode/config.json` **Spawn configuration:** -| Property | Value | -|----------|-------| -| Prompt flag | `run` (positional subcommand) | -| Model flag | `--model` | -| Strip provider prefix | No | -| Model transform | Adds `poe/` prefix if not present | -| Default args | `--format json` | -| Interactive prompt flag | `--prompt` | -| Resume command | ` --session ` | +| Property | Value | +| ----------------------- | --------------------------------- | +| Prompt flag | `run` (positional subcommand) | +| Model flag | `--model` | +| Strip provider prefix | No | +| Model transform | Adds `poe/` prefix if not present | +| Default args | `--format json` | +| Interactive prompt flag | `--prompt` | +| Resume command | ` --session ` | **Permission mode args:** -| Mode | Args | -|------|------| -| `yolo` | (empty) | -| `edit` | (empty) | +| Mode | Args | +| ------ | -------------- | +| `yolo` | (empty) | +| `edit` | (empty) | | `read` | `--agent plan` | --- +### Cursor Provider + +| Property | Value | +| ------------- | --------------------------------- | +| ID | `cursor` | +| Aliases | `cursor-agent` | +| Binary | `cursor-agent` | +| Config File | `~/.cursor/cli-config.json` | +| Config Format | JSON | +| Branding | Dark: `#FFFFFF`, Light: `#000000` | + +**Models:** + +Uses `DEFAULT_CURSOR_MODEL`, which follows `DEFAULT_FRONTIER_MODEL` (`anthropic/claude-opus-4.7`) unless the caller passes `--model`. Cursor strips provider prefixes at spawn time and converts Claude model dots to hyphens for the native CLI. + +**Configuration mutations (configure):** + +No Poe configuration is written. Cursor uses the authenticated `cursor-agent` installation and the user's Cursor account. + +**Install:** + +Runs `curl https://cursor.com/install -fsS | bash` on macOS and Linux. + +**Health check:** + +Spawns Cursor with the selected model and expects `CURSOR_OK`. + +**Spawn configuration:** + +| Property | Value | +| --------------------- | ------------------------------------------------------------------------------------- | +| Prompt flag | `-p` | +| Model flag | `--model` | +| Strip provider prefix | Yes | +| Model transform | Claude model dots become hyphens (for example, `claude-opus-4.7` → `claude-opus-4-7`) | +| Default args | `--output-format stream-json --trust --approve-mcps` | +| Stdin mode | Omit prompt flag | +| Interactive args | (empty — no default args) | +| Resume command | `--resume ` | + +**Permission mode args:** + +| Mode | Args | +| ------ | ---------------------------- | +| `yolo` | `--force --sandbox disabled` | +| `edit` | `--force` | +| `read` | `--mode plan` | + +**MCP config:** Cursor supports standard MCP config at `~/.cursor/mcp.json`. Spawn-time MCP writes a temporary `.cursor/mcp.json` under the spawn cwd, deep-merges the requested servers into any existing JSON object, and restores the previous content after the child exits. + ### Kimi Provider -| Property | Value | -|----------|-------| -| ID | `kimi` | -| Aliases | `kimi-cli` | -| Binary | `kimi` | -| Config File | `~/.kimi/config.toml` | -| Config Format | TOML | -| Branding | Dark: `#7B68EE`, Light: `#6A5ACD` | +| Property | Value | +| ------------- | --------------------------------- | +| ID | `kimi` | +| Aliases | `kimi-cli` | +| Binary | `kimi` | +| Config File | `~/.kimi/config.toml` | +| Config Format | TOML | +| Branding | Dark: `#7B68EE`, Light: `#6A5ACD` | **Models:** -| Model ID | Default | -|----------|---------| -| `novitaai/kimi-k2.5` | Yes | -| `novitaai/kimi-k2-thinking` | | +| Model ID | Default | +| --------------------------- | ------- | +| `novitaai/kimi-k2.5` | Yes | +| `novitaai/kimi-k2-thinking` | | **Configuration mutations (configure):** @@ -1712,14 +1772,15 @@ Config probe: `.config/opencode/config.json` **Unconfigure mutations:** Transform `~/.kimi/config.toml`: + - Remove `providers.poe` entry - Delete `providers` object if empty **Isolated environment:** -| Variable | Type | -|----------|------| -| `HOME` | `isolatedDir` | +| Variable | Type | +| -------- | ------------- | +| `HOME` | `isolatedDir` | Agent binary: `kimi-cli` (special name to avoid home directory stripping issues) @@ -1729,22 +1790,22 @@ Config probe: `.kimi/config.toml` **Spawn configuration:** -| Property | Value | -|----------|-------| -| Prompt flag | `-p` | -| Strip provider prefix | Yes | -| Default args | `--print --output-format stream-json` | -| Stdin mode | Omit prompt, add `--input-format stream-json` | -| Interactive prompt flag | `-p` | -| Resume command | `--session --work-dir ` | +| Property | Value | +| ----------------------- | --------------------------------------------- | +| Prompt flag | `-p` | +| Strip provider prefix | Yes | +| Default args | `--print --output-format stream-json` | +| Stdin mode | Omit prompt, add `--input-format stream-json` | +| Interactive prompt flag | `-p` | +| Resume command | `--session --work-dir ` | **Permission mode args:** -| Mode | Args | -|------|------| +| Mode | Args | +| ------ | -------- | | `yolo` | `--yolo` | -| `edit` | (empty) | -| `read` | (empty) | +| `edit` | (empty) | +| `read` | (empty) | **MCP args:** JSON format via `--mcp-servers` (also accepts `@path/to/file.json`; `--mcp-config` is deprecated alias) @@ -1752,13 +1813,13 @@ Config probe: `.kimi/config.toml` ### Goose Provider -| Property | Value | -|----------|-------| -| ID | `goose` | -| Binary | `goose` | -| Config File | `~/.config/goose/config.yaml` | -| Config Format | YAML | -| Branding | Dark: `#FF6B35`, Light: `#E85D26` | +| Property | Value | +| ------------- | --------------------------------- | +| ID | `goose` | +| Binary | `goose` | +| Config File | `~/.config/goose/config.yaml` | +| Config Format | YAML | +| Branding | Dark: `#FF6B35`, Light: `#E85D26` | **Models:** @@ -1779,10 +1840,10 @@ Uses `FRONTIER_MODELS` with default `anthropic/claude-opus-4.7`. **Isolated environment:** -| Variable | Type | Relative Path | -|----------|------|---------------| -| `HOME` | `isolatedDir` | `` | -| `XDG_CONFIG_HOME` | `isolatedDir` | `.config` | +| Variable | Type | Relative Path | +| ----------------- | ------------- | ------------- | +| `HOME` | `isolatedDir` | `` | +| `XDG_CONFIG_HOME` | `isolatedDir` | `.config` | Config probe: `.config/goose/config.yaml` @@ -1790,23 +1851,23 @@ Config probe: `.config/goose/config.yaml` **Spawn configuration:** -| Property | Value | -|----------|-------| -| Prompt flag | `--text` | -| Model flag | `--model` | -| Strip provider prefix | No | -| Default args | `run --output-format stream-json` | -| Stdin mode | Omit prompt, add `--instructions -` | -| Interactive args | `session` | -| Resume command | `run --resume --text continue` | +| Property | Value | +| --------------------- | ----------------------------------- | +| Prompt flag | `--text` | +| Model flag | `--model` | +| Strip provider prefix | No | +| Default args | `run --output-format stream-json` | +| Stdin mode | Omit prompt, add `--instructions -` | +| Interactive args | `session` | +| Resume command | `run --resume --text continue` | **Permission mode env:** -| Mode | Value | -|------|-------| -| `yolo` | `GOOSE_MODE=auto` | +| Mode | Value | +| ------ | -------------------------- | +| `yolo` | `GOOSE_MODE=auto` | | `edit` | `GOOSE_MODE=smart_approve` | -| `read` | `GOOSE_MODE=chat` | +| `read` | `GOOSE_MODE=chat` | **MCP args:** repeated `--with-extension " "` @@ -1890,9 +1951,7 @@ export const provider = createProvider/` | -| `poeApiKey` | Resolved from stored credentials | -| `poeBaseUrl` | Resolved from environment/defaults | -| String literal | Used as-is | +| Kind | Description | +| -------------- | --------------------------------------------------- | +| `isolatedDir` | Maps to a directory under `~/.poe-code//` | +| `poeApiKey` | Resolved from stored credentials | +| `poeBaseUrl` | Resolved from environment/defaults | +| String literal | Used as-is | --- @@ -1938,52 +1998,52 @@ The `poe-code` MCP server exposes Poe API generation capabilities as MCP tools t Generate text using any Poe bot. -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `bot_name` | `string` | Yes | Name of the Poe bot/model to query. | -| `message` | `string` | Yes | Message to send to the bot. | -| `params` | `object` | No | Additional parameters. | +| Parameter | Type | Required | Description | +| ---------- | -------- | -------- | ----------------------------------- | +| `bot_name` | `string` | Yes | Name of the Poe bot/model to query. | +| `message` | `string` | Yes | Message to send to the bot. | +| `params` | `object` | No | Additional parameters. | #### generate_image Generate an image. -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | Text prompt for image generation. | -| `bot_name` | `string` | No | Bot to use. Default: `google/nano-banana-pro`. | -| `params` | `object` | No | Additional parameters. | +| Parameter | Type | Required | Description | +| ---------- | -------- | -------- | ---------------------------------------------- | +| `prompt` | `string` | Yes | Text prompt for image generation. | +| `bot_name` | `string` | No | Bot to use. Default: `google/nano-banana-pro`. | +| `params` | `object` | No | Additional parameters. | #### generate_video Generate a video. -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | Text prompt for video generation. | -| `bot_name` | `string` | No | Bot to use. Default: `google/veo-3.1`. | -| `params` | `object` | No | Additional parameters. | +| Parameter | Type | Required | Description | +| ---------- | -------- | -------- | -------------------------------------- | +| `prompt` | `string` | Yes | Text prompt for video generation. | +| `bot_name` | `string` | No | Bot to use. Default: `google/veo-3.1`. | +| `params` | `object` | No | Additional parameters. | #### generate_audio Convert text to audio. -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | Text to convert to audio. | -| `bot_name` | `string` | No | Bot to use. Default: `elevenlabs/elevenlabs-v3`. | -| `params` | `object` | No | Additional parameters. | +| Parameter | Type | Required | Description | +| ---------- | -------- | -------- | ------------------------------------------------ | +| `prompt` | `string` | Yes | Text to convert to audio. | +| `bot_name` | `string` | No | Bot to use. Default: `elevenlabs/elevenlabs-v3`. | +| `params` | `object` | No | Additional parameters. | ### MCP Output Formats When serving media (images, video, audio), the MCP server supports multiple output formats: -| Format | Description | Supports | -|--------|-------------|----------| -| `url` | Returns the media URL as text. | All media types | -| `base64` | Returns base64-encoded content as an MCP Image/Audio content block. | Images, Audio (not video) | -| `markdown` | Returns markdown: `![Image](url)` for images, `[filename](url)` for video/audio. | All media types | -| `markdown_instructions` | Returns instructions for the agent to render the media in chat with specific action text. | All media types | +| Format | Description | Supports | +| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------- | +| `url` | Returns the media URL as text. | All media types | +| `base64` | Returns base64-encoded content as an MCP Image/Audio content block. | Images, Audio (not video) | +| `markdown` | Returns markdown: `![Image](url)` for images, `[filename](url)` for video/audio. | All media types | +| `markdown_instructions` | Returns instructions for the agent to render the media in chat with specific action text. | All media types | Formats can be combined as a comma-separated fallback chain: `--output-format base64,url` tries base64 first, falls back to URL. @@ -1992,6 +2052,7 @@ Formats can be combined as a comma-separated fallback chain: `--output-format ba The MCP configuration format varies by agent: **Standard shape** (Claude Code, Claude Desktop, Kimi): + ```json { "poe-code": { @@ -2003,6 +2064,7 @@ The MCP configuration format varies by agent: ``` **OpenCode shape:** + ```json { "poe-code": { @@ -2015,6 +2077,7 @@ The MCP configuration format varies by agent: ``` **Codex shape** (TOML): + ```toml [mcp_servers.poe-code] command = "poe-code" @@ -2022,6 +2085,7 @@ args = ["mcp", "serve", "--output-format", "url"] ``` **Goose shape** (YAML): + ```yaml extensions: poe-code: @@ -2040,11 +2104,11 @@ extensions: ### Spawn Modes -| Mode | Description | Claude Code Args | Codex Args | OpenCode Args | Kimi Args | Goose | -|------|-------------|-----------------|------------|---------------|-----------|-------| -| `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `-s danger-full-access` | (none) | `--yolo` | `GOOSE_MODE=auto` | -| `edit` | Can edit files, restricted commands | `--permission-mode acceptEdits --allowedTools Bash,Read,Write,Edit,Glob,Grep,NotebookEdit` | `-s workspace-write` | (none) | (none) | `GOOSE_MODE=smart_approve` | -| `read` | Read-only, no modifications | `--permission-mode plan` | `-s read-only` | `--agent plan` | (none) | `GOOSE_MODE=chat` | +| Mode | Description | Claude Code Args | Codex Args | Cursor Args | OpenCode Args | Kimi Args | Goose | +| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------- | -------------- | --------- | -------------------------- | +| `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `-s danger-full-access` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | +| `edit` | Can edit files, restricted commands | `--permission-mode acceptEdits --allowedTools Bash,Read,Write,Edit,Glob,Grep,NotebookEdit` | `-s workspace-write` | `--force` | (none) | (none) | `GOOSE_MODE=smart_approve` | +| `read` | Read-only, no modifications | `--permission-mode plan` | `-s read-only` | `--mode plan` | `--agent plan` | (none) | `GOOSE_MODE=chat` | ### Streaming (ACP Events) @@ -2064,13 +2128,14 @@ const final = await result; **Streaming support by agent:** -| Agent | Streaming | Output Format | -|-------|-----------|---------------| -| Claude Code | Yes | `stream-json` | -| Codex | Yes | `json` | -| OpenCode | Yes | `json` | -| Kimi | Yes | `stream-json` | -| Goose | Yes | `stream-json` | +| Agent | Streaming | Output Format | +| ----------- | --------- | ------------- | +| Claude Code | Yes | `stream-json` | +| Codex | Yes | `json` | +| OpenCode | Yes | `json` | +| Cursor | Yes | `stream-json` | +| Kimi | Yes | `stream-json` | +| Goose | Yes | `stream-json` | Use `renderAcpStream()` from `@poe-code/agent-spawn` for pretty-printed terminal output, or `spawn.pretty()` from the SDK. @@ -2079,6 +2144,7 @@ Use `renderAcpStream()` from `@poe-code/agent-spawn` for pretty-printed terminal Inject MCP servers into an agent session at spawn time. This allows agents to use additional tools during a session. **CLI:** + ```bash poe-code spawn claude-code "Use the database tool" \ --mcp-servers '{"db": {"command": "/usr/local/bin/db-server", "args": ["--port", "5432"]}}' @@ -2088,14 +2154,15 @@ poe-code spawn claude-code "Use the database tool" --mcp-servers @./mcp.json ``` **SDK:** + ```typescript const { result } = spawn("claude-code", { prompt: "Query the database for user stats", mcpServers: { - "db": { + db: { command: "/usr/local/bin/db-server", args: ["--port", "5432"], - env: { "DB_HOST": "localhost" } + env: { DB_HOST: "localhost" } } } }); @@ -2103,15 +2170,16 @@ const { result } = spawn("claude-code", { **MCP serialization per agent:** -| Agent | Format | Flag | -|-------|--------|------| -| Claude Code | JSON or `@file` via `--mcp-servers` | `--mcp-servers` | -| Codex | TOML inline tables via `-c` flags | `-c mcp_servers.name.command="..."` | -| Kimi | JSON or `@file` via `--mcp-servers` | `--mcp-servers` | -| Goose | Repeated extension flags | `--with-extension " "` | -| OpenCode | JSON config serialized into `OPENCODE_CONFIG_CONTENT` | environment variable | +| Agent | Format | Flag | +| ----------- | --------------------------------------------------------------------------------------------- | ---------------------------------------- | +| Claude Code | JSON or `@file` via `--mcp-servers` | `--mcp-servers` | +| Codex | TOML inline tables via `-c` flags | `-c mcp_servers.name.command="..."` | +| Kimi | JSON or `@file` via `--mcp-servers` | `--mcp-servers` | +| Cursor | Temporary `.cursor/mcp.json` in the spawn cwd, deep-merged and restored after the child exits | config file | +| Goose | Repeated extension flags | `--with-extension " "` | +| OpenCode | JSON config serialized into `OPENCODE_CONFIG_CONTENT` | environment variable | -The same serialization runs for interactive spawns, so agents that receive MCP config through environment variables are configured before their TUI starts. +The same serialization runs for interactive spawns, so agents that receive MCP config through environment variables or temporary config files are configured before their TUI starts. ### Interactive Mode @@ -2130,6 +2198,7 @@ const { result } = spawn("claude-code", { ``` In interactive mode: + - stdio is inherited (agent gets direct terminal access) - No ACP event stream (events iterable is empty) - Agent runs its own UI @@ -2151,12 +2220,13 @@ cat prompt.txt | poe-code spawn claude-code **Stdin mode differences per agent:** -| Agent | Stdin Behavior | -|-------|---------------| -| Claude Code | Omits `-p` flag, adds `--input-format text` | -| Codex | Omits `exec` subcommand, adds `-` | -| Kimi | Omits `-p` flag, adds `--input-format stream-json` | -| Goose | Omits `--text`, adds `--instructions -` | +| Agent | Stdin Behavior | +| ----------- | -------------------------------------------------- | +| Claude Code | Omits `-p` flag, adds `--input-format text` | +| Codex | Omits `exec` subcommand, adds `-` | +| Kimi | Omits `-p` flag, adds `--input-format stream-json` | +| Cursor | Omits prompt flag; sends prompt on stdin | +| Goose | Omits `--text`, adds `--instructions -` | ### Resume Sessions @@ -2175,13 +2245,14 @@ const { result } = spawn("claude-code", { **Resume command format per agent:** -| Agent | Resume Args | -|-------|-------------| -| Claude Code | `--resume ` | -| Codex | `resume -C ` | -| OpenCode | ` --session ` | -| Kimi | `--session --work-dir ` | -| Goose | `run --resume --text continue` | +| Agent | Resume Args | +| ----------- | --------------------------------------- | +| Claude Code | `--resume ` | +| Codex | `resume -C ` | +| OpenCode | ` --session ` | +| Cursor | `--resume ` | +| Kimi | `--session --work-dir ` | +| Goose | `run --resume --text continue` | ### Spawn Configurations per Agent @@ -2221,6 +2292,23 @@ Interactive: -a never Resume: resume -C ``` +#### Cursor Spawn Config + +``` +Binary: cursor-agent +Prompt: -p +Model: --model (provider prefix stripped; Claude model dots become hyphens) +Default args: --output-format stream-json --trust --approve-mcps +Modes: + yolo: --force --sandbox disabled + edit: --force + read: --mode plan +MCP: temporary .cursor/mcp.json in the spawn cwd, restored after exit +Stdin: omit prompt flag +Interactive: (no extra args) +Resume: --resume +``` + #### OpenCode Spawn Config ``` @@ -2281,6 +2369,7 @@ Resume: run --resume --text continue **Location:** `~/.poe-code/credentials.json` **Format:** + ```json { "apiKey": "pb-xxx", @@ -2296,18 +2385,20 @@ Resume: run --resume --text continue ``` **Resolution priority:** + 1. `POE_API_KEY` environment variable 2. `~/.poe-code/credentials.json` file ### Provider Config Files -| Provider | File(s) | Format | -|----------|---------|--------| -| Claude Code | `~/.claude/settings.json` | JSON | -| Codex | `~/.codex/config.toml` | TOML | -| OpenCode | `~/.config/opencode/config.json` + `~/.local/share/opencode/auth.json` | JSON | -| Kimi | `~/.kimi/config.toml` | TOML | -| Goose | `~/.config/goose/config.yaml` + `~/.config/goose/secrets.yaml` + `~/.config/goose/custom_providers/custom_poe.json` | YAML + JSON | +| Provider | File(s) | Format | +| ----------- | ------------------------------------------------------------------------------------------------------------------- | ----------- | +| Claude Code | `~/.claude/settings.json` | JSON | +| Codex | `~/.codex/config.toml` | TOML | +| OpenCode | `~/.config/opencode/config.json` + `~/.local/share/opencode/auth.json` | JSON | +| Cursor | `~/.cursor/cli-config.json`, plus `.cursor/mcp.json` for spawn-time MCP | JSON | +| Kimi | `~/.kimi/config.toml` | TOML | +| Goose | `~/.config/goose/config.yaml` + `~/.config/goose/secrets.yaml` + `~/.config/goose/custom_providers/custom_poe.json` | YAML + JSON | ### Isolated Environments @@ -2316,6 +2407,7 @@ Isolated environments sandbox agent configuration to `~/.poe-code//` to a **Base directory:** `~/.poe-code//` **How it works:** + 1. Home directory paths are remapped to isolated directories 2. Environment variables override the agent's config/data paths 3. The agent binary runs with these overridden environment variables @@ -2323,11 +2415,11 @@ Isolated environments sandbox agent configuration to `~/.poe-code//` to a **Variable kinds:** -| Kind | Description | Example | -|------|-------------|---------| -| `isolatedDir` | Directory under isolated base, optionally with relative path | `CODEX_HOME` → `~/.poe-code/codex/` | -| `poeApiKey` | API key from credentials | `POE_API_KEY` → `pb-xxx` | -| `poeBaseUrl` | Poe API base URL | `ANTHROPIC_BASE_URL` → `https://api.poe.com/v1` | +| Kind | Description | Example | +| ------------- | ------------------------------------------------------------ | ----------------------------------------------- | +| `isolatedDir` | Directory under isolated base, optionally with relative path | `CODEX_HOME` → `~/.poe-code/codex/` | +| `poeApiKey` | API key from credentials | `POE_API_KEY` → `pb-xxx` | +| `poeBaseUrl` | Poe API base URL | `ANTHROPIC_BASE_URL` → `https://api.poe.com/v1` | **CLI settings injection:** Some agents support a `--settings` flag or equivalent for runtime configuration. The isolated env system can inject settings like `apiKeyHelper` and environment variables. @@ -2339,10 +2431,10 @@ Providers use a declarative mutation system from `@poe-code/config-mutations` fo ```typescript // Create a directory -fileMutation.ensureDirectory({ path: "~/.config/app" }) +fileMutation.ensureDirectory({ path: "~/.config/app" }); // Backup a file before modifying -fileMutation.backup({ target: "~/.config/app/config.json" }) +fileMutation.backup({ target: "~/.config/app/config.json" }); ``` #### Config Mutations @@ -2355,7 +2447,7 @@ configMutation.merge({ apiKey: ctx.apiKey, model: ctx.model }) -}) +}); // Custom transformation configMutation.transform({ @@ -2364,13 +2456,13 @@ configMutation.transform({ changed: true, content: { ...doc, modified: true } }) -}) +}); // Remove specific keys configMutation.prune({ target: "~/.config/app/config.json", shape: { apiKey: true, password: true } -}) +}); ``` #### Template Mutations @@ -2385,7 +2477,7 @@ templateMutation.mergeToml({ baseUrl: ctx.baseUrl, model: ctx.model }) -}) +}); ``` ### Dry Run @@ -2397,11 +2489,13 @@ poe-code configure claude --model opus --dry-run ``` Output shows: + - Files that would be created/modified - Unified diff of changes - Sensitive values are redacted (API keys, tokens) **Redacted keys:** + - JSON: `apiKey`, `api_key`, `apiKeyHelper` - Auth files: `key` - TOML: `experimental_bearer_token` @@ -2412,19 +2506,20 @@ Output shows: ### Default Models -| Constant | Value | Used By | -|----------|-------|---------| -| `DEFAULT_TEXT_MODEL` | `anthropic/claude-sonnet-4.6` | `generate text` | -| `DEFAULT_IMAGE_BOT` | `google/nano-banana-pro` | `generate image` | -| `DEFAULT_VIDEO_BOT` | `google/veo-3.1` | `generate video` | -| `DEFAULT_AUDIO_BOT` | `elevenlabs/elevenlabs-v3` | `generate audio` | -| `DEFAULT_FRONTIER_MODEL` | `anthropic/claude-opus-4.7` | OpenCode and Goose defaults | -| `DEFAULT_CLAUDE_CODE_MODEL` | `anthropic/claude-sonnet-4.6` | Claude Code default | -| `DEFAULT_CODEX_MODEL` | `openai/gpt-5.5` | Codex default | -| `DEFAULT_KIMI_MODEL` | `novitaai/kimi-k2.5` | Kimi default | -| `DEFAULT_GOOSE_MODEL` | `anthropic/claude-opus-4.7` | Goose default | -| `DEFAULT_REASONING` | `medium` | Codex reasoning effort | -| `PROVIDER_NAME` | `poe` | Provider identifier in configs | +| Constant | Value | Used By | +| --------------------------- | ----------------------------- | ------------------------------------ | +| `DEFAULT_TEXT_MODEL` | `anthropic/claude-sonnet-4.6` | `generate text` | +| `DEFAULT_IMAGE_BOT` | `google/nano-banana-pro` | `generate image` | +| `DEFAULT_VIDEO_BOT` | `google/veo-3.1` | `generate video` | +| `DEFAULT_AUDIO_BOT` | `elevenlabs/elevenlabs-v3` | `generate audio` | +| `DEFAULT_FRONTIER_MODEL` | `anthropic/claude-opus-4.7` | OpenCode, Cursor, and Goose defaults | +| `DEFAULT_CLAUDE_CODE_MODEL` | `anthropic/claude-sonnet-4.6` | Claude Code default | +| `DEFAULT_CODEX_MODEL` | `openai/gpt-5.5` | Codex default | +| `DEFAULT_KIMI_MODEL` | `novitaai/kimi-k2.5` | Kimi default | +| `DEFAULT_GOOSE_MODEL` | `anthropic/claude-opus-4.7` | Goose default | +| `DEFAULT_CURSOR_MODEL` | `anthropic/claude-opus-4.7` | Cursor health-check default | +| `DEFAULT_REASONING` | `medium` | Codex reasoning effort | +| `PROVIDER_NAME` | `poe` | Provider identifier in configs | ### Frontier Models @@ -2468,11 +2563,7 @@ const CODEX_MODELS = [ ### Kimi Models ```typescript -const KIMI_MODELS = [ - "novitaai/kimi-k2.5", - "novitaai/kimi-k2-thinking", - "novitaai/kimi-k2.5-fw" -]; +const KIMI_MODELS = ["novitaai/kimi-k2.5", "novitaai/kimi-k2-thinking", "novitaai/kimi-k2.5-fw"]; ``` ### Model Namespace Stripping @@ -2480,27 +2571,27 @@ const KIMI_MODELS = [ Model IDs are namespaced (e.g., `anthropic/claude-sonnet-4.6`). The `stripModelNamespace()` function removes the provider prefix: ```typescript -stripModelNamespace("anthropic/claude-sonnet-4.6") // → "claude-sonnet-4.6" -stripModelNamespace("openai/gpt-5.2") // → "gpt-5.2" +stripModelNamespace("anthropic/claude-sonnet-4.6"); // → "claude-sonnet-4.6" +stripModelNamespace("openai/gpt-5.2"); // → "gpt-5.2" ``` --- ## Environment Variables -| Variable | Default | Description | -|----------|---------|-------------| -| `POE_API_KEY` | — | Poe API key. Highest priority credential source. | -| `POE_DEFAULT_AGENT` | — | Default agent (or `agent:model`) used when commands omit agent selection. | -| `POE_BASE_URL` | `https://api.poe.com/v1` | Poe API base URL. Used for provider configuration. | -| `POE_API_BASE_URL` | `https://api.poe.com/v1` | Poe API base URL. Used by SDK generate functions. | -| `POE_TEXT_MODEL` | `anthropic/claude-sonnet-4.6` | Override default text generation model. | -| `POE_IMAGE_MODEL` | `google/nano-banana-pro` | Override default image generation model. | -| `POE_VIDEO_MODEL` | `google/veo-3.1` | Override default video generation model. | -| `POE_AUDIO_MODEL` | `elevenlabs/elevenlabs-v3` | Override default audio generation model. | -| `POE_CODE_STDERR_LOGS` | — | Set to `1` or `true` to enable stderr logging for bootstrap errors. | -| `POE_SNAPSHOT_MODE` | `playback` | Testing: `record` to record LLM responses, `playback` to replay. | -| `POE_SNAPSHOT_MISS` | `error` | Testing: behavior on missing snapshot: `error`, `warn`, `passthrough`. | +| Variable | Default | Description | +| ---------------------- | ----------------------------- | ------------------------------------------------------------------------- | +| `POE_API_KEY` | — | Poe API key. Highest priority credential source. | +| `POE_DEFAULT_AGENT` | — | Default agent (or `agent:model`) used when commands omit agent selection. | +| `POE_BASE_URL` | `https://api.poe.com/v1` | Poe API base URL. Used for provider configuration. | +| `POE_API_BASE_URL` | `https://api.poe.com/v1` | Poe API base URL. Used by SDK generate functions. | +| `POE_TEXT_MODEL` | `anthropic/claude-sonnet-4.6` | Override default text generation model. | +| `POE_IMAGE_MODEL` | `google/nano-banana-pro` | Override default image generation model. | +| `POE_VIDEO_MODEL` | `google/veo-3.1` | Override default video generation model. | +| `POE_AUDIO_MODEL` | `elevenlabs/elevenlabs-v3` | Override default audio generation model. | +| `POE_CODE_STDERR_LOGS` | — | Set to `1` or `true` to enable stderr logging for bootstrap errors. | +| `POE_SNAPSHOT_MODE` | `playback` | Testing: `record` to record LLM responses, `playback` to replay. | +| `POE_SNAPSHOT_MISS` | `error` | Testing: behavior on missing snapshot: `error`, `warn`, `passthrough`. | --- @@ -2515,6 +2606,7 @@ The `research` command is a specialized spawn that defaults to `read` mode. Key 5. **Agent is specified via `--agent`** option (not positional argument) **Workflow for GitHub research:** + 1. Clones the repository to a temporary directory 2. Spawns the agent with the cloned repo as working directory 3. Unless `--keep` is set, removes the cloned repo after completion @@ -2527,10 +2619,10 @@ Skills are agent-specific prompt templates/directories that extend agent capabil ### Scope -| Scope | Location | Flag | -|-------|----------|------| +| Scope | Location | Flag | +| ------ | ----------------------------------------------- | ---------- | | Global | `~/.poe-code//skills/` (varies by agent) | `--global` | -| Local | `.//` (project directory) | `--local` | +| Local | `.//` (project directory) | `--local` | ### Workflow @@ -2551,13 +2643,13 @@ poe-code skill unconfigure claude-code --global --force `poe-code` provides convenience binaries for common agent patterns: -| Binary | Purpose | -|--------|---------| -| `poe-code` | Main CLI | -| `poe-code-configure` | Alias for `poe-code configure` | -| `poe-claude` | Convenience wrapper for Claude Code | -| `poe-codex` | Convenience wrapper for Codex | -| `poe-opencode` | Convenience wrapper for OpenCode | +| Binary | Purpose | +| -------------------- | ----------------------------------- | +| `poe-code` | Main CLI | +| `poe-code-configure` | Alias for `poe-code configure` | +| `poe-claude` | Convenience wrapper for Claude Code | +| `poe-codex` | Convenience wrapper for Codex | +| `poe-opencode` | Convenience wrapper for OpenCode | --- @@ -2588,6 +2680,7 @@ Content-Type: application/json **Text responses:** Extracts `choices[0].message.content` **Media responses:** Tries multiple extraction strategies in order: + 1. Parse content as JSON with `{ url, mimeType, data }` fields 2. Treat content as a raw URL 3. Extract URL from markdown format `![alt](url)` @@ -2595,6 +2688,7 @@ Content-Type: application/json ### Error Handling API errors throw `ApiError` with: + - `httpStatus`: HTTP status code - `endpoint`: The API endpoint that failed - `context.responseBody`: Error response body (if available) @@ -2605,12 +2699,12 @@ API errors throw `ApiError` with: ### Error Types -| Error | Description | -|-------|-------------| -| `ApiError` | HTTP error from the Poe API. Contains `httpStatus`, `endpoint`, and optional `context`. | +| Error | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------- | +| `ApiError` | HTTP error from the Poe API. Contains `httpStatus`, `endpoint`, and optional `context`. | | Credential errors | Thrown when no API key is found. Message: `"No API key found. Set POE_API_KEY or run 'poe-code login'."` | -| Spawn errors | Non-zero exit codes from agent processes. | -| Validation errors | Invalid MCP config, missing required arguments, etc. | +| Spawn errors | Non-zero exit codes from agent processes. | +| Validation errors | Invalid MCP config, missing required arguments, etc. | ### Exit Codes @@ -2663,7 +2757,9 @@ poe-code/ │ │ ├── claude-code.ts # Claude Code provider │ │ ├── codex.ts # Codex provider │ │ ├── opencode.ts # OpenCode provider -│ │ └── kimi.ts # Kimi provider +│ │ ├── cursor.ts # Cursor provider +│ │ ├── kimi.ts # Kimi provider +│ │ └── goose.ts # Goose provider │ ├── sdk/ │ │ ├── spawn.ts # SDK spawn (streaming + pretty) │ │ ├── spawn-core.ts # Core spawn logic @@ -2723,47 +2819,46 @@ poe-code/ ### CLI Commands Summary -| Command | Subcommands | Description | -|---------|-------------|-------------| -| `configure [agent]` | — | Configure agent for the selected provider API | -| `unconfigure ` | — | Remove Poe configuration | -| `login` | — | Store API key | -| `logout` | — | Remove all config + credentials | -| `auth` | `status`, `api-key`, `whoami`, `login`, `logout` | Poe account authentication commands | -| `provider` | `list`, `login`, `logout` | Provider authentication management | -| `approvals` | `list`, `show`, `run` | Toolcraft human-in-loop approval queue | -| `spawn [prompt]` | — | Run agent with prompt | -| `code-review` | `install`, `profiles`, `ingest`, `run`, `drafts`, `commit`, `agent-mcp` | Agent-assisted GitHub pull request reviews | -| `research [prompt]` | — | Research codebase (read mode) | -| `wrap ` | — | One-off isolated session | -| `test [agent]` | — | Health check | -| `install [agent]` | — | Install agent binary | -| `generate` | `text`, `image`, `video`, `audio` | Generate content | -| `usage` | `balance`, `list` | Check usage/billing | -| `models` | — | List available models | -| `mcp` | `serve`, `configure`, `unconfigure` | MCP server management | -| `skill` | `configure`, `unconfigure` | Agent skill management | -| `pipeline` | `run`, `init`, `validate`, `plan-path`, `install` | Pipeline plan generation, validation, and execution | -| `memory` | `init`, `ls`, `show`, `search`, `status`, `clear` | Repo-scoped persistent memory operations | - +| Command | Subcommands | Description | +| ------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------- | +| `configure [agent]` | — | Configure agent for the selected provider API | +| `unconfigure ` | — | Remove Poe configuration | +| `login` | — | Store API key | +| `logout` | — | Remove all config + credentials | +| `auth` | `status`, `api-key`, `whoami`, `login`, `logout` | Poe account authentication commands | +| `provider` | `list`, `login`, `logout` | Provider authentication management | +| `approvals` | `list`, `show`, `run` | Toolcraft human-in-loop approval queue | +| `spawn [prompt]` | — | Run agent with prompt | +| `code-review` | `install`, `profiles`, `ingest`, `run`, `drafts`, `commit`, `agent-mcp` | Agent-assisted GitHub pull request reviews | +| `research [prompt]` | — | Research codebase (read mode) | +| `wrap ` | — | One-off isolated session | +| `test [agent]` | — | Health check | +| `install [agent]` | — | Install agent binary | +| `generate` | `text`, `image`, `video`, `audio` | Generate content | +| `usage` | `balance`, `list` | Check usage/billing | +| `models` | — | List available models | +| `mcp` | `serve`, `configure`, `unconfigure` | MCP server management | +| `skill` | `configure`, `unconfigure` | Agent skill management | +| `pipeline` | `run`, `init`, `validate`, `plan-path`, `install` | Pipeline plan generation, validation, and execution | +| `memory` | `init`, `ls`, `show`, `search`, `status`, `clear` | Repo-scoped persistent memory operations | ### SDK Exports Summary ```typescript // Functions -export { spawn } from "poe-code"; // spawn() and spawn.pretty() -export { generate } from "poe-code"; // Text generation -export { generateImage } from "poe-code"; // Image generation -export { generateVideo } from "poe-code"; // Video generation -export { generateAudio } from "poe-code"; // Audio generation -export { getPoeApiKey } from "poe-code"; // API key resolution +export { spawn } from "poe-code"; // spawn() and spawn.pretty() +export { generate } from "poe-code"; // Text generation +export { generateImage } from "poe-code"; // Image generation +export { generateVideo } from "poe-code"; // Video generation +export { generateAudio } from "poe-code"; // Audio generation +export { getPoeApiKey } from "poe-code"; // API key resolution export { getPoeAuthIdentity } from "poe-code"; // Poe account identity export { agent, openaiChatCompletionsPlugin, openaiResponsesPlugin, systemPromptPlugin -} from "poe-code/agent"; // Composable agent runtime +} from "poe-code/agent"; // Composable agent runtime // Types export type { SpawnOptions } from "poe-code"; @@ -2787,9 +2882,10 @@ export { main, isCliInvocation } from "poe-code"; ### Supported Agents Summary -| Agent | ID | Aliases | Binary | Config Format | Stdin | MCP Spawn | Interactive | Resume | -|-------|-----|---------|--------|--------------|-------|-----------|-------------|--------| -| Claude Code | `claude-code` | `claude` | `claude` | JSON | Yes | Yes | Yes | Yes | -| Codex | `codex` | — | `codex` | TOML | Yes | Yes | Yes | Yes | -| OpenCode | `opencode` | — | `opencode` | JSON | No | No | Yes | Yes | -| Kimi | `kimi` | `kimi-cli` | `kimi` | TOML | Yes | Yes | Yes | Yes | +| Agent | ID | Aliases | Binary | Config Format | Stdin | MCP Spawn | Interactive | Resume | +| ----------- | ------------- | -------------- | -------------- | ------------- | ----- | --------- | ----------- | ------ | +| Claude Code | `claude-code` | `claude` | `claude` | JSON | Yes | Yes | Yes | Yes | +| Codex | `codex` | — | `codex` | TOML | Yes | Yes | Yes | Yes | +| OpenCode | `opencode` | — | `opencode` | JSON | No | No | Yes | Yes | +| Cursor | `cursor` | `cursor-agent` | `cursor-agent` | JSON | No | Yes | Yes | Yes | +| Kimi | `kimi` | `kimi-cli` | `kimi` | TOML | Yes | Yes | Yes | Yes | diff --git a/docs/development/NPM_PUBLISHING.md b/docs/development/NPM_PUBLISHING.md index 43093d46b2..62118b8a76 100644 --- a/docs/development/NPM_PUBLISHING.md +++ b/docs/development/NPM_PUBLISHING.md @@ -50,10 +50,10 @@ For packages that must release in lockstep, use the shared composite action afte uses: ./.github/actions/prepare-lockstep-release with: version: ${{ steps.version.outputs.version }} - packages: '["packages/toolcraft", "packages/toolcraft-openapi"]' + packages: '["packages/toolcraft-schema", "packages/toolcraft", "packages/toolcraft-openapi"]' ``` -The action rewrites every listed `package.json` to the same version and rewrites intra-group `dependencies`, `peerDependencies`, and `optionalDependencies` to that exact version. The group must contain at least two public npm package directories, and each prepared package should be published by the workflow. `npm run lint:packages` enforces this with `lockstep-release-group-valid`. +The action rewrites every listed `package.json` to the same version and rewrites intra-group `dependencies`, `peerDependencies`, and `optionalDependencies` to that exact version. The group must contain at least two public npm package directories, and each prepared package should be published by the workflow. The Toolcraft release group publishes `toolcraft-schema`, `toolcraft`, and `toolcraft-openapi`; `toolcraft-design` is private and is bundled through the public `toolcraft/design` export, so the workflow builds it but does not prepare or publish it. `npm run lint:packages` enforces public lockstep groups with `lockstep-release-group-valid`. If a published package declares `bin`, add the shared executable-bit helper to `prepack` so `tsc`-emitted binaries do not ship as mode `0644`: diff --git a/packages/agent-spawn/README.md b/packages/agent-spawn/README.md index b36cfa8527..6854b7c724 100644 --- a/packages/agent-spawn/README.md +++ b/packages/agent-spawn/README.md @@ -1,7 +1,5 @@ # @poe-code/agent-spawn -Cursor spawns use the authenticated `cursor-agent` installation and the user's Cursor account. No environment variables are injected. Supported modes map to Cursor's forced sandbox-disabled, forced edit, and plan/read-only modes. - `@poe-code/agent-spawn` contains the low-level spawn adapters used by the CLI and SDK to run supported coding agents, stream ACP-like events, pass model and permission-mode flags, inject MCP servers at spawn time, and resume prior sessions when an agent returns a thread/session ID. ## Usage @@ -24,6 +22,10 @@ console.log(result.exitCode, result.stdout); console.log(listMcpSupportedAgents()); ``` +## Agent notes + +Cursor spawns use the authenticated `cursor-agent` installation and the user's Cursor account. No Poe environment variables are injected. Cursor models strip provider prefixes and translate Claude model dots to hyphens, modes map to forced sandbox-disabled (`yolo`), forced edit (`edit`), and plan/read-only (`read`), and resume passes `--resume `. + ## Spawn modes | Mode | Purpose | @@ -36,7 +38,7 @@ Mode-specific args and env vars are declared in each agent config. Goose uses `G ## MCP at spawn time -Pass `mcpServers` as a map of server names to `{ command, args?, env?, timeout? }`. The package serializes that declarative config into agent-specific CLI arguments, environment variables, or a temporary workspace config file. `listMcpSupportedAgents()` reports the current agents with spawn-time MCP support. +Pass `mcpServers` as a map of server names to `{ command, args?, env?, timeout? }`. The package serializes that declarative config into agent-specific CLI arguments, environment variables, or a temporary workspace config file. Cursor uses a temporary `.cursor/mcp.json` in the spawn working directory; existing JSON object content is deep-merged for the child process and restored afterward. `listMcpSupportedAgents()` reports the current agents with spawn-time MCP support. The same serialization is used for interactive TUI spawns. Agents that express MCP servers through environment-backed config, such as OpenCode's `OPENCODE_CONFIG_CONTENT`, receive those values in diff --git a/packages/terminal-pilot/README.md b/packages/terminal-pilot/README.md index 3211b92b80..027d7dcd0e 100644 --- a/packages/terminal-pilot/README.md +++ b/packages/terminal-pilot/README.md @@ -26,7 +26,7 @@ npx terminal-pilot [options] ### Skill installation -The CLI can install a Claude Code skill that teaches the agent how to use terminal-pilot's MCP tools. Supported agents: `claude-code`, `codex`, `opencode`. +The CLI can install a Claude Code skill that teaches the agent how to use terminal-pilot's MCP tools. Supported agents: `claude-code`, `codex`, `cursor`, `opencode`. **Install the skill (local project, default):** diff --git a/packages/toolcraft-design/README.md b/packages/toolcraft-design/README.md index d3506e8e94..85ab6f4b4c 100644 --- a/packages/toolcraft-design/README.md +++ b/packages/toolcraft-design/README.md @@ -1,20 +1,20 @@ # toolcraft-design -Shared terminal design system for Toolcraft applications. It provides design tokens, ANSI-aware text and layout components, interactive prompts, dashboards, explorers, terminal Markdown rendering, and deterministic static renderers from one package. +Private workspace package for the Toolcraft terminal design system. It provides design tokens, ANSI-aware text and layout components, interactive prompts, dashboards, explorers, terminal Markdown rendering, and deterministic static renderers from one package. ## Install +`toolcraft-design` is private and is bundled through the public `toolcraft/design` export. Consumers should install `toolcraft` and import the design API from that subpath: + ```sh -npm install toolcraft-design +npm install toolcraft ``` -Import from the package root: - ```ts -import { configureTheme, promptText, renderMarkdown, renderTable, text } from "toolcraft-design"; +import { configureTheme, promptText, renderMarkdown, renderTable, text } from "toolcraft/design"; ``` -The package does not expose public subpath imports. +Inside this monorepo, workspace packages may still import `toolcraft-design` directly when they need the source package. ## Public API @@ -95,7 +95,7 @@ The package does not expose public subpath imports. The default configuration is `{ brand: "purple", label: "Poe" }`. Configure the package before producing design-system output: ```ts -import { configureTheme, getThemeConfig, resetTheme } from "toolcraft-design"; +import { configureTheme, getThemeConfig, resetTheme } from "toolcraft/design"; configureTheme({ brand: "blue", label: "Toolcraft" }); @@ -116,7 +116,7 @@ The built-in brands are: Register another brand by adding a `Brand` to the exported `brands` registry before selecting it: ```ts -import { brands, configureTheme, type Brand } from "toolcraft-design"; +import { brands, configureTheme, type Brand } from "toolcraft/design"; const orange: Brand = { name: "orange", diff --git a/packages/toolcraft/README.md b/packages/toolcraft/README.md index f5c70712c7..b2b4210aff 100644 --- a/packages/toolcraft/README.md +++ b/packages/toolcraft/README.md @@ -85,7 +85,10 @@ export const root = defineGroup({ import { runCLI } from "toolcraft/cli"; import { root } from "./root.js"; -await runCLI(root, { version: "0.1.0" }); +await runCLI(root, { + version: "0.1.0", + controls: { yes: true, output: true, debug: true, verbose: true } +}); ``` ```sh @@ -94,6 +97,8 @@ mytool greet --name world --loud mytool greet --help ``` +Generated global CLI controls are opt-in. Pass `controls` to expose `--yes`, `--output`, `--debug`, or `--verbose`; otherwise toolcraft only adds options required by the root, such as `--version` or `--preset` when enabled. Root groups may also use an unnamed default command (`name: ""`) alongside named siblings; help shows its positional arguments without exposing the internal default-command name. + ## Project layout A typical toolcraft project: @@ -147,7 +152,10 @@ const mode = process.argv[2]; if (mode === "mcp") { await runMCP(root, { name: "mytool", version: "0.1.0" }); } else { - await runCLI(root, { version: "0.1.0" }); + await runCLI(root, { + version: "0.1.0", + controls: { yes: true, output: true, debug: true, verbose: true } + }); } ``` @@ -350,20 +358,20 @@ const humanInLoop = { taskList: { dir: ".toolcraft/approvals.yaml", format: "yaml-file" as const } }; -await runCLI(root, { humanInLoop }); -createMCPServer(root, { name: "mytool", version: "0.1.0", humanInLoop }); -const sdk = createSDK(root, { humanInLoop }); +await runCLI(root, { humanInLoop, approvals: true }); +createMCPServer(root, { name: "mytool", version: "0.1.0", humanInLoop, approvals: true }); +const sdk = createSDK(root, { humanInLoop, approvals: true }); ``` If `provider` is omitted, toolcraft picks a default lazily on first use: `osascriptProvider` on macOS; otherwise a stub that throws `UserError("no human-in-loop provider configured for this platform")`. -A built-in `approvals` group is auto-merged into every root: +A built-in `approvals` group is available when enabled with `approvals: true`: - `approvals list` — list pending tasks (CLI, MCP, SDK). - `approvals show --approval-id ` — show one task. - `approvals run --approval-id ` — execute one queued task. CLI-only; used by the detached runner. -Pass `approvals: false` to `runCLI`, `createMCPServer`/`runMCP`, or `createSDK` to omit these approval-management commands while keeping `humanInLoop` execution behavior available for commands that request approval. +Approval-management commands are opt-in for `runCLI`, `createMCPServer`/`runMCP`, and `createSDK`. Leave `approvals` unset or set it to `false` to omit the built-in commands while keeping `humanInLoop` execution behavior available for commands that request approval. The name `approvals` is reserved when the built-in group is enabled. Defining your own `approvals` group fails at startup. @@ -473,7 +481,8 @@ If you have an existing MCP server you want to keep running, use the MCP proxy: - `presets?: boolean` — enables `--preset ` for loading parameter defaults from JSON files. - `apiVersion?: string` — for `requires.apiVersion`. - `humanInLoop?: HumanInLoopRuntimeOptions` -- `approvals?: boolean` — set to `false` to omit the built-in approval-management commands. +- `approvals?: boolean` — set to `true` to add built-in approval-management commands. +- `controls?: { yes?: boolean; output?: boolean; debug?: boolean; verbose?: boolean }` — opt in to generated global CLI controls. - `errorReports?: boolean | { dir?: string }` - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`). @@ -528,3 +537,4 @@ Subpath imports: - `toolcraft/mcp` — `runMCP`, `createMCPServer` - `toolcraft/human-in-loop` — provider helpers - `toolcraft/mcp-proxy` — proxy internals +- `toolcraft/design` — bundled terminal design-system exports