typeclaw 0.48.13 → 0.49.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +5 -5
- package/scripts/dump-system-prompt.ts +52 -110
- package/src/agent/index.ts +144 -72
- package/src/agent/live-sessions.ts +2 -2
- package/src/agent/live-subagents.ts +1 -0
- package/src/agent/plugin-tools.ts +53 -11
- package/src/agent/prompt-cache-key.ts +42 -0
- package/src/agent/provider-error.ts +179 -10
- package/src/agent/restart-handoff/index.ts +7 -14
- package/src/agent/reviewer-activity.ts +68 -0
- package/src/agent/session-origin.ts +33 -0
- package/src/agent/subagents.ts +13 -1
- package/src/agent/system-prompt.ts +68 -202
- package/src/agent/todo/continuation-policy.ts +12 -4
- package/src/agent/tool-file-safety.ts +113 -14
- package/src/agent/tool-not-found-nudge.ts +1 -1
- package/src/agent/tools/channel-history-render.ts +2 -1
- package/src/agent/tools/channel-reply.ts +23 -5
- package/src/agent/tools/channel-send.ts +49 -7
- package/src/agent/tools/curl-impersonate.ts +11 -2
- package/src/agent/tools/post-github-review.ts +77 -15
- package/src/agent/tools/skip-response.ts +2 -2
- package/src/agent/tools/spawn-subagent.ts +163 -12
- package/src/agent/tools/subagent-output.ts +8 -0
- package/src/bundled-plugins/backup/README.md +10 -9
- package/src/bundled-plugins/backup/runner.ts +140 -58
- package/src/bundled-plugins/backup/subagents.ts +58 -26
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +34 -2
- package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
- package/src/bundled-plugins/github-cli-auth/index.ts +83 -11
- package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
- package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
- package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
- package/src/bundled-plugins/operator/operator.ts +15 -4
- package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
- package/src/bundled-plugins/security/index.ts +50 -2
- package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
- package/src/channels/adapters/discord-bot-reactions.ts +18 -0
- package/src/channels/adapters/discord-bot.ts +122 -67
- package/src/channels/adapters/discord-reactions.ts +18 -0
- package/src/channels/adapters/discord.ts +114 -8
- package/src/channels/adapters/github/inbound.ts +103 -8
- package/src/channels/adapters/github/index.ts +251 -19
- package/src/channels/adapters/github/last-alive.ts +27 -0
- package/src/channels/adapters/github/outbound.ts +54 -18
- package/src/channels/adapters/github/pending-review-store.ts +141 -0
- package/src/channels/adapters/github/permission-guidance.ts +1 -0
- package/src/channels/adapters/github/reactions.ts +100 -0
- package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
- package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
- package/src/channels/adapters/github/recovery.ts +106 -0
- package/src/channels/adapters/github/review-check.ts +510 -0
- package/src/channels/adapters/github/review-submitter.ts +34 -2
- package/src/channels/adapters/instagram.ts +32 -14
- package/src/channels/adapters/kakaotalk.ts +22 -7
- package/src/channels/adapters/line.ts +18 -3
- package/src/channels/adapters/outbound-account.ts +20 -0
- package/src/channels/adapters/own-reactions.ts +66 -0
- package/src/channels/adapters/recovery-correlation.ts +214 -0
- package/src/channels/adapters/slack-bot-classify.ts +18 -11
- package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
- package/src/channels/adapters/slack-bot-reactions.ts +18 -0
- package/src/channels/adapters/slack-bot.ts +125 -57
- package/src/channels/adapters/slack-classify.ts +25 -4
- package/src/channels/adapters/slack-inbound-revision.ts +96 -0
- package/src/channels/adapters/slack-reactions.ts +18 -0
- package/src/channels/adapters/slack-thread-ts.ts +6 -0
- package/src/channels/adapters/slack.ts +48 -3
- package/src/channels/adapters/teams.ts +14 -4
- package/src/channels/adapters/telegram-bot.ts +56 -10
- package/src/channels/adapters/webex-bot.ts +12 -2
- package/src/channels/adapters/webex.ts +12 -2
- package/src/channels/background-handoff.ts +434 -0
- package/src/channels/background-obligations.ts +893 -0
- package/src/channels/continuity-types.ts +271 -0
- package/src/channels/github-review-check.ts +598 -0
- package/src/channels/github-review-turn-ledger.ts +102 -28
- package/src/channels/github-review-verdict-coordinator.ts +72 -12
- package/src/channels/github-token-bridge.ts +11 -5
- package/src/channels/inbound-journal.ts +1738 -0
- package/src/channels/index.ts +6 -1
- package/src/channels/manager.ts +17 -7
- package/src/channels/recovery-dispatcher.ts +264 -0
- package/src/channels/recovery-notice.ts +94 -0
- package/src/channels/recovery-outbox.ts +459 -0
- package/src/channels/router.ts +2539 -615
- package/src/channels/schema.ts +8 -1
- package/src/channels/subagent-completion-bridge.ts +17 -14
- package/src/channels/types.ts +121 -16
- package/src/channels/waiting-reactions.ts +664 -0
- package/src/cli/compose.ts +7 -4
- package/src/cli/hostd.ts +49 -3
- package/src/cli/inspect.ts +11 -14
- package/src/coding-agent/broker-body.ts +38 -0
- package/src/coding-agent/broker.ts +290 -0
- package/src/coding-agent/claude.ts +95 -0
- package/src/coding-agent/codex.ts +104 -0
- package/src/coding-agent/index.ts +506 -0
- package/src/coding-agent/omo-state.ts +69 -0
- package/src/coding-agent/omo-stream.ts +98 -0
- package/src/coding-agent/omo.ts +192 -0
- package/src/coding-agent/runner.ts +263 -0
- package/src/coding-agent/tool.ts +62 -0
- package/src/coding-agent/worktree.ts +355 -0
- package/src/compose/restart.ts +10 -3
- package/src/compose/start.ts +20 -3
- package/src/config/config.ts +10 -3
- package/src/config/providers.ts +12 -9
- package/src/container/exit-reason.ts +44 -0
- package/src/container/index.ts +5 -0
- package/src/container/log-archive.ts +51 -13
- package/src/container/memory-limit.ts +1 -1
- package/src/container/memory-oversubscription.ts +36 -6
- package/src/container/oom-events.ts +86 -0
- package/src/container/restart.ts +2 -0
- package/src/container/shared.ts +8 -1
- package/src/container/start.ts +25 -13
- package/src/container/stop.ts +6 -2
- package/src/container/tool-oom-priority.ts +32 -0
- package/src/cron/consumer.ts +10 -4
- package/src/cron/reloadable.ts +23 -2
- package/src/doctor/checks.ts +14 -2
- package/src/hostd/daemon.ts +20 -10
- package/src/hostd/spawn.ts +106 -5
- package/src/hostd/version.ts +20 -0
- package/src/hostd/watchdog.ts +241 -0
- package/src/init/dockerfile.ts +57 -592
- package/src/init/index.ts +2 -3
- package/src/mcp/client.ts +3 -1
- package/src/operations/classify-tool-outcome.ts +45 -1
- package/src/operations/incidents.ts +10 -5
- package/src/plugin/core-tool-names.ts +1 -1
- package/src/plugin/define.ts +1 -0
- package/src/plugin/index.ts +1 -0
- package/src/plugin/types.ts +6 -1
- package/src/run/background-handoff-boot.ts +86 -0
- package/src/run/index.ts +83 -83
- package/src/run/resource-sample.ts +19 -0
- package/src/sandbox/build.ts +4 -0
- package/src/sandbox/coding-agent.ts +214 -0
- package/src/sandbox/policy.ts +1 -0
- package/src/sandbox/runtime-private.ts +4 -1
- package/src/secrets/coding-agent-auth.ts +97 -0
- package/src/secrets/index.ts +0 -16
- package/src/server/command-runner.ts +6 -2
- package/src/server/index.ts +101 -40
- package/src/skills/typeclaw-channel-github/SKILL.md +7 -5
- package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
- package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
- package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
- package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
- package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
- package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
- package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
- package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
- package/src/skills/typeclaw-config/SKILL.md +21 -21
- package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
- package/src/skills/typeclaw-cron/SKILL.md +1 -1
- package/src/skills/typeclaw-github-contributing/SKILL.md +2 -2
- package/src/skills/typeclaw-memory/SKILL.md +3 -3
- package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
- package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
- package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
- package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
- package/src/skills/typeclaw-plugins/SKILL.md +15 -15
- package/src/skills/typeclaw-skills/SKILL.md +19 -2
- package/src/skills/typeclaw-troubleshooting/SKILL.md +15 -2
- package/typeclaw.schema.json +12 -1
- package/src/secrets/claude-credentials-json.ts +0 -129
- package/src/secrets/codex-auth-json.ts +0 -102
- package/src/secrets/export-claude-credentials-file.ts +0 -270
- package/src/secrets/export-codex-auth-file.ts +0 -250
- package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
- package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
- package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
- package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
|
@@ -22,7 +22,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
|
|
|
22
22
|
- `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
|
|
23
23
|
- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, LINE, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
|
|
24
24
|
- `branding` — whether your system prompt discloses that you run on TypeClaw. Default `true`: the prompt says you run "inside TypeClaw" and stamps a `## Runtime` TypeClaw-version block. Set `false` and both are stripped — the prompt opens generically and the runtime-version block is omitted (also on the subagent prompt path). Read fresh per session, so it applies on the next `reload`. The `typeclaw.json` filename and the `typeclaw-render-pdf` / `typeclaw-troubleshooting` skill names stay regardless — they are tokens you need to operate, not disclosure. **Live-reloadable.**
|
|
25
|
-
- `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, and `
|
|
25
|
+
- `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli`, `omoCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, and `omoCli` are boolean-only). Most toggles install apt packages with BuildKit cache mounts; `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are exceptions — `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's official `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package, and `omoCli` downloads digest-verified OmO Native 5.1.19 assets. (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
|
|
26
26
|
- `git.ignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. Lives under the `git` namespace. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
|
|
27
27
|
- `portForward` — allow/deny policy for the auto port-forwarder (the host-stage `_hostd` daemon's portbroker). When the agent runs a server inside the container that LISTENs on a TCP port, the broker proxies it to the same port number on `127.0.0.1` of the host so the user can hit it directly. `portForward` decides which ports are allowed through. **Restart-required** — the broker captures the policy at register time on `typeclaw start`.
|
|
28
28
|
- `network` — the separate container-stage egress firewall. `blockInternal` defaults on; `allow` accepts explicit IPv4 addresses/CIDRs for all-protocol firewall exceptions. It does not bypass `web_fetch` or URL-backed `look_at` SSRF validation. **Restart-required.**
|
|
@@ -43,21 +43,21 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
|
|
|
43
43
|
|
|
44
44
|
`typeclaw.json` is a single JSON object with these fields:
|
|
45
45
|
|
|
46
|
-
| Field | Required | Type | Notes
|
|
47
|
-
| -------------------------------- | -------- | ---------------- |
|
|
48
|
-
| `$schema` | no | string | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.
|
|
49
|
-
| `port` | no | integer | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**
|
|
50
|
-
| `model` | no | string | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**
|
|
51
|
-
| `models.<profile>.thinkingLevel` | no | string | Per-profile reasoning effort (NOT a top-level field): `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`. Lives in a profile object `{ "model": "<ref>", "thinkingLevel": … }`. Resolves as profile's own → `default` profile's → SDK default (`medium`). Set with `typeclaw model set <profile> <ref> --thinking <level>` or `typeclaw model thinking <level>` (for `default`). **Live-reloadable.**
|
|
52
|
-
| `mounts` | no | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**
|
|
53
|
-
| `plugins` | no | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.
|
|
54
|
-
| `alias` | no | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.**
|
|
55
|
-
| `channels` | no | object | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below.
|
|
56
|
-
| `portForward` | no | object | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.
|
|
57
|
-
| `network` | no | object | Container-stage egress firewall: `{ blockInternal, autoAllowResolvers, allow }`. Defaults to internal blocking on, resolver carve-outs on, and no IPv4 exceptions. `allow` is independent from safe-HTTP SSRF exceptions. **Restart-required.** See **Network and model HTTP internal destinations** below.
|
|
58
|
-
| `docker` | no | object | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, xvfb: true, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
|
|
59
|
-
| `git` | no | object | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.
|
|
60
|
-
| `branding` | no | boolean | Whether the system prompt discloses that you run on TypeClaw. Defaults to `true`. Set `false` to strip every TypeClaw clue from the prompt: the base prompt opens generically (no "inside TypeClaw") and the `## Runtime` version block is omitted, on both the main and subagent prompt paths. Read fresh per session. Functional identifiers (`typeclaw.json`, the `typeclaw-render-pdf` / `typeclaw-troubleshooting` skill names) are unaffected. **Live-reloadable.**
|
|
46
|
+
| Field | Required | Type | Notes |
|
|
47
|
+
| -------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `$schema` | no | string | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it. |
|
|
49
|
+
| `port` | no | integer | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.** |
|
|
50
|
+
| `model` | no | string | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.** |
|
|
51
|
+
| `models.<profile>.thinkingLevel` | no | string | Per-profile reasoning effort (NOT a top-level field): `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`. Lives in a profile object `{ "model": "<ref>", "thinkingLevel": … }`. Resolves as profile's own → `default` profile's → SDK default (`medium`). Set with `typeclaw model set <profile> <ref> --thinking <level>` or `typeclaw model thinking <level>` (for `default`). **Live-reloadable.** |
|
|
52
|
+
| `mounts` | no | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.** |
|
|
53
|
+
| `plugins` | no | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**. |
|
|
54
|
+
| `alias` | no | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.** |
|
|
55
|
+
| `channels` | no | object | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below. |
|
|
56
|
+
| `portForward` | no | object | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below. |
|
|
57
|
+
| `network` | no | object | Container-stage egress firewall: `{ blockInternal, autoAllowResolvers, allow }`. Defaults to internal blocking on, resolver carve-outs on, and no IPv4 exceptions. `allow` is independent from safe-HTTP SSRF exceptions. **Restart-required.** See **Network and model HTTP internal destinations** below. |
|
|
58
|
+
| `docker` | no | object | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, `omoCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, xvfb: true, claudeCode: false, codexCli: false, omoCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
|
|
59
|
+
| `git` | no | object | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below. |
|
|
60
|
+
| `branding` | no | boolean | Whether the system prompt discloses that you run on TypeClaw. Defaults to `true`. Set `false` to strip every TypeClaw clue from the prompt: the base prompt opens generically (no "inside TypeClaw") and the `## Runtime` version block is omitted, on both the main and subagent prompt paths. Read fresh per session. Functional identifiers (`typeclaw.json`, the `typeclaw-render-pdf` / `typeclaw-troubleshooting` skill names) are unaffected. **Live-reloadable.** |
|
|
61
61
|
|
|
62
62
|
> **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
|
|
63
63
|
|
|
@@ -72,7 +72,7 @@ A scaffolded `typeclaw.json` looks like:
|
|
|
72
72
|
}
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
The runtime fills in defaults for any omitted field: `port` → `8973`, `mounts` → `[]` (no host paths exposed), `plugins` → `[]`, `channels` → `{}` (no adapters configured), `portForward` → `{ "allow": "*" }` (forward every container LISTEN port), `network` → `{ "blockInternal": true, "autoAllowResolvers": true, "allow": [] }`, `docker` → `{ "file": { "ffmpeg": false, "gh": true, "python": true, "tmux": true, "cjkFonts": "auto", "cloudflared": false, "xvfb": true, "claudeCode": false, "codexCli": false, "append": [] } }` (tmux/gh/python/xvfb pre-installed; cjkFonts auto-detected from host locale; ffmpeg, cloudflared, claudeCode, and
|
|
75
|
+
The runtime fills in defaults for any omitted field: `port` → `8973`, `mounts` → `[]` (no host paths exposed), `plugins` → `[]`, `channels` → `{}` (no adapters configured), `portForward` → `{ "allow": "*" }` (forward every container LISTEN port), `network` → `{ "blockInternal": true, "autoAllowResolvers": true, "allow": [] }`, `docker` → `{ "file": { "ffmpeg": false, "gh": true, "python": true, "tmux": true, "cjkFonts": "auto", "cloudflared": false, "xvfb": true, "claudeCode": false, "codexCli": false, "omoCli": false, "append": [] } }` (tmux/gh/python/xvfb pre-installed; cjkFonts auto-detected from host locale; ffmpeg, cloudflared, claudeCode, codexCli, and omoCli off; no custom build steps), `git` → `{ "ignore": { "append": [] } }` (no custom ignore patterns). `typeclaw init` deliberately omits any field whose default is owned elsewhere — `mounts`, `portForward`, `network`, `docker`, and `git` default via `configSchema`, and the bundled memory plugin owns its own `memory` defaults — so the scaffolded file stays minimal and the user sees only fields they actually need to think about. Add a `memory` block (a **plugin config block** owned by the bundled memory plugin) only when overriding its defaults; see the `typeclaw-memory` skill for the schema.
|
|
76
76
|
|
|
77
77
|
If the user said yes to "Wire a Discord bot?" during `typeclaw init`, the scaffold also includes:
|
|
78
78
|
|
|
@@ -291,7 +291,7 @@ The transport still performs DNS answer validation, socket pinning, mixed-answer
|
|
|
291
291
|
|
|
292
292
|
The `docker.file` block has two layers of customization:
|
|
293
293
|
|
|
294
|
-
1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`). Most are apt packages — boolean for on/off, version string for an apt pin — and benefit from BuildKit cache mounts. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
|
|
294
|
+
1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, `omoCli`). Most are apt packages — boolean for on/off, version string for an apt pin — and benefit from BuildKit cache mounts. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
|
|
295
295
|
2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#docker.file.append.` comment.
|
|
296
296
|
|
|
297
297
|
For the full toggle catalog (per-toggle defaults, types, version-pin rules, what each installs and why), the `append` single-line constraint, where things land in the build, and the restart/rebuild semantics, consult `references/dockerfile.md`. The playbooks below are the entry point; open the reference when you need the specifics of a toggle or the build-layer details. **`docker.file` is restart-required** — the next `typeclaw start` rewrites the Dockerfile and rebuilds the image automatically (no `--build` flag needed).
|
|
@@ -299,7 +299,7 @@ For the full toggle catalog (per-toggle defaults, types, version-pin rules, what
|
|
|
299
299
|
### When the user asks "install <package> in the container" / "add a Dockerfile line"
|
|
300
300
|
|
|
301
301
|
1. **Read `typeclaw.json`.**
|
|
302
|
-
2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts` (CJK glyph rendering for `agent-browser` screenshots), `cloudflared` (Cloudflare Quick tunnels), Anthropic's Claude Code CLI (`claudeCode`),
|
|
302
|
+
2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts` (CJK glyph rendering for `agent-browser` screenshots), `cloudflared` (Cloudflare Quick tunnels), Anthropic's Claude Code CLI (`claudeCode`), OpenAI's Codex CLI (`codexCli`), or OmO Native (`omoCli`), prefer the toggle: `"docker": { "file": { "ffmpeg": true } }`. For a pinned version of an apt toggle, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`. `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are boolean-only — no version-pin variant.
|
|
303
303
|
3. **Otherwise, use `append`.** Decide on a single-line entry — for apt installs, prefer one `RUN apt-get update && apt-get install -y --no-install-recommends <pkg> && rm -rf /var/lib/apt/lists/*` line. For env vars, one `ENV` line per variable.
|
|
304
304
|
4. **Validate no embedded newlines** (`append` only). Multi-step logic must be `&&`-chained on one line, not split across array entries unless those entries are independent Dockerfile instructions.
|
|
305
305
|
5. **Append to `docker.file.append`** (creating the field if it doesn't exist). Preserve existing entries.
|
|
@@ -524,7 +524,7 @@ Never request, echo, log, or commit values from `secrets.json` or `.env`. Gitign
|
|
|
524
524
|
- If `portForward` is set: `allow` is either `"*"` or an array of integers (1–65535); `deny`, if present, is an array of integers and **only valid when `allow` is `"*"`** (the schema rejects `deny` paired with a number-array `allow`)
|
|
525
525
|
- If `network` is set: `blockInternal` and `autoAllowResolvers` are booleans; `allow` is an array of bare IPv4 addresses or IPv4 CIDRs only
|
|
526
526
|
- If `docker.file.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
|
|
527
|
-
- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `cjkFonts` is boolean or `"auto"`; `python`, `cloudflared`, `claudeCode`, and `
|
|
527
|
+
- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `cjkFonts` is boolean or `"auto"`; `python`, `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are boolean only
|
|
528
528
|
- No unknown top-level keys you invented — keys outside the documented core fields are interpreted as **plugin config blocks** and only do something if a plugin owns them. Inventing one means the user thinks it took effect and it did not.
|
|
529
529
|
|
|
530
530
|
## Things you must not do
|
|
@@ -543,7 +543,7 @@ Never request, echo, log, or commit values from `secrets.json` or `.env`. Gitign
|
|
|
543
543
|
- **Do not promise to post to a channel the speaker's role does not cover.** The router drops every inbound where the speaking author resolves to a role without `channel.respond`. If the user wants you to post somewhere new, the prerequisite is a `roles` edit + restart, not a retry.
|
|
544
544
|
- **Do not conflate "stop replying" with "remove the role's match-rule".** Removing the match-rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
|
|
545
545
|
- **Do not edit the `Dockerfile` directly.** It is autogenerated and rewritten on every `typeclaw start` from `src/init/dockerfile.ts` in the typeclaw repo. Manual edits will be silently overwritten (and auto-committed away if the working tree is dirty). Customizations belong in the `docker.file` block (toggles or `append`).
|
|
546
|
-
- **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, ffmpeg, fonts-noto-cjk (cjkFonts), cloudflared, Anthropic's Claude Code CLI (claudeCode),
|
|
546
|
+
- **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, ffmpeg, fonts-noto-cjk (cjkFonts), cloudflared, Anthropic's Claude Code CLI (claudeCode), OpenAI's Codex CLI (codexCli), or OmO Native (omoCli) installed (or removed, or pinned), use the toggle. The apt toggles are the cache-mounted path; `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are non-apt boolean toggles, and the `claudeCode`/`codexCli` toggles pair with the `typeclaw-claude-code`/`typeclaw-codex-cli` skills that document auth + usage. `append` for any of these is slower and harder to read.
|
|
547
547
|
- **Do not use `docker.file.append` for things that belong in the template.** If the user wants a system package _every_ typeclaw user should have, that's a typeclaw release, not a per-agent `append`. Suggest filing an issue.
|
|
548
548
|
- **Do not put multiline strings in `docker.file.append`.** The schema rejects entries with embedded `\n`/`\r`. Use one entry per Dockerfile instruction; chain shell logic with `&&` on one line.
|
|
549
549
|
- **Do not pass `pkg=ver` as a toggle version string.** The schema rejects `=` in version strings. Pass just the version (`"gh": "2.40.0"`); the renderer prepends `pkg=` itself. Same for whitespace — version strings cannot contain spaces.
|
|
@@ -6,21 +6,22 @@ Companion to the **Dockerfile** section of the `typeclaw-config` SKILL.md. The S
|
|
|
6
6
|
|
|
7
7
|
`docker.file` has two layers of customization:
|
|
8
8
|
|
|
9
|
-
1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared`, `claudeCode`, and `
|
|
9
|
+
1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, `omoCli`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are the exceptions: `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package, and `omoCli` downloads digest-verified OmO Native 5.1.19 assets; all four are boolean-only. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
|
|
10
10
|
2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#docker.file.append.` comment.
|
|
11
11
|
|
|
12
|
-
| Field | Required | Type | Notes
|
|
13
|
-
| ------------- | -------- | ------------------- |
|
|
14
|
-
| `tmux` | no | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).
|
|
15
|
-
| `gh` | no | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.
|
|
16
|
-
| `python` | no | boolean | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.
|
|
17
|
-
| `ffmpeg` | no | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.
|
|
18
|
-
| `cjkFonts` | no | boolean or `"auto"` | Default `"auto"`. Installs `fonts-noto-cjk` (~89 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `"auto"` resolves at `typeclaw start` from the host locale (`LANG`/`LC_ALL`/`Intl`): a CJK host (ja/ko/zh) installs the fonts, any other host skips them. An explicit `true`/`false` forces the decision. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes).
|
|
19
|
-
| `cloudflared` | no | boolean | Default `false`. Downloads the pinned `cloudflared` GitHub release (~38 MB) into the image so `cloudflare-quick` tunnels work. Default `false` skips the layer on agents that don't use tunnels; `typeclaw tunnel add` / `channel add github` with a Cloudflare provider flip it to `true` automatically and prompt for a restart, so the happy path needs no manual edit. If the binary is absent when a tunnel starts, the tunnel goes `permanently-failed` with a "set docker.file.cloudflared: true and run typeclaw restart" message. Boolean-only — pinning is owned by the typeclaw release.
|
|
20
|
-
| `xvfb` | no | boolean | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.
|
|
21
|
-
| `claudeCode` | no | boolean | Default `false`. `true` runs Anthropic's official
|
|
22
|
-
| `codexCli` | no | boolean | Default `false`. `true` runs `bun install -g @openai/codex`
|
|
23
|
-
| `
|
|
12
|
+
| Field | Required | Type | Notes |
|
|
13
|
+
| ------------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
14
|
+
| `tmux` | no | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`). |
|
|
15
|
+
| `gh` | no | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version. |
|
|
16
|
+
| `python` | no | boolean | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin. |
|
|
17
|
+
| `ffmpeg` | no | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version. |
|
|
18
|
+
| `cjkFonts` | no | boolean or `"auto"` | Default `"auto"`. Installs `fonts-noto-cjk` (~89 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `"auto"` resolves at `typeclaw start` from the host locale (`LANG`/`LC_ALL`/`Intl`): a CJK host (ja/ko/zh) installs the fonts, any other host skips them. An explicit `true`/`false` forces the decision. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). |
|
|
19
|
+
| `cloudflared` | no | boolean | Default `false`. Downloads the pinned `cloudflared` GitHub release (~38 MB) into the image so `cloudflare-quick` tunnels work. Default `false` skips the layer on agents that don't use tunnels; `typeclaw tunnel add` / `channel add github` with a Cloudflare provider flip it to `true` automatically and prompt for a restart, so the happy path needs no manual edit. If the binary is absent when a tunnel starts, the tunnel goes `permanently-failed` with a "set docker.file.cloudflared: true and run typeclaw restart" message. Boolean-only — pinning is owned by the typeclaw release. |
|
|
20
|
+
| `xvfb` | no | boolean | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin. |
|
|
21
|
+
| `claudeCode` | no | boolean | Default `false`. `true` runs Anthropic's official installer with version argument `2.1.299`, copies the resolved executable into root-owned `/usr/local/lib/typeclaw-coding-agents/claude/2.1.299/claude`, and links `/usr/local/bin/claude` there so model bash's bwrap sandbox can execute it without binding `/root`. The layer retains the existing hooks and `~/.claude.json` onboarding seed. Boolean-only; the version pin is owned by the TypeClaw release. Protected authentication profiles remain masked. |
|
|
22
|
+
| `codexCli` | no | boolean | Default `false`. `true` runs `bun install -g @openai/codex@0.162.1` with `BUN_INSTALL=/usr/local/lib/typeclaw-coding-agents/codex` and `BUN_INSTALL_BIN=/usr/local/lib/typeclaw-coding-agents/codex/bin`. The root-owned global package tree (including the vendored native binary) stays under `/usr/local`; `/usr/local/bin/codex` invokes its JS launcher with Bun because the image's `node` fallback is outside the sandbox PATH. The layer retains the existing hook scripts and `~/.codex/hooks.json`. Boolean-only; the version pin is owned by the TypeClaw release. Protected authentication profiles remain masked. |
|
|
23
|
+
| `omoCli` | no | boolean | Default `false`. Installs digest-verified OmO Native 5.1.19 (arm64 or amd64-baseline) under `/usr/local/lib/typeclaw-coding-agents/omo/5.1.19/`, linked from `/usr/local/bin/omo`. Both Dockerfile branches use the same pin. Task-local HOME/config and broker authority come from `coding_agent`; no provider profile is installed. See `typeclaw-omo-cli`. |
|
|
24
|
+
| `append` | no | array of strings | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`. |
|
|
24
25
|
|
|
25
26
|
Toggle version strings reject whitespace and `=` (apt-injection guard) — pass just the version, not `pkg=ver`.
|
|
26
27
|
|
|
@@ -170,7 +170,7 @@ The handler receives a `ctx` with the LLM-call surface of a container plugin com
|
|
|
170
170
|
| `ctx.signal` | `AbortSignal` | Reserved for future cancellation; currently never aborted by the runtime (matches existing prompt/exec cron behavior — in-flight work runs to completion on container shutdown). Already threaded into `ctx.prompt` and `ctx.exec`, so future aborts propagate without handler-author changes. |
|
|
171
171
|
| `ctx.permissions` | `PermissionService` | Same service the rest of the runtime uses. Most handlers don't need it; the LLM session resolves permissions through `ctx.origin` automatically. |
|
|
172
172
|
| `ctx.origin` | `SessionOrigin` (cron-shaped) | `{ kind: 'cron', jobId, jobKind: 'handler', scheduledByRole, scheduledByOrigin }`. Plugin-contributed jobs default to `scheduledByRole: 'owner'`. |
|
|
173
|
-
| `ctx.prompt` | `(text: string) => Promise<string>` | Opens a brand-new agent session with the full toolset, sends `text`, returns the final assistant message.
|
|
173
|
+
| `ctx.prompt` | `(text: string) => Promise<string>` | Opens a brand-new agent session with the full toolset, sends `text`, returns the final assistant message. Gets the same shared system policy as every session, without the interactive orchestration context, roster, git nudge, or MCP catalog a TUI session adds. |
|
|
174
174
|
| `ctx.subagent` | `(name: string, payload?) => Promise<void>` | Invokes a registered subagent. Same dispatch path as `PluginContext.spawnSubagent`. |
|
|
175
175
|
| `ctx.exec` | `` ctx.exec`shell pipeline` `` → `Promise<CommandExecResult>` | Tagged template; runs in the agent folder with `ctx.signal` threaded through. Abort kills the entire process group (SIGTERM → 5s grace → SIGKILL). |
|
|
176
176
|
|
|
@@ -102,11 +102,11 @@ The same applies to PRs: a quick `gh pr list --search` avoids opening a PR for s
|
|
|
102
102
|
```sh
|
|
103
103
|
git -C <checkout> push <remote> <branch>
|
|
104
104
|
```
|
|
105
|
-
Then
|
|
105
|
+
Then open the PR yourself, with every field explicit and inline:
|
|
106
106
|
```sh
|
|
107
107
|
gh pr create --repo OWNER/REPO --title '<conventional title>' --body '<filled body>' --head <branch> --base <branch>
|
|
108
108
|
```
|
|
109
|
-
|
|
109
|
+
All five flags are required (`--draft` is optional). `--fill`, `--body-file`, `--template`, `--editor`, `--web` and `--attach` are refused because they read local files or open an editor/browser while the credential is live; omitting `--head` would make gh interrogate the checkout and offer to push. Fix ordinary Git errors yourself and retry. Without the `gitExfil` bypass, a plain one-branch push still works to repos listed in `channels.github.repos` under GitHub App auth; if `gitExfil` refuses it anyway, your role can't publish to that repository — surface the denial and only hand the operator a push command when the broker or your permissions refuse it. If the trusted store is unavailable, ask the operator to run `gh auth login --hostname github.com` on the host; the next real `typeclaw start` or `typeclaw restart` refreshes it automatically, while a start against an already-running container does not. When handing off, name a host-accessible checkout; never direct the operator to a per-session `/tmp` path.
|
|
110
110
|
5. **Verify it landed** as intended (`gh issue view` / `gh pr view`) — confirm the template rendered and nothing got truncated.
|
|
111
111
|
|
|
112
112
|
## Things you must not do
|
|
@@ -5,7 +5,7 @@ description: Use this skill whenever the user asks what you remember, what you f
|
|
|
5
5
|
|
|
6
6
|
# typeclaw-memory
|
|
7
7
|
|
|
8
|
-
The agent's long-term memory is sharded across files in `memory/topics/<slug>.md`. Each shard is one topic with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, optional `tags`) + body markdown.
|
|
8
|
+
The agent's long-term memory is sharded across files in `memory/topics/<slug>.md`. Each shard is one topic with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, optional `tags`) + body markdown. The dreaming subagent writes shard bodies and the runtime computes the frontmatter; neither is yours to author.
|
|
9
9
|
|
|
10
10
|
## Reading
|
|
11
11
|
|
|
@@ -15,9 +15,9 @@ Under budget you get shard bodies de-duplicated across turns; over budget you ge
|
|
|
15
15
|
|
|
16
16
|
## Writing
|
|
17
17
|
|
|
18
|
-
You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards.
|
|
18
|
+
You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards. Do not edit `memory/topics/`, `memory/skills/`, or the stream files yourself — the dreaming subagent and runtime own them. To capture something memorable, surface it in your reply and let the memory-logger append it to `memory/streams/`.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
`memory/skills/<name>/SKILL.md` is muscle memory the dreaming subagent distills from recurring procedures; the runtime auto-loads those as first-class skills on next boot. A durable task procedure you want to keep goes to its existing editable owner skill (or a support file that skill links) first — see `typeclaw-skills` for who owns which skill — not into `memory/skills/` or `AGENTS.md`.
|
|
21
21
|
|
|
22
22
|
## Citations
|
|
23
23
|
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: typeclaw-omo-cli
|
|
3
|
+
description: Use for explicit OmO Native delegation, substantial coding or analysis suited to OmO, a second opinion, or an attempt to invoke omo. Runs the brokered coding_agent tool in a persistent isolated worktree through a background operator, with brokered internal subagents and no credential transfer.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Delegate to OmO Native
|
|
7
|
+
|
|
8
|
+
Brief the repository, task, constraints, and acceptance checks. Use the existing background `operator` for substantial work; its `coding_agent` invocation stays foreground while the main conversation remains responsive.
|
|
9
|
+
|
|
10
|
+
## Prerequisites
|
|
11
|
+
|
|
12
|
+
The host operator enables `docker.file.omoCli:true`, configures `anthropic` or `openai-codex` through `typeclaw provider add <provider>`, and runs `typeclaw start` to rebuild the image. OmO Native 5.1.19 requires the supported Linux/bwrap profile. Use the tool's safe readiness diagnostic, never credential-file or environment inspection. See [auth-flow.md](references/auth-flow.md).
|
|
13
|
+
|
|
14
|
+
## Run and continue
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"action": "run",
|
|
19
|
+
"engine": "omo",
|
|
20
|
+
"repo": "/agent/mounts/project",
|
|
21
|
+
"modelRef": "anthropic/claude-sonnet-4-6",
|
|
22
|
+
"mode": "code",
|
|
23
|
+
"prompt": "Implement the requested change and run its tests.",
|
|
24
|
+
"timeoutSeconds": 1800
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Select a configured/curated `anthropic/...` or `openai-codex/...` model. One provider/model serves the parent, internal categories, named agents, and compaction. Other providers and model fallback are unavailable. `openai-codex` uses ChatGPT subscription OAuth, not an OpenAI API key.
|
|
29
|
+
|
|
30
|
+
Record `taskId`, `baseSha`, and `worktreePath`. The baseline is committed HEAD; dirty source changes are excluded. Never create a WIP commit to satisfy delegation. Use `mode:"plan"` for a read-only worktree and Git database. Implementation requires an explicit authorized transition:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"action": "run",
|
|
35
|
+
"engine": "omo",
|
|
36
|
+
"taskId": "<returned UUID>",
|
|
37
|
+
"mode": "code",
|
|
38
|
+
"prompt": "Implement the agreed plan and run the checks."
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The runtime retains the exact session UUID and checks that its saved session exists before resume. Do not select recent sessions, invent IDs, or rewrite OmO configuration. Engine, provider, model, and version remain fixed. See [headless-sessions.md](references/headless-sessions.md).
|
|
43
|
+
|
|
44
|
+
## Review and recovery
|
|
45
|
+
|
|
46
|
+
Inspect `state`, `finalMessage`, `exitCode`, and the complete patch, including untracked and binary files. A JSON-mode provider failure can exit zero; the runner checks structured stop reasons. A question in any language needs a follow-up prompt, not keyword detection or polling. A claim that tests passed is not independent evidence.
|
|
47
|
+
|
|
48
|
+
Run acceptance checks and apply reviewed changes through ordinary tools. The tool never merges, pushes, or creates a PR in the source repository. Timeout, cancellation, and failure preserve partial work. Retrieve it with `{"action":"result","taskId":"<returned UUID>"}`. Discard a stopped task only when its work is no longer needed: `{"action":"dispose","taskId":"<returned UUID>","discard":true}`. See [results-and-worktrees.md](references/results-and-worktrees.md).
|
|
49
|
+
|
|
50
|
+
## Credential boundary
|
|
51
|
+
|
|
52
|
+
OmO receives only a fresh local inference capability. Task-local HOME, sessions, and generated provider config contain no real provider credential. Do not run login flows, copy profiles, pass tokens, or disable TypeClaw sandboxing. OmO's native approvals are disabled only inside the outer sandbox; a bare `omo` shell invocation has no broker authority.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# OmO authentication through the broker
|
|
2
|
+
|
|
3
|
+
Host setup is `docker.file.omoCli:true`, `typeclaw provider add anthropic` or `typeclaw provider add openai-codex`, then `typeclaw start`. Anthropic supports API-key or subscription OAuth credentials; `openai-codex` supports ChatGPT subscription OAuth only. Do not silently switch billing surfaces.
|
|
4
|
+
|
|
5
|
+
The trusted runtime resolves and refreshes credentials. A per-invocation broker authenticates a fresh local capability, permits only the selected model and exact inference routes, rebuilds headers, and uses fixed upstreams. OmO's Anthropic OAuth capability has a transport compatibility prefix but is not a real OAuth token. The child never receives an access, refresh, or ID token, account identifier, or exported auth profile.
|
|
6
|
+
|
|
7
|
+
The generated provider config routes main, category, named-agent, and compaction calls through this broker. Categories use one explicit model chain; named agents clear inherited fallback chains. Memory side models, telemetry, update checks, ambient OAuth extensions, and MCP startup are disabled. Ordinary dependency downloads and tool networking remain governed by the outer sandbox, not by an offline marketing claim.
|
|
8
|
+
|
|
9
|
+
Missing credentials affect only the requested task. Ask the host operator to repair the chosen provider using its setup command, then retry. Missing binary or sandbox support requires an image rebuild or host namespace repair, never an unconfined fallback. Missing exact session data requires restoration or review of retained changes, not a fresh conversation disguised as a resume.
|
|
10
|
+
|
|
11
|
+
The guarantee covers private canonical credentials. Keys already exposed in `.env`, prompts, source objects, or model-readable files are outside it. Live subscription tools, resume, refresh, compaction, and Linux amd64/arm64 bwrap execution remain release gates; mock traffic does not establish upstream acceptance.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Headless OmO sessions
|
|
2
|
+
|
|
3
|
+
The runtime invokes pinned OmO with `-p --mode json`, a concrete brokered model, an exact `--session-id`, and a task-local `--session-dir`. Prompt text travels over stdin. No terminal, tmux process, picker, or Stop-hook polling is involved.
|
|
4
|
+
|
|
5
|
+
The session header must match the recorded UUID and worktree. The runner extracts text from the last assistant in the final settled `agent_end.messages`, excluding custom messages, tools, and thinking. It resets completion on a new main `agent_start` and ignores retrying boundaries. It drains both pipes and waits for process exit.
|
|
6
|
+
|
|
7
|
+
Success requires clean JSONL, exit zero, a matching session header, a settled final run, and assistant `stopReason:"stop"`. `length` and `toolUse` are incomplete. `error` and `aborted` cannot become success even when OmO exits zero. Individual recoverable tool errors remain visible in the saved structured events.
|
|
8
|
+
|
|
9
|
+
A new tool call with the same TypeClaw `taskId` resumes the exact session. Runtime ownership checks, invocation locking, provider/model/version pinning, and fresh capabilities apply on every turn. Missing or unsafe session files do not trigger OmO's implicit fresh-session behavior.
|
|
10
|
+
|
|
11
|
+
Plan mode makes worktree and Git storage read-only, regardless of native approval policy. Task-local conversation state remains writable. Internal OmO children run in-process under the same outer sandbox; its task IDs are not TypeClaw authority. Processes do not survive invocation teardown. After interruption, preserve the diff and resume explicitly.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# OmO results and worktrees
|
|
2
|
+
|
|
3
|
+
Container-stage task state persists under `/agent/workspace/coding-agents/<task-id>/`:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
git/ private Git object database
|
|
7
|
+
worktree/ detached checkout of recorded committed HEAD
|
|
8
|
+
omo/home/.omo/ generated orchestration config and provisioned native runtime
|
|
9
|
+
omo/agent/ generated models/settings and engine state
|
|
10
|
+
omo/sessions/ exact-session conversation files
|
|
11
|
+
omo/task-state/ internal OmO child-task records
|
|
12
|
+
omo/tmp/ task scratch
|
|
13
|
+
omo/config/ cache/ data/ state/ redirected XDG state
|
|
14
|
+
output/ JSONL, stderr, receipt, complete patch and change inventory
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The live source worktree and credential write directory are not mounted into the child. Snapshot bootstrap reads only source Git metadata; execution and artifact collection use task-private files. Ordinary project instructions remain available, while existing project/ancestor OmO config operands are masked so they cannot replace the generated model chains at launch.
|
|
18
|
+
|
|
19
|
+
The complete patch includes staged, unstaged, untracked, deleted, binary, executable-mode, and symlink changes against the recorded base. Capture does not mutate the CLI's index. Oversized artifacts are marked incomplete rather than presented as complete truncated patches.
|
|
20
|
+
|
|
21
|
+
Review the diff and run checks before applying it through normal tools. Timeout/failure preserves state; `result` retrieves it after restart. The private runtime registry, not editable CLI output, owns task authority and session identity.
|
|
22
|
+
|
|
23
|
+
Use explicit `dispose` with `discard:true` only for a stopped task whose work is no longer needed. Never prune sibling tasks or force-delete useful partial work. Task files stay outside system-managed memory/session backups. Shared workspace readers may inspect these non-secret artifacts; task IDs are not a separate tenant boundary.
|
|
@@ -333,13 +333,13 @@ type CronHandlerContext = {
|
|
|
333
333
|
readonly signal: AbortSignal // reserved for future cancellation; currently inert
|
|
334
334
|
readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" in §5.7 below
|
|
335
335
|
readonly origin: SessionOrigin // { kind: 'cron', jobKind: 'handler', ... }
|
|
336
|
-
readonly prompt: (text: string) => Promise<string> // full agent session,
|
|
336
|
+
readonly prompt: (text: string) => Promise<string> // full agent session, shared policy without interactive context
|
|
337
337
|
readonly subagent: (name, payload?) => Promise<void>
|
|
338
338
|
readonly exec: (cmd, ...vals) => Promise<CommandExecResult> // tagged template
|
|
339
339
|
}
|
|
340
340
|
```
|
|
341
341
|
|
|
342
|
-
The `prompt` / `subagent` / `exec` surface is identical to `ContainerCommandContext` (§5.7) and reuses the same underlying implementation — abort semantics, process-group kill, slim
|
|
342
|
+
The `prompt` / `subagent` / `exec` surface is identical to `ContainerCommandContext` (§5.7) and reuses the same underlying implementation — abort semantics, process-group kill, and the slim session context are all shared. Differences from `ContainerCommandContext`: no `stdin` / `stdout` / `stderr` (cron has no caller piping bytes), no `args` (handlers are scheduled, not invoked with flags), no return value (throw to signal failure, the consumer logs).
|
|
343
343
|
|
|
344
344
|
#### When to use which `kind`
|
|
345
345
|
|
|
@@ -401,22 +401,22 @@ hooks: {
|
|
|
401
401
|
}
|
|
402
402
|
```
|
|
403
403
|
|
|
404
|
-
| Hook | Direction | Payload | Notes
|
|
405
|
-
| -------------------- | ------------------- | --------------------------------------------- |
|
|
406
|
-
| `session.start` | observe | `{ sessionId, agentDir }` | Awaited before TUI gets `connected`.
|
|
407
|
-
| `session.end` | observe | `{ sessionId }` | Awaited before close handler resolves.
|
|
408
|
-
| `session.idle` | observe | `{ sessionId, parentTranscriptPath, idleMs }` | Fires **after every prompt completion** (success or error). The agent is "idle" the moment it stops responding. Plugins owning idle-debounced work (e.g. memory-logger spawn) install their own `setTimeout` and reset it on each event. `idleMs` is reserved (currently `0`).
|
|
409
|
-
| `session.prompt` | intervene | `{ prompt, sessionId, agentDir }` | Reassign `event.prompt` to mutate the **system prompt** as it's being assembled at session creation. `event.prompt` is
|
|
410
|
-
| `session.turn.start` | observe | `{ sessionId, agentDir, userPrompt }` | Fires **before every `session.prompt(text)` call** with `userPrompt` set to the literal text the session is about to receive. This is the right hook for "react to what the user just asked" (e.g. memory retrieval keyed on the user's question).
|
|
411
|
-
| `session.turn.end` | observe | `{ sessionId, agentDir }` | Fires after every `session.prompt(text)` returns (success or error). Pair with `session.turn.start` for per-turn bookkeeping.
|
|
412
|
-
| `tool.before` | intervene | `{ tool, sessionId, callId, args }` | Fires for plugin-defined tools and TypeClaw-exposed system tools, including built-in pi tools when plugins are wired. Mutate `event.args`, or return `{ block: true, reason }`. First block short-circuits.
|
|
413
|
-
| `tool.after` | observe / transform | `{ tool, sessionId, callId, result }` | Fires after plugin-defined tools and TypeClaw-exposed system tools. Observe `event.result`; tool result mutation is best-effort and tool-specific.
|
|
404
|
+
| Hook | Direction | Payload | Notes |
|
|
405
|
+
| -------------------- | ------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
406
|
+
| `session.start` | observe | `{ sessionId, agentDir }` | Awaited before TUI gets `connected`. |
|
|
407
|
+
| `session.end` | observe | `{ sessionId }` | Awaited before close handler resolves. |
|
|
408
|
+
| `session.idle` | observe | `{ sessionId, parentTranscriptPath, idleMs }` | Fires **after every prompt completion** (success or error). The agent is "idle" the moment it stops responding. Plugins owning idle-debounced work (e.g. memory-logger spawn) install their own `setTimeout` and reset it on each event. `idleMs` is reserved (currently `0`). |
|
|
409
|
+
| `session.prompt` | intervene | `{ prompt, sessionId, agentDir }` | Reassign `event.prompt` to mutate the **system prompt** as it's being assembled at session creation. `event.prompt` is the shared TypeClaw policy + IDENTITY + SOUL (the same policy for every standard origin; `systemPromptOverride` subagents don't fire it) — it is NOT the user's message. Runs once per session start, in plugin-load order. See CRITICAL note below. |
|
|
410
|
+
| `session.turn.start` | observe | `{ sessionId, agentDir, userPrompt }` | Fires **before every `session.prompt(text)` call** with `userPrompt` set to the literal text the session is about to receive. This is the right hook for "react to what the user just asked" (e.g. memory retrieval keyed on the user's question). |
|
|
411
|
+
| `session.turn.end` | observe | `{ sessionId, agentDir }` | Fires after every `session.prompt(text)` returns (success or error). Pair with `session.turn.start` for per-turn bookkeeping. |
|
|
412
|
+
| `tool.before` | intervene | `{ tool, sessionId, callId, args }` | Fires for plugin-defined tools and TypeClaw-exposed system tools, including built-in pi tools when plugins are wired. Mutate `event.args`, or return `{ block: true, reason }`. First block short-circuits. |
|
|
413
|
+
| `tool.after` | observe / transform | `{ tool, sessionId, callId, result }` | Fires after plugin-defined tools and TypeClaw-exposed system tools. Observe `event.result`; tool result mutation is best-effort and tool-specific. |
|
|
414
414
|
|
|
415
415
|
**Multiple plugins** for the same hook run **in plugin-load order**. For `session.prompt`, the next plugin sees the previous plugin's mutated string.
|
|
416
416
|
|
|
417
417
|
#### CRITICAL: `session.prompt`'s `event.prompt` is the SYSTEM prompt, not the user message
|
|
418
418
|
|
|
419
|
-
The `prompt` field on `SessionPromptEvent` is the system prompt as it's being composed by `createResourceLoader` (
|
|
419
|
+
The `prompt` field on `SessionPromptEvent` is the system prompt as it's being composed by `createResourceLoader` (shared policy + `IDENTITY.md` + `SOUL.md`), NOT the user's most recent message. Reading it as if it were the user's prompt — and feeding it to a retrieval system, classifier, or LLM — will keyword-mine TypeClaw's framing prose (`TypeClaw`, `subagent`, `AGENTS.md`) on every session.
|
|
420
420
|
|
|
421
421
|
If you want the **user's actual prompt** (their message text), subscribe to `session.turn.start` and read `event.userPrompt`. The bundled memory plugin's per-turn retrieval uses this hook so it embeds the user's text instead of the assembling system prompt; see `src/bundled-plugins/memory/index.ts`'s `session.turn.start` handler.
|
|
422
422
|
|
|
@@ -496,7 +496,7 @@ type ContainerCommandContext = {
|
|
|
496
496
|
|
|
497
497
|
Key facts about each capability:
|
|
498
498
|
|
|
499
|
-
- **`ctx.prompt(text)`** opens a brand-new `AgentSession` with the full agent toolset (read/bash/edit/write/grep/find/ls + plugin tools), sends `text` as if a user typed it, and returns the last assistant message. The session is created and disposed inside the call.
|
|
499
|
+
- **`ctx.prompt(text)`** opens a brand-new `AgentSession` with the full agent toolset (read/bash/edit/write/grep/find/ls + plugin tools), sends `text` as if a user typed it, and returns the last assistant message. The session is created and disposed inside the call. It runs with a subagent-shaped origin, so it gets the same shared system policy as a TUI session but skips the interactive orchestration context, subagent roster, git nudge, and MCP catalog.
|
|
500
500
|
- **`ctx.subagent(name, payload)`** invokes a registered subagent (yours or another plugin's). Returns when the subagent's `runSession` resolves.
|
|
501
501
|
- **`ctx.exec` is a tagged template** — `await ctx.exec\`git log --oneline -10\``runs the command in the agent folder with`ctx.signal` threaded through. Aborts kill the entire process group (SIGTERM → 5s grace → SIGKILL) so daemonized grandchildren don't outlive the abort.
|
|
502
502
|
- **`ctx.origin`** carries the caller's `SessionOrigin`. For host-invoked (TUI op) calls it's `{ kind: 'tui', ... }`; for cron-invoked calls it's the cron job's origin including `scheduledByRole`. **No silent role elevation** — a cron job running as `scheduledByRole: 'member'` invokes the command with that same role, and permission checks inside the command resolve accordingly.
|
|
@@ -851,7 +851,7 @@ Plugin `ToolContext` is `{ signal, sessionId, agentDir, logger }`. There is no `
|
|
|
851
851
|
- **Engine bridge**: `src/agent/plugin-tools.ts` (the ONLY file that imports both plugin and engine types)
|
|
852
852
|
- **Plugin wiring at boot**: `src/run/index.ts` (`startAgent` calls `loadPlugins`, merges into registries)
|
|
853
853
|
- **Hook fire sites**:
|
|
854
|
-
- `session.prompt`: `src/agent/index.ts` `createResourceLoader` (during system-prompt assembly; `event.prompt` is
|
|
854
|
+
- `session.prompt`: `src/agent/index.ts` `createResourceLoader` (during system-prompt assembly; `event.prompt` is shared policy + IDENTITY + SOUL, NOT the user message)
|
|
855
855
|
- `session.turn.start` / `session.turn.end`: bracket every `session.prompt(text)` call across all four prompt-driver sites — `src/server/index.ts` (TUI drain + fallback), `src/channels/router.ts` (`fireSessionTurnStart`), `src/cron/consumer.ts` (per-attempt), `src/agent/subagents.ts` (subagent runner). `userPrompt` carries the literal text being passed to `session.prompt(text)`.
|
|
856
856
|
- `session.idle`: `src/server/index.ts` `drain()` — fires immediately after every `session.prompt()` resolves (success or error)
|
|
857
857
|
- `session.start`/`session.end`: `src/server/index.ts` ws open/close
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: typeclaw-skills
|
|
3
|
-
description: Use this skill whenever the user asks you to install, find, list, update, or remove an agent skill, whenever you yourself want to add a new capability via a skill, or whenever you are about to edit any file under `.agents/skills/`. Triggers include "install skill", "add a skill", "find a skill", "update skills", "remove skill", "skill from <repo>", any mention of the `skills` CLI / `bunx skills`, any reference to `SKILL.md`, `skills-lock.json`, `.skill-lock.json`, and any time you read or write under `.agents/skills/<name>/`. Read it before you touch a skill — TypeClaw has three skill layers with different ownership rules, and editing a skill that the `skills` CLI manages will silently get overwritten on the next `bunx skills update`.
|
|
3
|
+
description: Use this skill whenever the user asks you to install, find, list, update, or remove an agent skill, whenever you yourself want to add a new capability via a skill or record a durable procedure fix (deciding between an existing skill, its support doc, a new skill, or `AGENTS.md`), or whenever you are about to edit any file under `.agents/skills/`. Triggers include "install skill", "add a skill", "find a skill", "update skills", "remove skill", "skill from <repo>", any mention of the `skills` CLI / `bunx skills`, any reference to `SKILL.md`, `skills-lock.json`, `.skill-lock.json`, and any time you read or write under `.agents/skills/<name>/`. Read it before you touch a skill — TypeClaw has three skill layers with different ownership rules, and editing a skill that the `skills` CLI manages will silently get overwritten on the next `bunx skills update`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# typeclaw-skills
|
|
@@ -201,9 +201,26 @@ Do not invent a reason for a half-applied install. The lockfile and the working
|
|
|
201
201
|
|
|
202
202
|
If the agent folder is not a git repo, `bunx skills` still works — it just means there's no commit to make. Tell the user once: "Heads up, this folder isn't a git repo, so I can't snapshot the install."
|
|
203
203
|
|
|
204
|
+
## Before authoring: find the owner
|
|
205
|
+
|
|
206
|
+
A new skill is the last option, not the first, when you are the one deciding where a lesson goes. When a recurring task needs a durable correction or more detail, route it to one owner. If the user explicitly asks for a specific skill or file, that request stands, subject to the ownership rules in this skill.
|
|
207
|
+
|
|
208
|
+
1. **An existing editable skill already covers the task** → edit that skill in place. Editable means a user-created skill under `.agents/skills/` that is in neither lockfile (see the workflow above), or a skill shipped by a local plugin you author in this agent folder (`packages/<name>/`, via its `skills`/`skillsDirs`) — edit that one in the plugin's source.
|
|
209
|
+
2. **The owner is right, but the detail is long** (edge cases, a runbook) → put it in a support file the skill already links (or add one next to `SKILL.md` and link it), and keep a short pointer in `SKILL.md`.
|
|
210
|
+
3. **The owner is not editable** → do not edit it. A system `typeclaw-*` skill is fixed with a typeclaw PR. A downloaded skill in a lockfile gets one of the three options from the workflow above (fork under a new name, propose upstream at its `<source>`, or `bunx skills remove` it first). A skill shipped by a published plugin package is proposed to that package. `memory/skills/` belongs to the dreaming subagent and is never hand-edited.
|
|
211
|
+
4. **An independent recurring workflow with no fitting owner** → author a new user-created skill (below).
|
|
212
|
+
|
|
213
|
+
Not every lesson belongs in a skill:
|
|
214
|
+
|
|
215
|
+
- **`AGENTS.md`**, when present where the session's project-context discovery finds it, is loaded into each such session. Keep it to cross-task conventions and short pointers to the owning skill — not task procedures, which would duplicate the skill and grow every one of those sessions' context.
|
|
216
|
+
- **Deterministic requirements** (fixed codes, mappings, thresholds, mandatory items) belong in code or config with a check that exercises the behavior. Prose in a skill is not enforcement.
|
|
217
|
+
- **A one-off event or transient failure** (a single timeout, a flaky network call) is not a standing rule. Report it; don't write it down as procedure.
|
|
218
|
+
|
|
219
|
+
None of this grants edit rights you don't already have: operator-owned files (`package.json` and dependencies, `.env`, secrets) keep their own rules.
|
|
220
|
+
|
|
204
221
|
## Authoring a user-created skill
|
|
205
222
|
|
|
206
|
-
When the user says "write me a skill for X" or
|
|
223
|
+
When the user says "write me a skill for X", or the owner check above found no existing skill that fits a recurring procedure:
|
|
207
224
|
|
|
208
225
|
1. **Pick a name that does not collide.** Check both `<typeclaw-package>/src/skills/` (system) and `.agents/skills/` (user). Prefer specific names (`postgres-backups`, not `db`). Do not prefix with `typeclaw-` — that prefix is reserved for system skills shipped by typeclaw.
|
|
209
226
|
2. **Create the directory**: `mkdir -p .agents/skills/<name>`.
|
|
@@ -1,13 +1,26 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: typeclaw-troubleshooting
|
|
3
|
-
description: Use this skill when you are stuck in a fix-it loop — you've made roughly three attempts at the same failure and you're still cycling shell commands (kill the process, re-run, `sleep`, `capture-pane`, inspect, retry) without converging. Triggers include a hung or runaway process that won't die, a `C-c` that didn't stop the program, `<defunct>`/zombie processes piling up in `ps`, an interactive program that blocks `bash` waiting for input, a script that "ran" but produced no output and no file, repeated "not found"/timeout/same-error-again loops, and any moment you catch yourself thinking "let me wait a bit more and check again" for the third time. Read it before you spawn `operator` to take over the debugging — it covers the operator hand-off prompt, the tmux session pattern, killing stuck/zombie processes properly, and the edge-triggered capture-pane polling loop that the inline retry-and-sleep approach gets wrong.
|
|
3
|
+
description: Use this skill when you are stuck in a fix-it loop — you've made roughly three attempts at the same failure and you're still cycling shell commands (kill the process, re-run, `sleep`, `capture-pane`, inspect, retry) without converging. Triggers include a hung or runaway process that won't die, a `C-c` that didn't stop the program, `<defunct>`/zombie processes piling up in `ps`, an interactive program that blocks `bash` waiting for input, a script that "ran" but produced no output and no file, repeated "not found"/timeout/same-error-again loops, and any moment you catch yourself thinking "let me wait a bit more and check again" for the third time. Also read it before you start a minutes-long or input-waiting program in your own session (dev server, REPL, watcher, `docker compose up`, interactive installer) — foreground `bash` blocks until exit, and this skill has the detached tmux start/observe/drive/stop pattern. Read it before you spawn `operator` to take over the debugging — it covers the operator hand-off prompt, the tmux session pattern, killing stuck/zombie processes properly, and the edge-triggered capture-pane polling loop that the inline retry-and-sleep approach gets wrong.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# typeclaw-troubleshooting
|
|
7
7
|
|
|
8
8
|
When a problem fights back, the failure mode is not "I can't fix it" — it's "I'm burning my own context and freezing the conversation while I fix it." A debugging loop is inherently noisy: every retry dumps stale shell output, zombie-process listings, and pane captures into your context, and each blocking `bash` call (especially `sleep N` followed by a capture) leaves the user staring at a frozen-looking conversation. The fix is to move the loop out of your session and into `operator`, which has bash-with-side-effects and runs in its own context window.
|
|
9
9
|
|
|
10
|
-
This skill is the runbook for that hand-off. Read it once you've hit the trigger (~3 attempts on the same failure without convergence), **before** you spawn `operator`.
|
|
10
|
+
This skill is the runbook for that hand-off. Read it once you've hit the trigger (~3 attempts on the same failure without convergence), **before** you spawn `operator`. It also owns the plain long-running-command pattern below, which applies before any loop starts.
|
|
11
|
+
|
|
12
|
+
## Long-running and interactive commands
|
|
13
|
+
|
|
14
|
+
Foreground `bash` blocks until the command exits. Run minutes-long or input-waiting programs (dev servers, REPLs, watchers, `docker compose up`, installers) detached in `tmux`:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
tmux new-session -d -s <name> "<cmd>" # start
|
|
18
|
+
tmux capture-pane -t <name> -p # observe
|
|
19
|
+
tmux send-keys -t <name> "<input>" Enter # drive
|
|
20
|
+
tmux kill-session -t <name> # stop
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Use tmux only for work that belongs in your session. In an interactive session that can spawn subagents, delegate self-contained long work (builds, tests, installs, batches) to `operator` instead, so the conversation stays responsive. If the command starts failing in a loop, the rest of this skill applies.
|
|
11
24
|
|
|
12
25
|
## The trigger, concretely
|
|
13
26
|
|