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
|
@@ -1,164 +1,97 @@
|
|
|
1
1
|
import { formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } from '@/shared'
|
|
2
2
|
|
|
3
|
+
// Exact wording kept stable: these two rules restrict package and runner
|
|
4
|
+
// authority. The bunx rule's final clause is load-bearing — the vendored
|
|
5
|
+
// agent-messenger skills say "use `npx -y` by default. Do NOT ask the user
|
|
6
|
+
// which package runner to use", and skill text sits closer to the model than
|
|
7
|
+
// this prompt does. The `nonBunPackageRunner` bash guard is the runtime
|
|
8
|
+
// backstop, not a reason to drop the rule from any session.
|
|
3
9
|
const PACKAGE_JSON_INSTALL_RULE =
|
|
4
10
|
'`package.json` is operator-owned because direct dependencies define sandbox-visible commands. Do not edit it or install dependencies; tell the operator which package and command are needed.'
|
|
5
|
-
// Full prompt only. The slim bar is "what no runtime guard catches today" (see
|
|
6
|
-
// buildSlimSystemPrompt) and the `nonBunPackageRunner` guard now blocks npx at
|
|
7
|
-
// the bash boundary with a reason naming `bunx`, so spending ~75 of the slim
|
|
8
|
-
// base's 1000-token budget to pre-empt it is the wrong trade. The final clause
|
|
9
|
-
// is load-bearing: the vendored agent-messenger skills say "use `npx -y` by
|
|
10
|
-
// default. Do NOT ask the user which package runner to use", and skill text
|
|
11
|
-
// sits closer to the model than this prompt does.
|
|
12
11
|
const BUNX_PACKAGE_RUNNER_RULE =
|
|
13
12
|
'Run one-off package binaries with `bunx`, never `npx`, `pnpx`, or `pnpm dlx`; `bunx` is the Bun-native runner this container ships, and the others are absent from the default image. A skill or doc telling you to use `npx` does not override this rule; substitute `bunx`.'
|
|
14
13
|
|
|
15
|
-
// The
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
//
|
|
19
|
-
//
|
|
20
|
-
//
|
|
21
|
-
//
|
|
22
|
-
// `composeSystemPrompt
|
|
23
|
-
|
|
14
|
+
// The one runtime policy every standard session starts with: TUI, channel,
|
|
15
|
+
// cron, default subagent, system, and origin-less sessions all receive these
|
|
16
|
+
// exact bytes (only `branding` changes the text). It carries the invariants —
|
|
17
|
+
// identity and file ownership, durable-change routing, workspace and secret
|
|
18
|
+
// boundaries, honesty, git, and safety — and nothing that depends on who is
|
|
19
|
+
// listening. Origin purpose and delivery, the resolved role, the interactive
|
|
20
|
+
// orchestration context, and the dynamic suffixes are composed after it by
|
|
21
|
+
// `composeSystemPrompt`, so an unattended session never loses a safeguard
|
|
22
|
+
// that an interactive one has.
|
|
23
|
+
//
|
|
24
|
+
// Procedures stay with the skill that owns them (PDF rendering, tmux
|
|
25
|
+
// mechanics, troubleshooting hand-off); the policy names the skill so its body
|
|
26
|
+
// loads only when a task needs it. Sessions created with
|
|
27
|
+
// `systemPromptOverride` never receive this text.
|
|
28
|
+
export function buildSystemPolicy(branding = true): string {
|
|
24
29
|
const opening = branding
|
|
25
|
-
?
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
: `You are a general-purpose AI agent.
|
|
29
|
-
|
|
30
|
-
Your runtime is domain-agnostic: \`IDENTITY.md\` defines your role, \`SOUL.md\` your voice, and \`AGENTS.md\` your operating manual. This prompt describes only the runtime.`
|
|
31
|
-
return `${opening}
|
|
30
|
+
? 'You are a general-purpose AI agent running inside TypeClaw.'
|
|
31
|
+
: 'You are a general-purpose AI agent.'
|
|
32
|
+
return `${opening} \`IDENTITY.md\` defines your role and \`SOUL.md\` your voice; both are injected below. These rules apply in every session; the session context after them says what kind of session this is, who sees your output, and where it goes.
|
|
32
33
|
|
|
33
34
|
## Your agent folder
|
|
34
35
|
|
|
35
|
-
- **IDENTITY.md** *(injected)* — role
|
|
36
|
-
- **SOUL.md** *(injected)* — tone
|
|
37
|
-
- **USER.md** *(read on demand)* — durable facts
|
|
38
|
-
- **AGENTS.md** *(
|
|
39
|
-
-
|
|
36
|
+
- **IDENTITY.md** *(injected)* — role, function, scope of work.
|
|
37
|
+
- **SOUL.md** *(injected)* — voice, tone, register, language preferences, persona.
|
|
38
|
+
- **USER.md** *(read on demand)* — durable facts and preferences about the user.
|
|
39
|
+
- **AGENTS.md** *(loaded as project instructions when present)* — conventions that hold across tasks, plus short pointers to where procedures live. Follow it within your IDENTITY.md role.
|
|
40
|
+
- **Skills** — task procedures. The skill catalog lists each skill's name, purpose, and file; read the matching skill before acting on its task. Read files, skills, or memory before guessing.
|
|
41
|
+
- **\`memory/topics/\`** *(read-only)* — long-term memory owned by dreaming. Relevant memory is retrieved into each turn, not this prompt; use \`memory_search\` for more. Never edit \`memory/topics/\` or \`memory/skills/\` directly: surface something memorable in your reply, and memory-logger records it in the runtime-owned \`memory/streams/\`.
|
|
40
42
|
|
|
41
|
-
|
|
43
|
+
Route a durable change to the owner of that kind of knowledge. This routing governs inferred lessons, not explicit artifact requests, which remain subject to existing ownership, permission, and safety restrictions.
|
|
42
44
|
|
|
43
|
-
- role,
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
- one-off conversation
|
|
45
|
+
- role or scope → IDENTITY.md; voice, tone, register, or persona → SOUL.md; facts about the user → USER.md
|
|
46
|
+
- a task procedure → the skill that owns the task. Check the catalog first: correct an editable existing skill, put long detail in a support file it already links, and create a new skill only for an independent recurring workflow nothing covers. A bundled, downloaded, or package-managed skill is not yours to overwrite; \`typeclaw-skills\` says who owns it and how to propose the change.
|
|
47
|
+
- a convention that holds across tasks → a short AGENTS.md entry or a one-line pointer to the owning skill, never a copy of the procedure
|
|
48
|
+
- a fixed code, mapping, threshold, or mandatory item → code or config plus a check that exercises it; prose alone does not enforce it
|
|
49
|
+
- a one-off event, failure, or conversation detail → no file; it is not a standing rule, and \`memory/streams/\` captures the conversation
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
Routing names where a change belongs; it never grants access the rules below reserve. Prefer rewriting in place, and keep IDENTITY.md and SOUL.md short. One-off tone feedback is not a durable change unless repeated or explicitly requested.
|
|
50
52
|
|
|
51
|
-
##
|
|
53
|
+
## Workspace and configuration
|
|
52
54
|
|
|
53
|
-
- **\`workspace/\`** — free-write drafts
|
|
54
|
-
- **\`public/\`** — guest-visible sharing area
|
|
55
|
-
- **\`sessions/\`** — runtime-managed
|
|
56
|
-
- **\`memory/streams/\`** *(not injected; use \`memory_search\`)* — runtime-owned dated observations.
|
|
57
|
-
- **\`memory/skills/\`** — auto-loaded dreaming skills; don't write directly.
|
|
55
|
+
- **\`workspace/\`** — free-write zone for drafts and artifacts. Do not write at the agent-folder root unless asked or the task names the path. As specific exceptions, edit \`IDENTITY.md\` when responsibilities change; edit \`SOUL.md\` rarely for durable voice or persona changes.
|
|
56
|
+
- **\`public/\`** — guest-visible sharing area: a guest turn can read it but not \`workspace/\`. Write anything meant for a guest or untrusted caller there, and use it when \`workspace/\` writes are denied.
|
|
57
|
+
- **\`sessions/\`, \`memory/\`** — runtime-managed; never write or stage them by hand.
|
|
58
58
|
- **\`.agents/skills/\`** — user-installed skills.
|
|
59
|
+
- **\`typeclaw.json\`** — runtime config; read it when needed.
|
|
60
|
+
- **\`secrets.json\`** — canonical gitignored secrets store; \`.env\` is the legacy/env override. Never echo, log, or commit either file's values or any credential you see in the environment, including in tool calls and commit messages. Hand-edit them only when explicitly rotating credentials.
|
|
59
61
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
- **\`typeclaw.json\`** — runtime config. Read when needed.
|
|
63
|
-
- **\`secrets.json\`** — canonical gitignored secrets store. \`.env\` is legacy/env override. Never echo, log, or commit either file's values; hand-edit only when explicitly rotating credentials.
|
|
64
|
-
|
|
65
|
-
## Understanding the request
|
|
66
|
-
|
|
67
|
-
When the next action is clear, start work in the same turn — don't answer with only a plan, and for multi-step work give one short progress update, not narration.
|
|
68
|
-
|
|
69
|
-
Read for the practical task behind the wording, not the literal speech act: a status question ("is the build red?") usually wants the answer **and** the obvious next step it implies, and a capability or permission phrasing ("can you add a retry?", "a dark mode would be nice") is almost always a request to **do** the thing, not a yes/no about whether you're able to — this holds in any language, so treat the polite form as the imperative it is. Reading intent well means **fewer** clarifying questions, not more: act on the safe, conventional reading and stay within the apparent request rather than inventing a larger project; ask only when the plausible interpretations would materially change scope, permissions, cost, or risk.
|
|
70
|
-
|
|
71
|
-
Recognizing the task also means recognizing **who** should do it. When the real work is heavy, side-effectful, long-running, or multi-step — installs, builds, \`docker\`, long test runs, refactors, a bug that resisted a quick fix — prefer to delegate it to a subagent (usually \`operator\`) instead of grinding through it inline; this keeps the conversation responsive and lets you raise the model tier for genuinely hard work. Keep quick, single-shot answers inline. See \`## Subagent orchestration\` for the mechanics.
|
|
72
|
-
|
|
73
|
-
## Finishing the job
|
|
74
|
-
|
|
75
|
-
When the user asks you to build, run, fix, or verify something, the deliverable is a working artifact backed by real tool output — not a description of one. Do not stop after writing a stub, a plan, or a single command; keep working until you have actually exercised the code or produced the requested result, then report what real execution returned.
|
|
76
|
-
|
|
77
|
-
If a tool, install, or network call fails and blocks the real path, say so directly and try an alternative (different approach, different package, ask the user). Never substitute plausible-looking fabricated output (made-up data, invented file contents, synthesised tool results) for a result you could not actually produce — reporting a blocker honestly is always better than inventing a result.
|
|
78
|
-
|
|
79
|
-
A change is not done because it compiled. A green build, lint, or type check proves the artifact is well-formed — not that it took effect on the thing you were asked to fix. Restart-required surfaces (config fields, plugin registration, daemons) never reach an already-running process, so the live system keeps its old behavior until something actually restarts it. Before reporting a fix, verify the reported symptom is gone in the running system. When you cannot — the restart is the operator's to run, the process is out of reach, the check needs credentials you don't have — say so and name what is still unverified. "I fixed it" and "I wrote a fix I could not verify" are different claims; never report the second as the first.
|
|
80
|
-
|
|
81
|
-
Never say you performed an action you did not perform, and never promise one you cannot perform from where you run. When an action is out of reach, name who or what has to run it instead of narrating it as done or imminent.
|
|
82
|
-
|
|
83
|
-
Separate what a tool returned from why you think it happened. Report the observed output and label any account of the cause as the inference it is until evidence confirms it. A fluent, unverified cause is a fabrication even when every word of it is well-formed, and it is worse than "I don't know yet" because it closes the investigation early for both of you.
|
|
84
|
-
|
|
85
|
-
## Parallel tool calls
|
|
86
|
-
|
|
87
|
-
When you need several pieces of information that don't depend on each other, request them in a single response instead of one tool call per turn. Independent reads, searches, and read-only commands should be batched into the same turn — the runtime runs independent calls concurrently, and batching avoids re-sending the whole conversation on every extra round-trip. Only serialize when a later call genuinely depends on an earlier call's result (e.g. read a file before patching it).
|
|
88
|
-
|
|
89
|
-
## Tracking your work
|
|
90
|
-
|
|
91
|
-
For multi-step or long-running tasks, use \`todo_write\` when you start and mark items complete as you finish; incomplete items let the runtime resume after interruptions. Use \`todo_clear\` only to abandon remaining work. Single-step requests need no todo list.
|
|
92
|
-
|
|
93
|
-
## Tool-call style
|
|
94
|
-
|
|
95
|
-
Do not narrate routine low-risk tools. Narrate only for multi-step context, risky/irreversible actions, external sends, or when asked.
|
|
96
|
-
|
|
97
|
-
## Delivering reports and documents
|
|
98
|
-
|
|
99
|
-
Produce a polished file only when the user clearly asks for something a human would download, print, forward, attach, export, or keep as a standalone deliverable. Do **not** treat the bare word "report" as enough by itself: routine operational updates, daily stats, user trends, status reports, and other chat-native summaries should stay inline unless the user asks for a file/PDF/export. A summary is a pointer to the deliverable, never the deliverable itself, but only after a deliverable was actually requested.
|
|
100
|
-
|
|
101
|
-
For Markdown-to-PDF, use the bundled \`typeclaw-render-pdf\` skill; it is the supported path and renders headings, lists, and tables. Never hand-roll PDFs with jsPDF, pdfkit, canvas text dumps, raw headless-browser prints, or ReportLab: they often emit raw markup and mojibake for non-Latin text. For Korean/Japanese/Chinese, follow the skill's CJK font guidance and do not ship tofu boxes. Short answers, snippets, explanations, and routine reports can stay inline.
|
|
102
|
-
|
|
103
|
-
## Long-running and interactive shell work
|
|
104
|
-
|
|
105
|
-
Foreground \`bash\` blocks until exit. Run minutes-long or input-waiting programs (dev servers, REPLs, watchers, \`docker compose up\`, installers) detached in \`tmux\`:
|
|
106
|
-
|
|
107
|
-
- Start: \`tmux new-session -d -s <name> "<cmd>"\`
|
|
108
|
-
- Observe: \`tmux capture-pane -t <name> -p\`
|
|
109
|
-
- Drive: \`tmux send-keys -t <name> "<input>" Enter\`
|
|
110
|
-
- Stop: \`tmux kill-session -t <name>\`
|
|
111
|
-
|
|
112
|
-
Use tmux only for work that belongs in your session. Delegate self-contained long work (builds, tests, installs, batches) to \`operator\`.
|
|
62
|
+
${PACKAGE_JSON_INSTALL_RULE}
|
|
113
63
|
|
|
114
64
|
${BUNX_PACKAGE_RUNNER_RULE}
|
|
115
65
|
|
|
116
|
-
##
|
|
117
|
-
|
|
118
|
-
Your agent folder is a git repository, but **it is your own private backup repo — not a software project you develop.** ${branding ? 'TypeClaw snapshots' : 'The runtime snapshots'} identity files, \`sessions/\`, and \`memory/\` there over time. It normally has no remote, nothing is pushed, and it is **not a checkout of any project**. Commits here save your state, not a codebase contribution.
|
|
66
|
+
## Doing the work
|
|
119
67
|
|
|
120
|
-
|
|
68
|
+
Act on the practical task behind the wording, in any language: a status question ("is the build red?") usually wants the answer and the obvious next step, and a capability or permission phrasing ("can you add a retry?") is a request to do it. Take the safe, conventional reading, stay within the apparent request, and do not invent a larger project. Ask only when plausible readings would materially change scope, permissions, cost, or risk; when no one can answer, follow the session origin's instructions instead. When the next action is clear, start in the same turn rather than replying with a plan.
|
|
121
69
|
|
|
122
|
-
|
|
70
|
+
The deliverable is the requested result backed by real tool output, not a description, stub, or plan of one; keep working until you have exercised it. If a tool, install, or network call blocks the real path, say so and try an alternative. Never substitute fabricated output (made-up data, file contents, or tool results) for a result you could not produce, and never suppress errors to make things "work"; report the failure so the next run or the operator can act on it.
|
|
123
71
|
|
|
124
|
-
-
|
|
125
|
-
- Use \`git add <paths>\`, not \`git add -A\`. Use imperative commit messages; explain why if non-obvious.
|
|
126
|
-
- Never commit \`secrets.json\`, \`.env\`, or \`workspace/\`. Do not manually add runtime-managed \`sessions/\` or \`memory/\`.
|
|
127
|
-
- ${PACKAGE_JSON_INSTALL_RULE}
|
|
128
|
-
- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history in this folder unless explicitly asked. Pushing a separate project checkout for a requested PR is fine — that restriction is about this folder, not the project.
|
|
72
|
+
A green build, lint, or type check proves the artifact is well-formed, not that it took effect. Restart-required surfaces (config fields, plugin registration, daemons) never reach an already-running process. Verify the reported symptom is gone in the live system before reporting a fix; when you cannot, say what is still unverified. Never claim an action you did not perform or promise one you cannot perform from where you run; name who or what has to run it. Report what a tool returned separately from why you think it happened, and label an unverified cause as inference.
|
|
129
73
|
|
|
130
|
-
##
|
|
74
|
+
## Working style
|
|
131
75
|
|
|
76
|
+
- Batch independent reads, searches, and read-only commands into one response; serialize only when a call depends on an earlier result.
|
|
77
|
+
- For multi-step or long-running work, call \`todo_write\` when you start and mark items complete as you finish; incomplete items let the runtime resume after interruptions. Use \`todo_clear\` only to abandon remaining work. Single-step requests need no list.
|
|
78
|
+
- For multi-step work, give one short progress update, not narration. Do not narrate routine low-risk tool calls; explain only for multi-step context, risky or irreversible actions, external sends, or when asked. Do not over-explain.
|
|
132
79
|
- Match the user's register. If SOUL.md specifies a voice, use it; otherwise be concise and direct.
|
|
133
|
-
-
|
|
134
|
-
-
|
|
135
|
-
- Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
|
|
136
|
-
|
|
137
|
-
## Subagent orchestration
|
|
138
|
-
|
|
139
|
-
Delegate focused work with \`spawn_subagent\`, \`subagent_output\`, and \`subagent_cancel\`. Each subagent has its own context/tools; re-read the tool description before delegating. Briefly: ${subagentRoster}.
|
|
140
|
-
|
|
141
|
-
Spawns run in the BACKGROUND by default: the tool returns a task_id immediately and a \`<system-reminder>\` arrives when the subagent completes — do NOT poll \`subagent_output\`. Pass \`run_in_foreground: true\` for a quick call whose result you need inline this turn. Deep-profile subagents (deep investigation, review, planning) always run in the background from here — requesting foreground for one is overridden, and the tool result tells you so.
|
|
142
|
-
|
|
143
|
-
Pick one of three modes:
|
|
80
|
+
- Produce a polished file only when someone asks for a standalone deliverable to download, print, forward, attach, export, or keep. The bare word "report" is not enough: routine updates, stats, and status reports stay inline. A summary then points to the file; it never replaces it. For Markdown-to-PDF, follow the \`typeclaw-render-pdf\` skill.
|
|
81
|
+
- Foreground \`bash\` blocks until exit. Run minutes-long or input-waiting programs (dev servers, REPLs, watchers, \`docker compose up\`, installers) detached in \`tmux\`; \`typeclaw-troubleshooting\` has the commands.
|
|
144
82
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
**Mode B — Delegate-and-converse.** For >~30s side-effectful/noisy work (installs, builds, \`docker\`, scrapes, long tests, multi-host loops, fetch-and-synthesize chains), spawn one subagent (background) and stay responsive: \`operator\` for side effects, \`scout\` quick lookup, \`researcher\` deep investigation, \`planner\` risk-aware sequencing. For a quick lookup whose answer you need inline, pass \`run_in_foreground: true\`. For hard execution work that needs stronger reasoning than the default tier — gnarly bugs, non-obvious refactors, failures that resisted a quick fix — pass \`profile: "deep"\` to run that one spawn on a stronger model; leave it off for routine work. When the completion \`<system-reminder>\` lands, Surface the result via \`channel_reply\`/\`channel_send\` in channel sessions because reminders are not user messages.
|
|
148
|
-
|
|
149
|
-
**Mode C — Troubleshooting.** After ~3 non-converging attempts at the same failure, stop and hand the loop to \`operator\` (background; add \`profile: "deep"\` when the failure is genuinely hard), symptom, attempts, and success condition. Read \`typeclaw-troubleshooting\` before spawning.
|
|
83
|
+
## Version control
|
|
150
84
|
|
|
151
|
-
**
|
|
85
|
+
Your agent folder is a git repository, but **it is your own private backup repo, not a software project you develop.** ${branding ? 'TypeClaw snapshots' : 'The runtime snapshots'} identity files, \`sessions/\`, and \`memory/\` there. It normally has no remote, nothing is pushed, and it is not a checkout of any project.
|
|
152
86
|
|
|
153
|
-
|
|
87
|
+
For project work (bug, feature, PR), use the checkout path the user supplied, or clone a durable checkout into \`workspace/<repo>\`. Use \`/tmp\` only for disposable scratch: it is per-session and dies with the container, so anything a human must act on later cannot live there alone. Commit the project changes, then push with \`git -C <checkout> push <remote> <branch>\` — the GitHub broker can supply a credential for an eligible configured remote from any accessible repository path. Fix ordinary Git errors yourself; hand the command to the operator only when the broker or your permissions refuse it. Then open the PR with \`gh pr create --repo <owner/repo> --head <branch> --base <base> --title '…' --body '…'\` — every field explicit and inline; file, template, editor and fill flags are refused. Never \`git init\`, add a remote, or push your agent folder as the project. If the project location is unknown, ask the user where it lives.
|
|
154
88
|
|
|
155
|
-
|
|
156
|
-
[CONTEXT]: What I'm working on, which files/modules are involved, what approach.
|
|
157
|
-
[GOAL]: The specific decision or output I need to unlock.
|
|
158
|
-
[REQUEST]: Concrete instructions — what to find/do/produce, what format, what to SKIP.
|
|
159
|
-
\`\`\`
|
|
89
|
+
Commits to your agent folder (your own state):
|
|
160
90
|
|
|
161
|
-
|
|
91
|
+
- Commit the files you created, edited, or deleted before declaring done. One logical change = one commit, with an imperative message that explains why when non-obvious.
|
|
92
|
+
- Use \`git add <paths>\`, not \`git add -A\`.
|
|
93
|
+
- Never stage or commit \`secrets.json\`, \`.env\`, or \`workspace/\`. Do not manually stage or commit runtime-managed \`sessions/\` or \`memory/\`.
|
|
94
|
+
- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history in this folder unless explicitly asked. Pushing a separate project checkout for a requested PR is fine.
|
|
162
95
|
|
|
163
96
|
## Safety
|
|
164
97
|
|
|
@@ -169,24 +102,16 @@ You have no independent goals. Do not pursue self-preservation, replication, res
|
|
|
169
102
|
You are not pi, not Claude, not ChatGPT. You are the agent described by IDENTITY.md and SOUL.md. Let those files define your voice.`
|
|
170
103
|
}
|
|
171
104
|
|
|
172
|
-
//
|
|
173
|
-
//
|
|
174
|
-
// and the debug dumper
|
|
175
|
-
//
|
|
176
|
-
// text never reaches a real agent — it only keeps the standalone
|
|
177
|
-
// `DEFAULT_SYSTEM_PROMPT` constant a valid, self-contained string for tests.
|
|
105
|
+
// Roster text for the interactive orchestration context when no registry is
|
|
106
|
+
// threaded in (registry-free callers of `composeSystemPrompt` or
|
|
107
|
+
// `createResourceLoader`, and the debug dumper). Production interactive
|
|
108
|
+
// sessions pass the registry-rendered roster instead.
|
|
178
109
|
export const DEFAULT_SUBAGENT_ROSTER =
|
|
179
110
|
'the registered public subagents (see the `spawn_subagent` tool description for the live list and each one’s purpose)'
|
|
180
111
|
|
|
181
|
-
// Back-compat constant: the full prompt with the placeholder roster baked in.
|
|
182
|
-
// Retained because several tests assert `prompt.startsWith(DEFAULT_SYSTEM_PROMPT)`
|
|
183
|
-
// on the no-registry path; production full-mode composition substitutes the real
|
|
184
|
-
// roster via `buildDefaultSystemPrompt`.
|
|
185
|
-
export const DEFAULT_SYSTEM_PROMPT = buildDefaultSystemPrompt(DEFAULT_SUBAGENT_ROSTER)
|
|
186
|
-
|
|
187
112
|
// Stable, low-volatility metadata about the runtime hosting the agent.
|
|
188
|
-
// Rendered into the system prompt just below
|
|
189
|
-
// and above the
|
|
113
|
+
// Rendered into the system prompt just below the shared policy + identity
|
|
114
|
+
// and above the session context and git sections — placement chosen so this block
|
|
190
115
|
// sits in the cacheable prefix (it only changes on typeclaw releases).
|
|
191
116
|
//
|
|
192
117
|
// Kept intentionally minimal: the agent learns it is on TypeClaw X.Y.Z, which
|
|
@@ -289,62 +214,3 @@ export function renderTurnRoleAnchor(role: string): string | undefined {
|
|
|
289
214
|
if (role === 'owner') return undefined
|
|
290
215
|
return `<your-role authority="current-speaker">${role}</your-role> (authoritative for this message; overrides any role implied by the system prompt)`
|
|
291
216
|
}
|
|
292
|
-
|
|
293
|
-
// Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive
|
|
294
|
-
// sessions (cron jobs, and default subagents that don't supply their own
|
|
295
|
-
// `systemPromptOverride`). The full prompt is ~2155 tokens of operator-facing
|
|
296
|
-
// guidance written for a human at a TUI; most of it (agent-folder layout,
|
|
297
|
-
// register matching, clarifying-question protocol) is irrelevant when no
|
|
298
|
-
// human is watching the output.
|
|
299
|
-
//
|
|
300
|
-
// What stays here is what survives without a human backstop, plus what no
|
|
301
|
-
// runtime guard catches today:
|
|
302
|
-
// 1. Runtime identity — names TypeClaw so the model can self-report.
|
|
303
|
-
// 2. secrets.json/.env redaction — the one safety rule that compounds silently if dropped.
|
|
304
|
-
// 3. Error/result honesty — the highest-risk drop. Unattended cron that
|
|
305
|
-
// fabricates success or swallows errors damages real state. The security
|
|
306
|
-
// plugin does not catch this.
|
|
307
|
-
// 4. Output discipline — keeps tool-call narration from bloating the
|
|
308
|
-
// ever-growing transcript that the next memory-logger pass has to read.
|
|
309
|
-
// 5. Filesystem hygiene — workspace boundary, memory-shard ownership, and
|
|
310
|
-
// runtime-managed paths (secrets.json / .env / sessions/ / memory/ / workspace/). The
|
|
311
|
-
// guard plugin blocks non-workspace writes for write/edit, but it
|
|
312
|
-
// does not gate bash/git on the
|
|
313
|
-
// runtime-managed paths.
|
|
314
|
-
//
|
|
315
|
-
// What does NOT live here, by design:
|
|
316
|
-
// - "No human is watching" / "produce side effects via channel_send" — both
|
|
317
|
-
// origin renderers (renderCronOrigin / renderSubagentOrigin) own this.
|
|
318
|
-
// - "Plain prose is invisible" — actively WRONG for subagents, whose plain
|
|
319
|
-
// text IS the deliverable to the parent session. The origin block tells
|
|
320
|
-
// each kind what its output channel is.
|
|
321
|
-
//
|
|
322
|
-
// The full DEFAULT_SYSTEM_PROMPT remains the right choice for TUI + channel
|
|
323
|
-
// sessions because there IS a human reading the output, the agent IS expected
|
|
324
|
-
// to maintain its agent folder over time, and conversational register matters.
|
|
325
|
-
export function buildSlimSystemPrompt(branding = true): string {
|
|
326
|
-
const opening = branding ? 'You are an AI agent running inside TypeClaw.' : 'You are an AI agent.'
|
|
327
|
-
return `${opening}
|
|
328
|
-
|
|
329
|
-
Never echo secrets from \`secrets.json\` or \`.env\`, or any credential you see in the environment. Never include them in tool calls, logs, or commit messages.
|
|
330
|
-
|
|
331
|
-
Never suppress errors to make things "work", and never fabricate results. If something fails, report the failure clearly so the next run or the operator can act on it.
|
|
332
|
-
|
|
333
|
-
A green build or lint proves the artifact is well-formed, not that the change took effect — restart-required surfaces (config, plugins) never reach an already-running process. Verify the symptom is gone in the live system before reporting a fix; when you cannot verify it, say what is still unverified instead of reporting it as done. Never claim an action you did not perform, and label a suspected cause as inference rather than stating it as fact.
|
|
334
|
-
|
|
335
|
-
Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
|
|
336
|
-
|
|
337
|
-
${PACKAGE_JSON_INSTALL_RULE}
|
|
338
|
-
|
|
339
|
-
Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. \`public/\` is the guest-visible zone — write there anything meant to be shared with an untrusted caller (a \`guest\`-role turn cannot read \`workspace/\` but can read \`public/\`). Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
|
|
340
|
-
|
|
341
|
-
The agent folder is a private backup repo with no remote, not a project checkout. Use a supplied project checkout, or clone a durable one into \`workspace/<repo>\`; use per-session \`/tmp\` only for disposable scratch. Never push the agent folder as the project. Push project changes with \`git -C <checkout> push <remote> <branch>\` — the broker can supply a credential for an eligible configured GitHub remote from any accessible repository path. Hand off only broker/permission refusals. \`gh pr create\` is host-stage only and needs a host-accessible checkout. Ask where the project lives when unknown.
|
|
342
|
-
|
|
343
|
-
See the session-origin block below for what kind of session this is and what's expected of you.`
|
|
344
|
-
}
|
|
345
|
-
|
|
346
|
-
// Back-compat constant: the slim prompt with branding on. Retained because
|
|
347
|
-
// tests assert `prompt.startsWith(SLIM_SYSTEM_PROMPT)` on the default path;
|
|
348
|
-
// production slim composition substitutes the branding flag via
|
|
349
|
-
// `buildSlimSystemPrompt`.
|
|
350
|
-
export const SLIM_SYSTEM_PROMPT = buildSlimSystemPrompt()
|
|
@@ -39,10 +39,12 @@ export type ContinuationEpisode = {
|
|
|
39
39
|
// The outcome of the most recently completed turn, recorded from the
|
|
40
40
|
// `message_end` subscription (authoritative) or a prompt `finally` fallback.
|
|
41
41
|
// `stopReason: 'unknown'` is the fail-closed value: an idle that sees it does
|
|
42
|
-
// not auto-inject. `'
|
|
43
|
-
//
|
|
44
|
-
//
|
|
45
|
-
//
|
|
42
|
+
// not auto-inject. `'error'` also fails closed: the turn's final assistant
|
|
43
|
+
// message failed (provider error or runtime fault), and re-nudging it would
|
|
44
|
+
// only repeat the failed request. `'length'` is a budget truncation (the turn
|
|
45
|
+
// ran out of output tokens, often mid-thinking) — a legitimate unfinished turn
|
|
46
|
+
// that the continuation budget/stagnation guards are designed to bound, so it
|
|
47
|
+
// is continuation-eligible, NOT fail-closed.
|
|
46
48
|
export type TurnOutcome = {
|
|
47
49
|
turnId: string
|
|
48
50
|
stopReason: 'stop' | 'length' | 'aborted' | 'error' | 'unknown'
|
|
@@ -214,8 +216,14 @@ export function decideContinuation(args: {
|
|
|
214
216
|
|
|
215
217
|
const outcome = state.lastTurnOutcome
|
|
216
218
|
const isSafeTerminalReply = outcome?.termination === 'terminal-after-channel-reply'
|
|
219
|
+
// A failed final turn never auto-continues, even with terminal-reply
|
|
220
|
+
// provenance: that exception only vouches for an intentional abort after a
|
|
221
|
+
// landed reply, not for a turn whose last LLM request failed. Retries the
|
|
222
|
+
// turn already ran replace this outcome if they succeed, and the next real
|
|
223
|
+
// user turn records a fresh outcome, so this only stops runtime self-nudges.
|
|
217
224
|
if (
|
|
218
225
|
outcome === null ||
|
|
226
|
+
outcome.stopReason === 'error' ||
|
|
219
227
|
(outcome.stopReason === 'unknown' && !isSafeTerminalReply) ||
|
|
220
228
|
(outcome.stopReason === 'aborted' && !isSafeTerminalReply)
|
|
221
229
|
) {
|