typeclaw 0.48.13 → 0.50.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/dist/types/agent/attention-escalation.d.ts +18 -0
- package/dist/types/agent/auth.d.ts +7 -0
- package/dist/types/agent/compaction.d.ts +8 -0
- package/dist/types/agent/git-nudge.d.ts +6 -0
- package/dist/types/agent/guard-types.d.ts +25 -0
- package/dist/types/agent/guards.d.ts +7 -0
- package/dist/types/agent/idle-compaction.d.ts +7 -0
- package/dist/types/agent/index.d.ts +163 -0
- package/dist/types/agent/live-subagents.d.ts +113 -0
- package/dist/types/agent/llm-replay-sanitizer.d.ts +11 -0
- package/dist/types/agent/loop-guard.d.ts +67 -0
- package/dist/types/agent/model-fallback.d.ts +29 -0
- package/dist/types/agent/model-overrides.d.ts +8 -0
- package/dist/types/agent/multimodal/index.d.ts +2 -0
- package/dist/types/agent/multimodal/look-at.d.ts +60 -0
- package/dist/types/agent/multimodal/looker.d.ts +61 -0
- package/dist/types/agent/multimodal/read-redirect.d.ts +6 -0
- package/dist/types/agent/network/response-body.d.ts +1 -0
- package/dist/types/agent/network/safe-http.d.ts +46 -0
- package/dist/types/agent/plugin-tools.d.ts +129 -0
- package/dist/types/agent/proactive-next-step-nudge.d.ts +2 -0
- package/dist/types/agent/prompt-cache-key.d.ts +3 -0
- package/dist/types/agent/provider-error.d.ts +23 -0
- package/dist/types/agent/reload-tool.d.ts +10 -0
- package/dist/types/agent/restart/index.d.ts +31 -0
- package/dist/types/agent/restart-handoff/index.d.ts +32 -0
- package/dist/types/agent/restart-handoff/paths.d.ts +1 -0
- package/dist/types/agent/retry-same-ref.d.ts +41 -0
- package/dist/types/agent/reviewer-activity.d.ts +3 -0
- package/dist/types/agent/reviewer-bash-policy.d.ts +8 -0
- package/dist/types/agent/self.d.ts +1 -0
- package/dist/types/agent/session-meta.d.ts +28 -0
- package/dist/types/agent/session-origin.d.ts +65 -0
- package/dist/types/agent/subagent-cache-keepalive.d.ts +38 -0
- package/dist/types/agent/subagent-completion-reminder.d.ts +29 -0
- package/dist/types/agent/subagent-drain.d.ts +25 -0
- package/dist/types/agent/subagent-session.d.ts +3 -0
- package/dist/types/agent/subagents.d.ts +153 -0
- package/dist/types/agent/system-prompt.d.ts +7 -0
- package/dist/types/agent/throttle-circuit.d.ts +25 -0
- package/dist/types/agent/todo/continuation-policy.d.ts +54 -0
- package/dist/types/agent/todo/continuation-state.d.ts +11 -0
- package/dist/types/agent/todo/continuation-wiring.d.ts +32 -0
- package/dist/types/agent/todo/continuation.d.ts +21 -0
- package/dist/types/agent/todo/scope.d.ts +6 -0
- package/dist/types/agent/todo/store.d.ts +16 -0
- package/dist/types/agent/tool-error-remediation.d.ts +1 -0
- package/dist/types/agent/tool-file-safety.d.ts +78 -0
- package/dist/types/agent/tool-not-found-nudge.d.ts +9 -0
- package/dist/types/agent/tool-result-budget.d.ts +15 -0
- package/dist/types/agent/tools/channel-disengage.d.ts +18 -0
- package/dist/types/agent/tools/channel-edit.d.ts +19 -0
- package/dist/types/agent/tools/channel-fetch-attachment.d.ts +36 -0
- package/dist/types/agent/tools/channel-handoff.d.ts +13 -0
- package/dist/types/agent/tools/channel-history-render.d.ts +3 -0
- package/dist/types/agent/tools/channel-history.d.ts +25 -0
- package/dist/types/agent/tools/channel-log.d.ts +5 -0
- package/dist/types/agent/tools/channel-react.d.ts +23 -0
- package/dist/types/agent/tools/channel-read.d.ts +27 -0
- package/dist/types/agent/tools/channel-reply.d.ts +47 -0
- package/dist/types/agent/tools/channel-send.d.ts +42 -0
- package/dist/types/agent/tools/channel-session-search.d.ts +10 -0
- package/dist/types/agent/tools/curl-impersonate.d.ts +37 -0
- package/dist/types/agent/tools/ddg.d.ts +18 -0
- package/dist/types/agent/tools/grant-role.d.ts +25 -0
- package/dist/types/agent/tools/keyed-semaphore.d.ts +10 -0
- package/dist/types/agent/tools/post-github-review.d.ts +38 -0
- package/dist/types/agent/tools/restart.d.ts +25 -0
- package/dist/types/agent/tools/runtime-notice.d.ts +3 -0
- package/dist/types/agent/tools/search-retry.d.ts +16 -0
- package/dist/types/agent/tools/skip-response.d.ts +17 -0
- package/dist/types/agent/tools/spawn-subagent.d.ts +77 -0
- package/dist/types/agent/tools/stream-snapshot.d.ts +23 -0
- package/dist/types/agent/tools/subagent-access.d.ts +20 -0
- package/dist/types/agent/tools/subagent-cancel.d.ts +23 -0
- package/dist/types/agent/tools/subagent-output.d.ts +50 -0
- package/dist/types/agent/tools/todo/index.d.ts +14 -0
- package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +29 -0
- package/dist/types/agent/tools/webfetch/fetch.d.ts +26 -0
- package/dist/types/agent/tools/webfetch/html-lexical.d.ts +27 -0
- package/dist/types/agent/tools/webfetch/index.d.ts +1 -0
- package/dist/types/agent/tools/webfetch/inline-style-visibility.d.ts +3 -0
- package/dist/types/agent/tools/webfetch/strategies/grep.d.ts +11 -0
- package/dist/types/agent/tools/webfetch/strategies/jq.d.ts +4 -0
- package/dist/types/agent/tools/webfetch/strategies/raw.d.ts +1 -0
- package/dist/types/agent/tools/webfetch/strategies/readability.d.ts +16 -0
- package/dist/types/agent/tools/webfetch/strategies/selector.d.ts +4 -0
- package/dist/types/agent/tools/webfetch/strategies/snapshot.d.ts +1 -0
- package/dist/types/agent/tools/webfetch/tool.d.ts +15 -0
- package/dist/types/agent/tools/webfetch/types.d.ts +32 -0
- package/dist/types/agent/tools/websearch.d.ts +17 -0
- package/dist/types/agent/tools/wikipedia.d.ts +7 -0
- package/dist/types/agent/tools-without-local-file-operands.d.ts +1 -0
- package/dist/types/agent/turn-runner.d.ts +36 -0
- package/dist/types/agent-messenger/config-dir.d.ts +19 -0
- package/dist/types/browser/dockerfile.d.ts +2 -0
- package/dist/types/browser/registry.d.ts +49 -0
- package/dist/types/bundled-plugins/bun-hygiene/policy.d.ts +18 -0
- package/dist/types/bundled-plugins/github-cli-auth/git-askpass.d.ts +5 -0
- package/dist/types/bundled-plugins/guard/keys.d.ts +6 -0
- package/dist/types/bundled-plugins/guard/policies/managed-config.d.ts +7 -0
- package/dist/types/bundled-plugins/guard/policies/memory-topics-delete.d.ts +11 -0
- package/dist/types/bundled-plugins/guard/policies/memory-topics-write.d.ts +7 -0
- package/dist/types/bundled-plugins/guard/policies/non-workspace-write.d.ts +9 -0
- package/dist/types/bundled-plugins/guard/policies/skill-authoring.d.ts +20 -0
- package/dist/types/bundled-plugins/guard/policies/uncommitted-changes.d.ts +12 -0
- package/dist/types/bundled-plugins/guard/policy.d.ts +11 -0
- package/dist/types/bundled-plugins/memory/secret-detector.d.ts +11 -0
- package/dist/types/bundled-plugins/memory/slug.d.ts +4 -0
- package/dist/types/bundled-plugins/security/permissions.d.ts +20 -0
- package/dist/types/bundled-plugins/security/policies/private-surface-read.d.ts +34 -0
- package/dist/types/bundled-plugins/security/policies/ssrf.d.ts +18 -0
- package/dist/types/bundled-plugins/security/policy.d.ts +4 -0
- package/dist/types/channels/adapter-namespace.d.ts +2 -0
- package/dist/types/channels/adapters/mention-hints.d.ts +12 -0
- package/dist/types/channels/adapters/webex-id-ref.d.ts +5 -0
- package/dist/types/channels/background-handoff.d.ts +56 -0
- package/dist/types/channels/background-obligations.d.ts +135 -0
- package/dist/types/channels/catch-up.d.ts +26 -0
- package/dist/types/channels/commands.d.ts +2 -0
- package/dist/types/channels/completion-claim.d.ts +20 -0
- package/dist/types/channels/continuation-willingness.d.ts +1 -0
- package/dist/types/channels/continuity-types.d.ts +75 -0
- package/dist/types/channels/describe-error.d.ts +1 -0
- package/dist/types/channels/engagement.d.ts +34 -0
- package/dist/types/channels/github-false-receipt.d.ts +20 -0
- package/dist/types/channels/github-repo.d.ts +2 -0
- package/dist/types/channels/github-rereview-guard.d.ts +24 -0
- package/dist/types/channels/github-review-check.d.ts +135 -0
- package/dist/types/channels/github-review-claim.d.ts +3 -0
- package/dist/types/channels/github-review-turn-ledger.d.ts +71 -0
- package/dist/types/channels/github-review-verdict-coordinator.d.ts +117 -0
- package/dist/types/channels/github-token-bridge.d.ts +20 -0
- package/dist/types/channels/github-verdict-activity.d.ts +12 -0
- package/dist/types/channels/inbound-journal.d.ts +272 -0
- package/dist/types/channels/last-alive.d.ts +3 -0
- package/dist/types/channels/membership-cache.d.ts +27 -0
- package/dist/types/channels/membership.d.ts +21 -0
- package/dist/types/channels/outbound-flood-filter.d.ts +7 -0
- package/dist/types/channels/participants.d.ts +4 -0
- package/dist/types/channels/persistence.d.ts +32 -0
- package/dist/types/channels/recovery-notice.d.ts +26 -0
- package/dist/types/channels/recovery-outbox.d.ts +58 -0
- package/dist/types/channels/router.d.ts +798 -0
- package/dist/types/channels/schema.d.ts +501 -0
- package/dist/types/channels/session-handoff.d.ts +58 -0
- package/dist/types/channels/session-search.d.ts +29 -0
- package/dist/types/channels/types.d.ts +414 -0
- package/dist/types/channels/waiting-reactions.d.ts +25 -0
- package/dist/types/cli/builtins.d.ts +2 -0
- package/dist/types/cli/command-meta.d.ts +9 -0
- package/dist/types/coding-agent/broker-body.d.ts +7 -0
- package/dist/types/coding-agent/broker.d.ts +22 -0
- package/dist/types/coding-agent/claude.d.ts +22 -0
- package/dist/types/coding-agent/codex.d.ts +19 -0
- package/dist/types/coding-agent/index.d.ts +71 -0
- package/dist/types/coding-agent/omo-state.d.ts +2 -0
- package/dist/types/coding-agent/omo-stream.d.ts +22 -0
- package/dist/types/coding-agent/omo.d.ts +133 -0
- package/dist/types/coding-agent/runner.d.ts +35 -0
- package/dist/types/coding-agent/tool.d.ts +27 -0
- package/dist/types/coding-agent/worktree.d.ts +22 -0
- package/dist/types/commands/index.d.ts +45 -0
- package/dist/types/config/config.d.ts +814 -0
- package/dist/types/config/index.d.ts +3 -0
- package/dist/types/config/model-overrides.d.ts +3 -0
- package/dist/types/config/providers.d.ts +1456 -0
- package/dist/types/config/reloadable.d.ts +9 -0
- package/dist/types/container/agent-operation-lock.d.ts +31 -0
- package/dist/types/container/build-cache.d.ts +39 -0
- package/dist/types/container/compose-project.d.ts +1 -0
- package/dist/types/container/controller.d.ts +25 -0
- package/dist/types/container/docker-app.d.ts +23 -0
- package/dist/types/container/exit-reason.d.ts +10 -0
- package/dist/types/container/index.d.ts +14 -0
- package/dist/types/container/log-archive.d.ts +68 -0
- package/dist/types/container/log-colors.d.ts +3 -0
- package/dist/types/container/log-timestamps.d.ts +9 -0
- package/dist/types/container/logs.d.ts +37 -0
- package/dist/types/container/memory-limit.d.ts +13 -0
- package/dist/types/container/memory-oversubscription.d.ts +20 -0
- package/dist/types/container/oom-events.d.ts +18 -0
- package/dist/types/container/port.d.ts +18 -0
- package/dist/types/container/require-running.d.ts +16 -0
- package/dist/types/container/restart.d.ts +32 -0
- package/dist/types/container/shared.d.ts +93 -0
- package/dist/types/container/shell.d.ts +35 -0
- package/dist/types/container/start.d.ts +144 -0
- package/dist/types/container/stats.d.ts +31 -0
- package/dist/types/container/status.d.ts +25 -0
- package/dist/types/container/stop.d.ts +24 -0
- package/dist/types/container/tool-oom-priority.d.ts +4 -0
- package/dist/types/container/verify-running.d.ts +49 -0
- package/dist/types/cron/consumer.d.ts +42 -0
- package/dist/types/cron/count-state.d.ts +24 -0
- package/dist/types/cron/index.d.ts +21 -0
- package/dist/types/cron/list.d.ts +33 -0
- package/dist/types/cron/reloadable.d.ts +11 -0
- package/dist/types/cron/scheduler.d.ts +51 -0
- package/dist/types/cron/schema.d.ts +108 -0
- package/dist/types/dependencies/bin-resolver.d.ts +28 -0
- package/dist/types/dependencies/bins.d.ts +22 -0
- package/dist/types/dependencies/index.d.ts +2 -0
- package/dist/types/git/bound-gc-config.d.ts +4 -0
- package/dist/types/git/hookless.d.ts +1 -0
- package/dist/types/git/reconcile-ignored.d.ts +13 -0
- package/dist/types/git/resolve-agent-git.d.ts +8 -0
- package/dist/types/git/resolve-identity.d.ts +10 -0
- package/dist/types/git/run.d.ts +24 -0
- package/dist/types/git/system-commit.d.ts +2 -0
- package/dist/types/hostd/client.d.ts +13 -0
- package/dist/types/hostd/models.d.ts +1 -0
- package/dist/types/hostd/paths.d.ts +17 -0
- package/dist/types/hostd/protocol.d.ts +93 -0
- package/dist/types/hostd/spawn.d.ts +17 -0
- package/dist/types/hostd/version.d.ts +18 -0
- package/dist/types/init/auto-upgrade.d.ts +41 -0
- package/dist/types/init/cli-version.d.ts +7 -0
- package/dist/types/init/dockerfile.d.ts +34 -0
- package/dist/types/init/ensure-deps.d.ts +17 -0
- package/dist/types/init/env-file.d.ts +3 -0
- package/dist/types/init/gitignore.d.ts +5 -0
- package/dist/types/init/local-source-stamp.d.ts +3 -0
- package/dist/types/init/packagejson.d.ts +7 -0
- package/dist/types/init/paths.d.ts +3 -0
- package/dist/types/init/reconcile-plugin-deps.d.ts +13 -0
- package/dist/types/init/run-bun-install.d.ts +16 -0
- package/dist/types/init/windows-dev-link.d.ts +8 -0
- package/dist/types/mcp/catalog.d.ts +7 -0
- package/dist/types/mcp/client.d.ts +58 -0
- package/dist/types/mcp/manager.d.ts +56 -0
- package/dist/types/mcp/tools.d.ts +23 -0
- package/dist/types/models/embedding-model.d.ts +20 -0
- package/dist/types/models/transformers-version.d.ts +1 -0
- package/dist/types/network/internal-destinations.d.ts +29 -0
- package/dist/types/operations/classify-tool-outcome.d.ts +35 -0
- package/dist/types/operations/incidents.d.ts +47 -0
- package/dist/types/operations/index.d.ts +3 -0
- package/dist/types/operations/remediations.d.ts +25 -0
- package/dist/types/path-safety/real-intended-path.d.ts +9 -0
- package/dist/types/permissions/builtins.d.ts +25 -0
- package/dist/types/permissions/grant.d.ts +19 -0
- package/dist/types/permissions/index.d.ts +6 -0
- package/dist/types/permissions/match-rule.d.ts +28 -0
- package/dist/types/permissions/permissions.d.ts +42 -0
- package/dist/types/permissions/resolve.d.ts +25 -0
- package/dist/types/permissions/schema.d.ts +14 -0
- package/dist/types/plugin/context.d.ts +20 -0
- package/dist/types/plugin/core-tool-names.d.ts +4 -0
- package/dist/types/plugin/define.d.ts +46 -0
- package/dist/types/plugin/hooks.d.ts +52 -0
- package/dist/types/plugin/index.d.ts +11 -0
- package/dist/types/plugin/load-skill.d.ts +14 -0
- package/dist/types/plugin/loader.d.ts +25 -0
- package/dist/types/plugin/manager.d.ts +42 -0
- package/dist/types/plugin/registry.d.ts +73 -0
- package/dist/types/plugin/skills.d.ts +11 -0
- package/dist/types/plugin/types.d.ts +336 -0
- package/dist/types/plugin/zod-introspect.d.ts +11 -0
- package/dist/types/reload/client.d.ts +11 -0
- package/dist/types/reload/docker-exec-client.d.ts +11 -0
- package/dist/types/reload/format.d.ts +2 -0
- package/dist/types/reload/index.d.ts +6 -0
- package/dist/types/reload/recover.d.ts +22 -0
- package/dist/types/reload/registry.d.ts +10 -0
- package/dist/types/reload/types.d.ts +25 -0
- package/dist/types/role-claim/client.d.ts +20 -0
- package/dist/types/role-claim/code.d.ts +4 -0
- package/dist/types/role-claim/controller.d.ts +59 -0
- package/dist/types/role-claim/index.d.ts +6 -0
- package/dist/types/role-claim/match-rule.d.ts +9 -0
- package/dist/types/role-claim/pending.d.ts +35 -0
- package/dist/types/role-claim/reload-after-claim.d.ts +16 -0
- package/dist/types/run/llm-fetch-observer.d.ts +50 -0
- package/dist/types/sandbox/availability.d.ts +21 -0
- package/dist/types/sandbox/build.d.ts +7 -0
- package/dist/types/sandbox/canonical-secrets.d.ts +8 -0
- package/dist/types/sandbox/coding-agent.d.ts +20 -0
- package/dist/types/sandbox/dependency-bins.d.ts +19 -0
- package/dist/types/sandbox/dev-source.d.ts +4 -0
- package/dist/types/sandbox/env-exposure.d.ts +1 -0
- package/dist/types/sandbox/errors.d.ts +20 -0
- package/dist/types/sandbox/hidden-paths.d.ts +11 -0
- package/dist/types/sandbox/index.d.ts +14 -0
- package/dist/types/sandbox/package-install.d.ts +1 -0
- package/dist/types/sandbox/policy.d.ts +71 -0
- package/dist/types/sandbox/privileged-runtime.d.ts +13 -0
- package/dist/types/sandbox/quote.d.ts +2 -0
- package/dist/types/sandbox/runtime-private.d.ts +1 -0
- package/dist/types/sandbox/session-tmp.d.ts +6 -0
- package/dist/types/sandbox/symlinks.d.ts +6 -0
- package/dist/types/sandbox/writable-zones.d.ts +15 -0
- package/dist/types/secrets/coding-agent-auth.d.ts +25 -0
- package/dist/types/secrets/defaults.d.ts +21 -0
- package/dist/types/secrets/export-github-cli-store.d.ts +22 -0
- package/dist/types/secrets/hydrate.d.ts +7 -0
- package/dist/types/secrets/index.d.ts +7 -0
- package/dist/types/secrets/provision-github-cli-store.d.ts +45 -0
- package/dist/types/secrets/refresh-provider-oauth.d.ts +22 -0
- package/dist/types/secrets/resolve.d.ts +14 -0
- package/dist/types/secrets/schema.d.ts +840 -0
- package/dist/types/secrets/storage.d.ts +56 -0
- package/dist/types/shared/host-locale.d.ts +1 -0
- package/dist/types/shared/index.d.ts +5 -0
- package/dist/types/shared/local-time.d.ts +4 -0
- package/dist/types/shared/platform.d.ts +2 -0
- package/dist/types/shared/protocol.d.ts +424 -0
- package/dist/types/shared/style-text.d.ts +3 -0
- package/dist/types/shared/wsl.d.ts +17 -0
- package/dist/types/stream/broker.d.ts +2 -0
- package/dist/types/stream/index.d.ts +2 -0
- package/dist/types/stream/types.d.ts +71 -0
- package/package.json +13 -6
- package/scripts/build-plugin-types.ts +105 -0
- package/scripts/check-plugin-sdk.ts +111 -0
- package/scripts/dump-system-prompt.ts +52 -110
- package/scripts/require-parallel.ts +5 -32
- package/src/agent/guard-types.ts +3 -0
- package/src/agent/guards.ts +4 -0
- package/src/agent/idle-compaction.ts +174 -0
- package/src/agent/index.ts +210 -80
- package/src/agent/live-sessions.ts +2 -2
- package/src/agent/live-subagents.ts +20 -0
- package/src/agent/multimodal/look-at.ts +22 -9
- package/src/agent/plugin-tools.ts +66 -12
- 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/reviewer-bash-policy.ts +41 -1
- package/src/agent/session-origin.ts +58 -9
- package/src/agent/subagent-cache-keepalive.ts +198 -0
- package/src/agent/subagent-session.ts +6 -0
- package/src/agent/subagents.ts +59 -9
- package/src/agent/system-prompt.ts +68 -202
- package/src/agent/todo/continuation-policy.ts +12 -4
- package/src/agent/tool-file-safety.ts +119 -15
- package/src/agent/tool-not-found-nudge.ts +1 -1
- package/src/agent/tools/channel-edit.ts +20 -10
- package/src/agent/tools/channel-fetch-attachment.ts +12 -5
- package/src/agent/tools/channel-handoff.ts +72 -0
- package/src/agent/tools/channel-history-render.ts +2 -1
- package/src/agent/tools/channel-read.ts +57 -10
- package/src/agent/tools/channel-reply.ts +55 -30
- package/src/agent/tools/channel-send.ts +69 -19
- package/src/agent/tools/channel-session-search.ts +35 -0
- package/src/agent/tools/curl-impersonate.ts +22 -6
- package/src/agent/tools/ddg.ts +13 -5
- 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 +190 -23
- package/src/agent/tools/stream-snapshot.ts +15 -2
- package/src/agent/tools/subagent-access.ts +11 -4
- package/src/agent/tools/subagent-output.ts +8 -0
- package/src/browser/bsk-shim.mjs +74 -0
- package/src/browser/dockerfile.ts +84 -0
- package/src/browser/egress.ts +104 -0
- package/src/browser/managed-browser.ts +205 -0
- package/src/browser/registry.ts +110 -0
- package/src/browser/relay.ts +231 -0
- package/src/browser/sandbox-entry.ts +167 -0
- package/src/bundled-plugins/agent-browser/index.ts +2 -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/browser-agent/browser-agent.ts +89 -0
- package/src/bundled-plugins/browser-agent/index.ts +12 -0
- package/src/bundled-plugins/doc-render/index.ts +0 -10
- package/src/bundled-plugins/doc-render/render.ts +83 -111
- package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +152 -257
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +38 -2
- package/src/bundled-plugins/github-cli-auth/git-auth-diagnostic.ts +95 -0
- package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
- package/src/bundled-plugins/github-cli-auth/index.ts +158 -70
- 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/managed-browser/index.ts +74 -0
- package/src/bundled-plugins/managed-browser/skills/browser-use/browser-use/SKILL.md +27 -0
- package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +28 -0
- package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +40 -0
- package/src/bundled-plugins/operator/operator.ts +15 -4
- package/src/bundled-plugins/qa/index.ts +11 -0
- package/src/bundled-plugins/qa/qa.ts +160 -0
- package/src/bundled-plugins/qa/skills/qa-cli.ts +50 -0
- package/src/bundled-plugins/qa/skills/qa-general.ts +30 -0
- package/src/bundled-plugins/qa/skills/qa-http.ts +39 -0
- package/src/bundled-plugins/qa/skills/qa-pr.ts +51 -0
- package/src/bundled-plugins/qa/skills/qa-web.ts +49 -0
- package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
- package/src/bundled-plugins/security/index.ts +103 -36
- package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
- package/src/channels/adapter-namespace.ts +13 -0
- package/src/channels/adapters/discord-bot-reactions.ts +18 -0
- package/src/channels/adapters/discord-bot.ts +219 -72
- 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 +267 -19
- package/src/channels/adapters/github/last-alive.ts +15 -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-attachment-download.ts +14 -3
- package/src/channels/adapters/slack-bot-author-resolver.ts +4 -3
- package/src/channels/adapters/slack-bot-channel-resolver.ts +9 -6
- package/src/channels/adapters/slack-bot-classify.ts +19 -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-slash-commands.ts +3 -1
- package/src/channels/adapters/slack-bot.ts +424 -124
- package/src/channels/adapters/slack-classify.ts +26 -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/catch-up.ts +137 -0
- package/src/channels/continuation-willingness.ts +2 -2
- package/src/channels/continuity-types.ts +272 -0
- package/src/channels/engagement.ts +17 -1
- package/src/channels/github-false-receipt.ts +3 -3
- package/src/channels/github-rereview-guard.ts +9 -5
- 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 +35 -5
- package/src/channels/inbound-journal.ts +1738 -0
- package/src/channels/index.ts +6 -1
- package/src/channels/last-alive.ts +34 -0
- package/src/channels/manager.ts +25 -8
- 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 +2951 -736
- package/src/channels/schema.ts +8 -1
- package/src/channels/session-handoff.fixture.ts +144 -0
- package/src/channels/session-handoff.ts +175 -0
- package/src/channels/session-search.ts +71 -0
- package/src/channels/subagent-completion-bridge.ts +17 -14
- package/src/channels/types.ts +133 -18
- package/src/channels/waiting-reactions.ts +664 -0
- package/src/cli/channel.ts +2 -3
- package/src/cli/compose.ts +7 -4
- package/src/cli/hostd.ts +49 -3
- package/src/cli/init.ts +2 -3
- package/src/cli/inspect.ts +11 -14
- package/src/cli/model.ts +132 -3
- 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 +512 -0
- package/src/coding-agent/omo-state.ts +69 -0
- package/src/coding-agent/omo-stream.ts +138 -0
- package/src/coding-agent/omo.ts +192 -0
- package/src/coding-agent/runner.ts +285 -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 +121 -25
- package/src/config/model-overrides.ts +59 -0
- package/src/config/models-mutation.ts +185 -2
- package/src/config/providers-mutation.ts +12 -4
- package/src/config/providers.ts +71 -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 +120 -17
- 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 +22 -8
- package/src/hostd/daemon.ts +33 -11
- package/src/hostd/spawn.ts +106 -5
- package/src/hostd/version.ts +20 -0
- package/src/hostd/watchdog.ts +241 -0
- package/src/init/auto-upgrade.ts +7 -1
- package/src/init/dockerfile.ts +112 -602
- package/src/init/index.ts +6 -6
- package/src/init/local-source-stamp.ts +68 -0
- package/src/init/models-dev.ts +4 -0
- package/src/init/validate-api-key.ts +3 -0
- 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/permissions/builtins.ts +7 -0
- package/src/permissions/permissions.ts +18 -9
- package/src/permissions/resolve.ts +7 -1
- package/src/plugin/context.ts +2 -0
- package/src/plugin/core-tool-names.ts +1 -1
- package/src/plugin/define.ts +1 -0
- package/src/plugin/hooks.ts +137 -0
- package/src/plugin/index.ts +7 -0
- package/src/plugin/manager.ts +4 -0
- package/src/plugin/types.ts +66 -1
- package/src/run/background-handoff-boot.ts +86 -0
- package/src/run/bundled-plugins.ts +6 -0
- package/src/run/index.ts +107 -97
- package/src/run/llm-fetch-observer.ts +12 -15
- package/src/run/resource-sample.ts +19 -0
- package/src/sandbox/build.ts +4 -0
- package/src/sandbox/canonical-secrets.ts +4 -0
- package/src/sandbox/coding-agent.ts +214 -0
- package/src/sandbox/dev-source.ts +26 -0
- package/src/sandbox/hidden-paths.ts +16 -2
- 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/secrets/storage.ts +13 -0
- package/src/server/command-runner.ts +6 -2
- package/src/server/index.ts +101 -40
- package/src/skills/typeclaw-channel-github/SKILL.md +15 -13
- 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 +60 -26
- 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 +3 -3
- package/src/skills/typeclaw-memory/SKILL.md +3 -3
- package/src/skills/typeclaw-monorepo/SKILL.md +1 -1
- 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-permissions/SKILL.md +7 -7
- 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 +26 -2
- package/typeclaw.schema.json +448 -6
- package/src/bundled-plugins/doc-render/templates/lib.typ +0 -339
- package/src/bundled-plugins/github-cli-auth/gh-store.ts +0 -733
- 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,250 +0,0 @@
|
|
|
1
|
-
import {
|
|
2
|
-
chmodSync,
|
|
3
|
-
mkdirSync,
|
|
4
|
-
readFileSync,
|
|
5
|
-
readlinkSync,
|
|
6
|
-
renameSync,
|
|
7
|
-
statSync,
|
|
8
|
-
unlinkSync,
|
|
9
|
-
writeFileSync,
|
|
10
|
-
} from 'node:fs'
|
|
11
|
-
import { homedir } from 'node:os'
|
|
12
|
-
import { dirname, isAbsolute, join, resolve } from 'node:path'
|
|
13
|
-
|
|
14
|
-
import { decodeCodexAccessTokenExpiryMs, emitCodexAuthJson, isDecodableJwt } from './codex-auth-json'
|
|
15
|
-
import type { ProviderCredential, Providers } from './schema'
|
|
16
|
-
import { SecretsBackend } from './storage'
|
|
17
|
-
|
|
18
|
-
const FILE_MODE = 0o600
|
|
19
|
-
const DIR_MODE = 0o700
|
|
20
|
-
|
|
21
|
-
export type ExportCodexAuthFileResult =
|
|
22
|
-
| { action: 'skipped'; reason: SkipReason }
|
|
23
|
-
| { action: 'wrote'; path: string }
|
|
24
|
-
| { action: 'failed'; reason: string }
|
|
25
|
-
|
|
26
|
-
export type SkipReason =
|
|
27
|
-
| 'codex-cli-disabled'
|
|
28
|
-
| 'no-openai-codex-credential'
|
|
29
|
-
| 'credential-not-oauth'
|
|
30
|
-
| 'on-disk-is-fresher'
|
|
31
|
-
|
|
32
|
-
export type ExportCodexAuthFileOptions = {
|
|
33
|
-
codexCliEnabled: boolean
|
|
34
|
-
providers: Providers
|
|
35
|
-
homeDir?: string
|
|
36
|
-
now?: () => number
|
|
37
|
-
log?: (message: string) => void
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
// Writes typeclaw's openai-codex OAuth credential to $HOME/.codex/auth.json
|
|
41
|
-
// when it's safe to do so. Container HOME is /home/agent and ephemeral; this
|
|
42
|
-
// boot-time export reconstructs the CLI file from secrets.json after provider
|
|
43
|
-
// OAuth refresh has had a chance to update the canonical credential.
|
|
44
|
-
//
|
|
45
|
-
// Three guards, cheapest first. The first two return without ever touching
|
|
46
|
-
// the filesystem, which keeps the 90% case (users who don't enable Codex
|
|
47
|
-
// CLI) at zero overhead on every container start.
|
|
48
|
-
export function exportCodexAuthFileIfApplicable(options: ExportCodexAuthFileOptions): ExportCodexAuthFileResult {
|
|
49
|
-
if (!options.codexCliEnabled) return { action: 'skipped', reason: 'codex-cli-disabled' }
|
|
50
|
-
|
|
51
|
-
const credential = options.providers['openai-codex']
|
|
52
|
-
if (credential === undefined) return { action: 'skipped', reason: 'no-openai-codex-credential' }
|
|
53
|
-
if (credential.type !== 'oauth') return { action: 'skipped', reason: 'credential-not-oauth' }
|
|
54
|
-
|
|
55
|
-
const targetPath = join(options.homeDir ?? homedir(), '.codex', 'auth.json')
|
|
56
|
-
|
|
57
|
-
try {
|
|
58
|
-
if (!shouldOverwrite(targetPath, credential, options.now ?? Date.now)) {
|
|
59
|
-
return { action: 'skipped', reason: 'on-disk-is-fresher' }
|
|
60
|
-
}
|
|
61
|
-
const contents = emitCodexAuthJson(credential)
|
|
62
|
-
writeAtomic(targetPath, contents)
|
|
63
|
-
return { action: 'wrote', path: targetPath }
|
|
64
|
-
} catch (err) {
|
|
65
|
-
const reason = err instanceof Error ? err.message : String(err)
|
|
66
|
-
options.log?.(`exportCodexAuthFile: ${reason}`)
|
|
67
|
-
return { action: 'failed', reason }
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
// Newer-wins: skip the write unless typeclaw's stored credential is
|
|
72
|
-
// strictly fresher than the on-disk JWT. Codex CLI rotates tokens
|
|
73
|
-
// in-place (it rewrites auth.json with a refreshed access_token whose
|
|
74
|
-
// JWT exp is later), so on a restart the file may legitimately be ahead
|
|
75
|
-
// of secrets.json. We must not clobber that.
|
|
76
|
-
//
|
|
77
|
-
// Ties skip: when expiries match, there's nothing to gain from a write,
|
|
78
|
-
// and avoiding the I/O keeps the steady state at zero churn after the
|
|
79
|
-
// first boot. The only writes we ever do are first-write (B1), recovery
|
|
80
|
-
// (B6), or refresh-from-typeclaw-side (B3).
|
|
81
|
-
//
|
|
82
|
-
// On any error reading or parsing the on-disk file (missing, corrupt JSON,
|
|
83
|
-
// missing JWT, undecodable exp), we return true. That's the "we have a
|
|
84
|
-
// valid credential, the file is unusable, replace it" fallback case (B1
|
|
85
|
-
// and B6 in the design doc).
|
|
86
|
-
//
|
|
87
|
-
// A file missing a usable `id_token` is unusable too, regardless of how
|
|
88
|
-
// fresh its access token is: codex rejects the whole auth.json with
|
|
89
|
-
// `missing field id_token` before any model call. This guard runs BEFORE
|
|
90
|
-
// the newer-wins expiry compare so a pre-fix TypeClaw-emitted file (valid,
|
|
91
|
-
// possibly fresher access token, but no id_token) is always rewritten —
|
|
92
|
-
// the path that self-heals already-broken agents on restart.
|
|
93
|
-
function shouldOverwrite(
|
|
94
|
-
targetPath: string,
|
|
95
|
-
credential: ProviderCredential & { expires?: unknown; access?: unknown },
|
|
96
|
-
now: () => number,
|
|
97
|
-
): boolean {
|
|
98
|
-
let raw: string
|
|
99
|
-
try {
|
|
100
|
-
raw = readFileSync(targetPath, 'utf8')
|
|
101
|
-
} catch {
|
|
102
|
-
return true
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
let parsed: unknown
|
|
106
|
-
try {
|
|
107
|
-
parsed = JSON.parse(raw)
|
|
108
|
-
} catch {
|
|
109
|
-
return true
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
if (!onDiskHasUsableIdToken(parsed)) return true
|
|
113
|
-
|
|
114
|
-
const onDiskAccess = readOnDiskAccessToken(parsed)
|
|
115
|
-
if (onDiskAccess === null) return true
|
|
116
|
-
|
|
117
|
-
const onDiskExpiry = decodeCodexAccessTokenExpiryMs(onDiskAccess)
|
|
118
|
-
if (onDiskExpiry === null) return true
|
|
119
|
-
|
|
120
|
-
const credentialExpiry = readCredentialExpiry(credential, now)
|
|
121
|
-
return credentialExpiry > onDiskExpiry
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
function readOnDiskAccessToken(parsed: unknown): string | null {
|
|
125
|
-
return readOnDiskToken(parsed, 'access_token')
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
// codex parses `tokens.id_token` as a JWT, so a value that is absent, empty,
|
|
129
|
-
// or not a decodable JWT is unusable — codex rejects the whole auth.json on
|
|
130
|
-
// load. Validate decodability (not just presence) so a file with a non-empty
|
|
131
|
-
// but malformed id_token, even alongside a fresh access token, is treated as
|
|
132
|
-
// stale and rewritten rather than preserved by the newer-wins compare.
|
|
133
|
-
function onDiskHasUsableIdToken(parsed: unknown): boolean {
|
|
134
|
-
const idToken = readOnDiskToken(parsed, 'id_token')
|
|
135
|
-
return idToken !== null && isDecodableJwt(idToken)
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
function readOnDiskToken(parsed: unknown, field: 'access_token' | 'id_token'): string | null {
|
|
139
|
-
if (typeof parsed !== 'object' || parsed === null) return null
|
|
140
|
-
const tokens = (parsed as Record<string, unknown>)['tokens']
|
|
141
|
-
if (typeof tokens !== 'object' || tokens === null) return null
|
|
142
|
-
const value = (tokens as Record<string, unknown>)[field]
|
|
143
|
-
return typeof value === 'string' && value.length > 0 ? value : null
|
|
144
|
-
}
|
|
145
|
-
|
|
146
|
-
// Resolution order for the credential's expiry:
|
|
147
|
-
// 1. The `expires` field pi-ai writes (absolute ms epoch).
|
|
148
|
-
// 2. The JWT `exp` claim decoded from `access`.
|
|
149
|
-
// 3. Now — guarantees we still write on first boot when the credential
|
|
150
|
-
// lacks both, rather than silently skipping forever.
|
|
151
|
-
function readCredentialExpiry(credential: { expires?: unknown; access?: unknown }, now: () => number): number {
|
|
152
|
-
if (typeof credential.expires === 'number' && Number.isFinite(credential.expires)) {
|
|
153
|
-
return credential.expires
|
|
154
|
-
}
|
|
155
|
-
if (typeof credential.access === 'string') {
|
|
156
|
-
const fromJwt = decodeCodexAccessTokenExpiryMs(credential.access)
|
|
157
|
-
if (fromJwt !== null) return fromJwt
|
|
158
|
-
}
|
|
159
|
-
return now()
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
// Atomic temp-then-rename, mirroring src/secrets/storage.ts's
|
|
163
|
-
// writeEnvelopeAtomic. The directory is created with 0700 and the file
|
|
164
|
-
// with 0600 because $HOME/.codex/auth.json holds a long-lived refresh
|
|
165
|
-
// token — leaking it via lax permissions defeats the whole point of
|
|
166
|
-
// running typeclaw on a multi-user host. The 0600 chmod after rename is
|
|
167
|
-
// belt-and-suspenders: writeFileSync's `mode` is applied at create time,
|
|
168
|
-
// but umask can mask it down on some filesystems.
|
|
169
|
-
//
|
|
170
|
-
// Symlink preservation is still a safety property even though TypeClaw no
|
|
171
|
-
// longer plants one here. An operator or external tool may preconfigure
|
|
172
|
-
// $HOME/.codex/auth.json as a symlink; POSIX rename(2) replaces that directory
|
|
173
|
-
// entry instead of following it. Resolve the target and rename there so the
|
|
174
|
-
// caller's symlink survives. The temp file MUST live alongside the real target
|
|
175
|
-
// because renameSync across filesystems fails with EXDEV.
|
|
176
|
-
function writeAtomic(targetPath: string, contents: string): void {
|
|
177
|
-
const realTarget = resolveSymlinkTarget(targetPath)
|
|
178
|
-
const dir = dirname(realTarget)
|
|
179
|
-
mkdirSync(dir, { recursive: true, mode: DIR_MODE })
|
|
180
|
-
const tmp = `${realTarget}.${process.pid}.${Date.now()}.tmp`
|
|
181
|
-
writeFileSync(tmp, contents, { encoding: 'utf8', mode: FILE_MODE })
|
|
182
|
-
try {
|
|
183
|
-
renameSync(tmp, realTarget)
|
|
184
|
-
} catch (err) {
|
|
185
|
-
try {
|
|
186
|
-
unlinkSync(tmp)
|
|
187
|
-
} catch {
|
|
188
|
-
// best-effort cleanup of the temp file when rename fails
|
|
189
|
-
}
|
|
190
|
-
throw err
|
|
191
|
-
}
|
|
192
|
-
// statSync + chmodSync rather than unconditional chmod so a 0644 file
|
|
193
|
-
// installed by something else stays visible in tests (we WANT to overwrite
|
|
194
|
-
// permissions when we own the file).
|
|
195
|
-
try {
|
|
196
|
-
statSync(realTarget)
|
|
197
|
-
chmodSync(realTarget, FILE_MODE)
|
|
198
|
-
} catch {
|
|
199
|
-
// ignore — file vanished between rename and chmod is benign
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
|
|
203
|
-
// Returns the absolute path renameSync should target. When `path` is a symlink,
|
|
204
|
-
// returns the resolved absolute target so we write through the link instead of
|
|
205
|
-
// replacing it. Otherwise returns the path unchanged.
|
|
206
|
-
//
|
|
207
|
-
// readlinkSync throws EINVAL when the path exists but isn't a symlink,
|
|
208
|
-
// and ENOENT when nothing is there. Either case → write to the original
|
|
209
|
-
// path; the parent-dir mkdir + atomic rename handle the rest. We don't
|
|
210
|
-
// distinguish errno because both have the same fallback.
|
|
211
|
-
function resolveSymlinkTarget(path: string): string {
|
|
212
|
-
let link: string
|
|
213
|
-
try {
|
|
214
|
-
link = readlinkSync(path)
|
|
215
|
-
} catch {
|
|
216
|
-
return path
|
|
217
|
-
}
|
|
218
|
-
return isAbsolute(link) ? link : resolve(dirname(path), link)
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
export type ExportCodexAuthFileForAgentOptions = {
|
|
222
|
-
agentDir: string
|
|
223
|
-
codexCliEnabled: boolean
|
|
224
|
-
homeDir?: string
|
|
225
|
-
log?: (message: string) => void
|
|
226
|
-
}
|
|
227
|
-
|
|
228
|
-
// Boot-time convenience wrapper for src/run/index.ts. Mirrors
|
|
229
|
-
// hydrateChannelEnvFromSecrets's contract: takes agentDir, never throws,
|
|
230
|
-
// returns a result the caller can ignore. Secrets-file read failures are
|
|
231
|
-
// caught and surfaced as a 'failed' result so the agent boot is not blocked
|
|
232
|
-
// by a missing or malformed secrets.json — same non-fatal policy hydrate
|
|
233
|
-
// uses on the channels slice.
|
|
234
|
-
export function exportCodexAuthFileForAgent(options: ExportCodexAuthFileForAgentOptions): ExportCodexAuthFileResult {
|
|
235
|
-
if (!options.codexCliEnabled) return { action: 'skipped', reason: 'codex-cli-disabled' }
|
|
236
|
-
let providers: Providers
|
|
237
|
-
try {
|
|
238
|
-
providers = new SecretsBackend(join(options.agentDir, 'secrets.json')).tryReadProvidersSync()
|
|
239
|
-
} catch (err) {
|
|
240
|
-
const reason = err instanceof Error ? err.message : String(err)
|
|
241
|
-
options.log?.(`exportCodexAuthFile: ${reason}`)
|
|
242
|
-
return { action: 'failed', reason }
|
|
243
|
-
}
|
|
244
|
-
return exportCodexAuthFileIfApplicable({
|
|
245
|
-
codexCliEnabled: options.codexCliEnabled,
|
|
246
|
-
providers,
|
|
247
|
-
...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
|
|
248
|
-
...(options.log !== undefined ? { log: options.log } : {}),
|
|
249
|
-
})
|
|
250
|
-
}
|
|
@@ -1,101 +0,0 @@
|
|
|
1
|
-
# Stop hook — schema and gotchas
|
|
2
|
-
|
|
3
|
-
Deep dive for the `Stop` lifecycle hook that powers the done-signal. Read it when the basic hook in `SKILL.md` isn't enough — when the transcript looks stale, the sentinel is malformed, or you need to extract intermediate tool calls from the JSONL.
|
|
4
|
-
|
|
5
|
-
## What fires when
|
|
6
|
-
|
|
7
|
-
Claude Code supports several lifecycle hooks. The two relevant to delegation are:
|
|
8
|
-
|
|
9
|
-
- **`Stop`** — fires every time the _main_ agent finishes responding. This is per-turn, not per-session. A 5-turn conversation fires `Stop` five times. The "task is done" signal is just "the latest Stop, where claude's message looks like a result not a question" — that's the multi-turn decision loop in `SKILL.md`.
|
|
10
|
-
- **`SubagentStop`** — fires when a _sub-agent_ (Task tool, plan-mode sub-agents, etc.) finishes. Sub-agents are claude spawning claude. You don't typically need to handle this — the parent's `Stop` fires after its sub-agents are done. Configure it only if you want progress signals during a sub-agent-heavy turn.
|
|
11
|
-
|
|
12
|
-
Other hooks that exist (`PreToolUse`, `PostToolUse`, `Notification`, `SessionStart`, `SessionEnd`, `PreCompact`, etc.) are out of scope for this skill — they're useful for progress logging, command auditing, or session bookkeeping, but they're not the done-signal.
|
|
13
|
-
|
|
14
|
-
## Stop event JSON schema
|
|
15
|
-
|
|
16
|
-
The hook command receives a single JSON object on stdin. Fields observed in current Claude Code (subject to upstream churn — the docs page is at `https://docs.anthropic.com/en/docs/claude-code/hooks`):
|
|
17
|
-
|
|
18
|
-
```jsonc
|
|
19
|
-
{
|
|
20
|
-
"session_id": "abc123…", // The Claude Code session UUID
|
|
21
|
-
"transcript_path": "/root/.claude/projects/-tmp-cc-foo/abc123.jsonl",
|
|
22
|
-
"cwd": "/tmp/cc-foo", // Should match your worktree path
|
|
23
|
-
"permission_mode": "default", // or "plan", "bypassPermissions", etc.
|
|
24
|
-
"hook_event_name": "Stop", // Literal "Stop" for this event
|
|
25
|
-
"stop_hook_active": false, // True only while the hook itself runs
|
|
26
|
-
"last_assistant_message": "…", // The text of claude's just-finished turn
|
|
27
|
-
}
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
Fields you actually use:
|
|
31
|
-
|
|
32
|
-
- **`last_assistant_message`** — your primary capture for the multi-turn decision loop. Read this from `sentinel.json`, classify (question / permission / result / spurious), act.
|
|
33
|
-
- **`transcript_path`** — points at the JSONL with the full conversation. Useful when `last_assistant_message` isn't enough.
|
|
34
|
-
- **`cwd`** — sanity check. If this isn't `/tmp/cc-<id>`, something is wrong with your tmux spawn (likely missing `-c`).
|
|
35
|
-
- **`session_id`** — useful for logging or if you want to correlate with the JSONL filename.
|
|
36
|
-
|
|
37
|
-
Fields you ignore:
|
|
38
|
-
|
|
39
|
-
- `permission_mode`, `stop_hook_active` — for hook-internal coordination, not delegation logic.
|
|
40
|
-
|
|
41
|
-
### SubagentStop deltas
|
|
42
|
-
|
|
43
|
-
If you ever configure a `SubagentStop` hook, expect these additional fields:
|
|
44
|
-
|
|
45
|
-
```jsonc
|
|
46
|
-
{
|
|
47
|
-
"agent_id": "def456…",
|
|
48
|
-
"agent_transcript_path": "/root/.claude/projects/-tmp-cc-foo/abc123/subagents/agent-def456.jsonl",
|
|
49
|
-
}
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
The schema is otherwise the same. `agent_transcript_path` is a separate JSONL per sub-agent.
|
|
53
|
-
|
|
54
|
-
## The transcript JSONL
|
|
55
|
-
|
|
56
|
-
`transcript_path` points at a JSONL file with one JSON object per line. Anthropic does not publish a formal schema — community tools (claudeoo, maury, serac) have reverse-engineered it. What you'll see:
|
|
57
|
-
|
|
58
|
-
- **`{ "type": "user", "message": { … } }`** — what you sent claude (or what the upstream parent sent, for sub-agents).
|
|
59
|
-
- **`{ "type": "assistant", "message": { "content": [ … ] } }`** — claude's response. `content` is an array of `{ "type": "text", "text": "…" }` and `{ "type": "tool_use", … }` objects.
|
|
60
|
-
- **`{ "type": "tool_use", "name": "Read", "input": { … } }`** — tool calls claude made.
|
|
61
|
-
- **`{ "type": "tool_result", "tool_use_id": "…", "content": "…" }`** — tool results.
|
|
62
|
-
- **`{ "type": "system", "subtype": "…" }`** — system events: `compact_boundary`, `turn_duration`, `stop_hook_summary`, etc.
|
|
63
|
-
- **`{ "type": "attachment", … }`** — file uploads or contextual attachments.
|
|
64
|
-
|
|
65
|
-
To extract claude's final text answer when `last_assistant_message` isn't enough:
|
|
66
|
-
|
|
67
|
-
```sh
|
|
68
|
-
# Read every assistant-text content line from the JSONL
|
|
69
|
-
jq -r 'select(.type == "assistant") | .message.content[] | select(.type == "text") | .text' "$transcript_path"
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
Filter further by timestamp or message-id if you only want the last turn.
|
|
73
|
-
|
|
74
|
-
## Documented race conditions
|
|
75
|
-
|
|
76
|
-
Three known races, all from upstream Claude Code issues. The skill body's design avoids them by preferring the sentinel over the JSONL; this is the reasoning if you have to debug:
|
|
77
|
-
|
|
78
|
-
1. **Stale transcript on Stop (#15813).** The `Stop` hook can fire before the last assistant message is flushed to the JSONL. If you read `transcript_path` immediately on hook fire, the last message may not be there yet. **Mitigation:** use `last_assistant_message` from the hook's stdin JSON as the primary capture; treat the JSONL as the backup, with a 1–2 second wait if it looks stale.
|
|
79
|
-
2. **Missing transcript file (#20612, #30217).** Some users report `transcript_path` pointing at a file that doesn't exist, especially in multi-session or concurrent-worktree setups. **Mitigation:** capture `last_assistant_message` on every Stop and accumulate it yourself if you need the full history. Falling back to `tmux capture-pane -S -` is the last-resort path.
|
|
80
|
-
3. **Inaccurate final token counts (#27361).** The JSONL has historically missed the final `message_stop` SSE event, causing `output_tokens` to be a mid-stream snapshot (sometimes undercounted by ~2x). **Mitigation:** don't rely on JSONL token counts for cost calculations; the Anthropic Console workspace usage is the authoritative source.
|
|
81
|
-
|
|
82
|
-
## Permission prompts vs Stop
|
|
83
|
-
|
|
84
|
-
A subtle point that confuses the multi-turn decision loop: **permission prompts do not fire `Stop`**. When claude is waiting for a "Allow this command?" yes/no, the turn isn't over — the model is waiting for the _user_ (you) to type y/n into the TUI, not waiting for a new prompt. So:
|
|
85
|
-
|
|
86
|
-
- **Permission prompt appears** → no `Stop`, no `.done`, you keep polling.
|
|
87
|
-
- **You answer the prompt** (via `tmux send-keys "y" Enter`) → claude continues working, eventually finishes its turn → `Stop` fires.
|
|
88
|
-
|
|
89
|
-
This is why the multi-turn loop's classification is "ends with question mark / contains 'Do you want me to'" — it's looking for _content-level_ questions claude wrote as part of its response, not permission-tool prompts. Permission prompts don't reach `last_assistant_message`; they only appear in the pane.
|
|
90
|
-
|
|
91
|
-
If you need to detect permission prompts (to auto-answer them), `capture-pane` is the only signal. Look for the literal yes/no UI affordance at the bottom of the pane. This is risky to automate — you're answering on the user's behalf for an operation you can't see the full safety implications of. Default behavior in this skill: pause polling for the sentinel, look at the pane after the budget elapses without a `.done`, and if there's a permission prompt sitting there, surface to the user rather than auto-answering.
|
|
92
|
-
|
|
93
|
-
## Things you must not do with the Stop hook
|
|
94
|
-
|
|
95
|
-
- **Do not write a per-worktree `.claude/settings.json` from operator code.** The hook is pre-baked into the image at build time (see `src/init/dockerfile.ts`, constants `TYPECLAW_CC_STOP_HOOK_PATH` and `TYPECLAW_CC_GLOBAL_SETTINGS`) precisely so the operator subagent never has to construct the JSON itself. Past delegations failed by inventing wrong shapes like `{"hooks": {"onStop": "./script.sh"}}` (wrong key — Claude Code's event name is literal `Stop`, no `on` prefix), `{"hooks": {"Stop": "./script.sh"}}` (right key, wrong value type — must be an array of matcher objects, not a string), and `{"hooks": {"Stop": [{"command": "./script.sh"}]}}` (missing the `matcher` and the inner `hooks` array — the schema is two levels of nesting, not one). All three slips silently fail: Claude Code ignores unknown keys, so the hook is never registered, `.done` is never created, and the polling loop times out at its wall-clock budget. If you ever find yourself wanting to write a per-worktree settings file, **stop** — either the global hook isn't installed (verify with the `jq` check in `SKILL.md`'s "The Stop hook" section) or you're trying to customize behavior the skill's flow doesn't anticipate. In the former case, bail to the user; in the latter, the right answer is a code change to `src/init/dockerfile.ts`, not a runtime JSON write.
|
|
96
|
-
- **Do not edit the in-Dockerfile hook config in a way that bypasses `JSON.stringify` + the regression test.** `TYPECLAW_CC_GLOBAL_SETTINGS` in `src/init/dockerfile.ts` is constructed via `JSON.stringify` so any structural drift fails `dockerfile.test.ts`'s `JSON.parse` regression test, not the docker build or (worse) the first failed delegation. Hand-writing the JSON as a string literal would let a typo land in production. The accepted shape is exactly `{"hooks": {"Stop": [{"matcher": "*", "hooks": [{"type": "command", "command": "..."}]}]}}`.
|
|
97
|
-
- **Do not set `matcher` to anything other than `"*"`.** The matcher filters by hook tool name; for `Stop`, there's no tool — `"*"` is the canonical "fire on every Stop". Other values may silently never match.
|
|
98
|
-
- **Do not put long-running commands in the hook.** The hook runs synchronously on the Claude Code main loop; a slow hook blocks the user's next prompt. Write the payload + touch a flag + exit. Anything heavier belongs in your polling loop, not the hook.
|
|
99
|
-
- **Do not skip the temp-file rename pattern.** Writing `sentinel.json` directly with `>` lets readers see partial JSON if they poll mid-write. Always `cat > sentinel.json.tmp && mv sentinel.json.tmp sentinel.json`.
|
|
100
|
-
- **Do not delete `transcript_path` from inside the hook.** The path is shared with `SessionEnd` and other lifecycle events; deleting it breaks downstream hooks.
|
|
101
|
-
- **Do not log the full hook payload to a place you don't control.** It contains `last_assistant_message`, which can contain anything claude said — including code, secrets the user pasted, or private context. Sentinel is fine (it's in `/tmp/`); piping to a shared log is not.
|
|
@@ -1,243 +0,0 @@
|
|
|
1
|
-
# Tmux driving — full reference
|
|
2
|
-
|
|
3
|
-
Deep dive for driving `claude` (interactive) through tmux. Read it when the main `SKILL.md` workflow hits an edge case: a hung session, a missing JSONL, an unexpected ANSI burst, a "tmux says session exists but claude isn't responsive" situation.
|
|
4
|
-
|
|
5
|
-
## Why tmux
|
|
6
|
-
|
|
7
|
-
The agent process has no TTY. `claude` (interactive) is a TUI that uses raw terminal modes — it reads stdin one byte at a time with echo off, draws with ANSI escapes, and refuses to start if stdin/stdout aren't terminals. Piping into `claude` (`echo "prompt" | claude`) doesn't work; the CLI detects the absence of a TTY and either falls back to `-p` semantics (no plan mode) or fails outright.
|
|
8
|
-
|
|
9
|
-
`tmux` solves this by spawning the process with a pty allocated by tmux itself. You then drive the pty via `send-keys` (write) and `capture-pane` (read). The process believes it's running interactively because, from its file descriptor's point of view, it is.
|
|
10
|
-
|
|
11
|
-
## Why `/tmp/cc-<id>` and not `workspace/cc-<id>`
|
|
12
|
-
|
|
13
|
-
The cwd of the spawned `claude` process must be the git worktree at `/tmp/cc-<id>/`, not the agent folder's `workspace/`. Three reasons:
|
|
14
|
-
|
|
15
|
-
1. **Worktree-vs-scratch:** the `cc-<id>` directory is a real git checkout managed by `git worktree`, with refs in `/agent/.git/worktrees/cc-<id>/`. Putting it under `workspace/` would mean the agent folder contains a worktree of itself, which works mechanically but is recursive and confusing.
|
|
16
|
-
2. **The global SessionStart and Stop hooks write their per-session files into cwd.** Both hook scripts read `$PWD` (the literal cwd Claude Code was invoked with) and write into it: SessionStart writes `.session-id` containing the UUID; Stop writes `sentinel-<uuid>.json` and `.done-<uuid>`. `$PWD` resolves to the worktree because `tmux new-session -c /tmp/cc-<id>` sets claude's cwd there. If cwd is the wrong place, the files land somewhere the polling loop isn't watching and the loop times out at its budget. (The hook config itself is global at `~/.claude/settings.json`, not per-worktree — see `references/stop-hook.md` for the architectural context. The hooks deliberately do NOT use Claude Code's `$CLAUDE_PROJECT_DIR` env var, which resolves to the git root of cwd — inside a worktree that's the main repo, not the worktree path; the dockerfile constant block in `src/init/dockerfile.ts` carries the rationale.)
|
|
17
|
-
3. **The worktree IS the codebase.** Claude can read every file at `HEAD` directly — it doesn't need a separate scratch area.
|
|
18
|
-
|
|
19
|
-
Auth has no in-container scratch directory at all — the OAuth `setup-token` flow runs on the user's machine, not in tmux here. See `references/auth-flow.md`.
|
|
20
|
-
|
|
21
|
-
## Spawning the session
|
|
22
|
-
|
|
23
|
-
The canonical spawn (per `SKILL.md`):
|
|
24
|
-
|
|
25
|
-
```sh
|
|
26
|
-
tmux new-session -d -s cc-<task-id> -c /tmp/cc-<task-id> claude
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Flags worth knowing:
|
|
30
|
-
|
|
31
|
-
- `-d` — detached. The session runs in the background; your shell doesn't attach.
|
|
32
|
-
- `-s cc-<task-id>` — explicit session name. Required. Without `-s`, tmux picks `0`, `1`, … and a sibling delegation will clobber yours.
|
|
33
|
-
- `-c /tmp/cc-<task-id>` — start directory. Must be the worktree path. The global Stop hook at `~/.claude/settings.json` always fires regardless of cwd, but the hook script writes its sentinel to `$PWD`; if cwd is wrong, the sentinel lands somewhere your polling loop isn't watching.
|
|
34
|
-
- `claude` — the command. Just `claude`, not `claude -p`. The interactive TUI is the whole point.
|
|
35
|
-
|
|
36
|
-
Common mistake: forgetting `-c` and getting cwd `/agent` by default. The Stop hook still fires (it's global), but `sentinel.json` + `.done` end up under `/agent/`, your polling loop watches `/tmp/cc-<id>/`, and the loop times out at its wall-clock budget. Worse: claude in `/agent` operates on the live working tree instead of the worktree.
|
|
37
|
-
|
|
38
|
-
## The init wait
|
|
39
|
-
|
|
40
|
-
`claude` prints a banner, performs auth verification, and renders its input box. This takes ~2–3 seconds on a warm cache, up to ~8s on cold start. You must wait for the input box to render (and clear any startup dialogs) before sending the first prompt, otherwise `send-keys` writes to a pane that isn't accepting input yet and your keystrokes are lost.
|
|
41
|
-
|
|
42
|
-
The skill body's flow uses dialog-polling rather than a fixed sleep: every 500ms, `tmux capture-pane -t cc-<id> -p -S -15` and check for the input box (Unicode box-drawing `╭` / `╰` at column 0 of bottom rows) OR a known dialog (API key confirmation / workspace trust). Clear dialogs as they appear, exit the loop when the input box is visible. Give up after ~10s and surface to the user.
|
|
43
|
-
|
|
44
|
-
`.session-id` cannot be used as a readiness signal: per anthropics/claude-code#11519, SessionStart is SKIPPED while workspace trust is pending. The dialog-polling loop is the only reliable signal here.
|
|
45
|
-
|
|
46
|
-
## Sending input
|
|
47
|
-
|
|
48
|
-
```sh
|
|
49
|
-
tmux send-keys -t cc-<id> "<text>" Enter
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
Notes:
|
|
53
|
-
|
|
54
|
-
- **Quote carefully.** The text is interpreted by tmux's send-keys before reaching the pty. Embedded `"` and `\` need escaping. For complex prompts, write the prompt to a file and use `tmux load-buffer + paste-buffer` instead of `send-keys`:
|
|
55
|
-
|
|
56
|
-
```sh
|
|
57
|
-
echo "<prompt>" > prompt.txt
|
|
58
|
-
tmux load-buffer -t cc-<id> prompt.txt
|
|
59
|
-
tmux paste-buffer -t cc-<id>
|
|
60
|
-
tmux send-keys -t cc-<id> Enter
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
- **`Enter` is the literal key name**, not the text "Enter". Other useful key names: `Escape`, `Tab`, `BSpace`, `Up`, `Down`, `C-c` (Ctrl+C), `C-d` (Ctrl+D for EOF).
|
|
64
|
-
|
|
65
|
-
- **Multi-line prompts**: send the body, then `Enter`. Claude Code's input box treats `Enter` as submit, so newlines in your text become submitted lines (not multi-line input). If you need a genuinely multi-line prompt, use the paste-buffer flow above with embedded newlines.
|
|
66
|
-
|
|
67
|
-
## Discovering `cc_session_id` and polling for `.done-<session_id>`
|
|
68
|
-
|
|
69
|
-
The skill workflow does NOT pre-fetch the session UUID from `.session-id` — per anthropics/claude-code#11519, SessionStart is suppressed while workspace trust is pending, so `.session-id` may never appear before the first prompt. Instead, the operator discovers the UUID from the **newest unprocessed** Stop sentinel.
|
|
70
|
-
|
|
71
|
-
### Polling is edge-triggered, not level-triggered
|
|
72
|
-
|
|
73
|
-
A subtle correctness rule: never poll on "the current `.done-<sid>` appears." That's level-triggered and breaks when (a) an old `.done` still exists from the previous turn and (b) a new one with a different UUID appears (compaction). Instead:
|
|
74
|
-
|
|
75
|
-
1. **Track which sentinels you've already processed** (by UUID).
|
|
76
|
-
2. **On every poll, enumerate ALL `.done-*` files**, ignore the ones you've already processed, and pick the **newest by mtime** of what remains.
|
|
77
|
-
3. **Prefer real UUIDs over `malformed`**: if the newest unprocessed file is a real UUID, take it; if only `.done-malformed` remains, bail with a diagnostic.
|
|
78
|
-
4. **After processing**, remove the specific `.done-<uuid>` you read — don't `rm .done-*`, that wipes an in-flight new sentinel.
|
|
79
|
-
|
|
80
|
-
This shape handles three cases uniformly:
|
|
81
|
-
|
|
82
|
-
- **First turn**: no processed set; the only file is the new sentinel.
|
|
83
|
-
- **Normal turn N→N+1**: the new sentinel arrives, the old one was removed last iteration; pick the new one.
|
|
84
|
-
- **Compact mid-delegation**: a `.done-<newuuid>` appears while `.done-<oldsid>` may or may not have been cleaned; pick newest, update `cc_session_id`.
|
|
85
|
-
|
|
86
|
-
### Phase 1 — first-turn discovery (after the first prompt is sent)
|
|
87
|
-
|
|
88
|
-
```sh
|
|
89
|
-
budget=600 # 10 minutes in seconds for the first turn
|
|
90
|
-
elapsed=0
|
|
91
|
-
processed="" # space-separated list of UUIDs we've already consumed
|
|
92
|
-
cc_session_id=""
|
|
93
|
-
while [ -z "$cc_session_id" ]; do
|
|
94
|
-
# Newest unprocessed real .done-<uuid> wins.
|
|
95
|
-
# ls -t sorts by mtime (newest first). Restrict to .done-<uuid> shape via case below.
|
|
96
|
-
newest=""
|
|
97
|
-
for f in $(ls -t /tmp/cc-<id>/.done-* 2>/dev/null); do
|
|
98
|
-
[ -f "$f" ] || continue
|
|
99
|
-
uuid="${f##*/.done-}"
|
|
100
|
-
case " $processed " in *" $uuid "*) continue ;; esac
|
|
101
|
-
if [ "$uuid" = "malformed" ]; then
|
|
102
|
-
# Only honor malformed if there's nothing real to pick. Keep scanning;
|
|
103
|
-
# if we don't see a real UUID first, fall through to the malformed-only case.
|
|
104
|
-
malformed_fallback="$f"
|
|
105
|
-
continue
|
|
106
|
-
fi
|
|
107
|
-
newest="$f"
|
|
108
|
-
cc_session_id="$uuid"
|
|
109
|
-
break
|
|
110
|
-
done
|
|
111
|
-
if [ -n "$cc_session_id" ]; then break; fi
|
|
112
|
-
if [ -n "${malformed_fallback:-}" ]; then
|
|
113
|
-
echo "Stop hook fired but couldn't extract a UUID-shape session_id"
|
|
114
|
-
exit 1
|
|
115
|
-
fi
|
|
116
|
-
if [ "$elapsed" -ge "$budget" ]; then
|
|
117
|
-
echo "Timeout reached — first Stop never fired"
|
|
118
|
-
break
|
|
119
|
-
fi
|
|
120
|
-
if ! tmux has-session -t cc-<id> 2>/dev/null; then
|
|
121
|
-
echo "tmux session died unexpectedly"
|
|
122
|
-
break
|
|
123
|
-
fi
|
|
124
|
-
sleep 0.5
|
|
125
|
-
elapsed=$((elapsed + 1))
|
|
126
|
-
done
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
(Fast-path optimization: if `/tmp/cc-<id>/.session-id` already exists when phase 1 starts — meaning trust was somehow already accepted before this session started — read it and skip the glob. The skill body explains why this rarely wins on first delegations.)
|
|
130
|
-
|
|
131
|
-
### Phase 2 — per-turn polling (turns 2 onward, after sending another prompt)
|
|
132
|
-
|
|
133
|
-
```sh
|
|
134
|
-
budget=600
|
|
135
|
-
elapsed=0
|
|
136
|
-
# `processed` carries over from phase 1 — add the just-consumed UUID before entering phase 2.
|
|
137
|
-
processed="$processed $cc_session_id"
|
|
138
|
-
new_sid=""
|
|
139
|
-
while [ -z "$new_sid" ]; do
|
|
140
|
-
for f in $(ls -t /tmp/cc-<id>/.done-* 2>/dev/null); do
|
|
141
|
-
[ -f "$f" ] || continue
|
|
142
|
-
uuid="${f##*/.done-}"
|
|
143
|
-
case " $processed " in *" $uuid "*) continue ;; esac
|
|
144
|
-
if [ "$uuid" = "malformed" ]; then
|
|
145
|
-
echo "Stop hook fired but couldn't extract a UUID-shape session_id"
|
|
146
|
-
exit 1
|
|
147
|
-
fi
|
|
148
|
-
new_sid="$uuid"
|
|
149
|
-
break
|
|
150
|
-
done
|
|
151
|
-
if [ -n "$new_sid" ]; then break; fi
|
|
152
|
-
if [ "$elapsed" -ge "$budget" ]; then echo "Timeout reached"; break; fi
|
|
153
|
-
if ! tmux has-session -t cc-<id> 2>/dev/null; then echo "tmux session died unexpectedly"; break; fi
|
|
154
|
-
sleep 0.5
|
|
155
|
-
elapsed=$((elapsed + 1))
|
|
156
|
-
done
|
|
157
|
-
|
|
158
|
-
if [ "$new_sid" != "$cc_session_id" ]; then
|
|
159
|
-
echo "Detected session_id rotation (compact #29094): ${cc_session_id} → ${new_sid}"
|
|
160
|
-
cc_session_id="$new_sid"
|
|
161
|
-
fi
|
|
162
|
-
# Read sentinel for this turn:
|
|
163
|
-
cat "/tmp/cc-<id>/sentinel-${cc_session_id}.json"
|
|
164
|
-
# After deciding what to do next, remove ONLY this turn's marker (not a glob):
|
|
165
|
-
rm -f "/tmp/cc-<id>/.done-${cc_session_id}"
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
In your actual loop, translate to your tool calls. The shell snippets are illustrative.
|
|
169
|
-
|
|
170
|
-
### Why edge-triggered, not level-triggered
|
|
171
|
-
|
|
172
|
-
The previous version of this snippet was level-triggered (`while [ ! -f .done-${cc_session_id} ]`), which has two failure modes:
|
|
173
|
-
|
|
174
|
-
- **Compact rotation while the old marker still exists**: if the operator hasn't yet `rm`'d `.done-<old>` when claude compacts and fires Stop with `.done-<new>`, the level-triggered predicate is FALSE (old still exists), the inner rotation-check loop never runs, and the operator never notices the new UUID. The new sentinel sits unread; the operator's next `rm .done-<old>` removes the stale marker; the polling loop now blocks forever waiting for `.done-<old>` to reappear.
|
|
175
|
-
- **First-turn discovery picking the wrong file**: `for f in .done-*` iterates in shell glob order (lexicographic). If two `.done-*` exist (operator crashed mid-cleanup of a prior turn, or compact fired immediately), the lower-UUID-prefix file wins. Newest-by-mtime is causally correct; shell-glob order is not.
|
|
176
|
-
|
|
177
|
-
If `/tmp/cc-<id>/sentinel-malformed.json` or `/tmp/cc-<id>/.done-malformed` appears AND no real UUID file appears, a hook fired but session_id extraction failed (malformed JSON, missing field, or a future upstream schema change). Read `sentinel-malformed.json` to diagnose and surface to the user — this is not a recoverable state from the operator's side.
|
|
178
|
-
|
|
179
|
-
### Why 500ms cadence
|
|
180
|
-
|
|
181
|
-
- Faster polling (50–100ms) wastes CPU and is invisible to the user; the user's perception starts caring around 1s.
|
|
182
|
-
- Slower polling (2s+) adds visible latency to the multi-turn loop — every Stop adds up to 2s of pure wait.
|
|
183
|
-
- 500ms is the sweet spot: invisible latency, minimal CPU, plenty of headroom for short turns.
|
|
184
|
-
|
|
185
|
-
### Session-died recovery
|
|
186
|
-
|
|
187
|
-
`tmux has-session` returns non-zero when the session is gone. Three reasons:
|
|
188
|
-
|
|
189
|
-
1. **Claude crashed**: assertion failure, OOM, segfault. `capture-pane` before tmux GC'd the session would show a stack trace. After GC, the session is just gone; you can't recover the pane content.
|
|
190
|
-
2. **Auth failed**: `claude` exited cleanly with "API key invalid" or similar. Pane would have shown the error briefly before the process exited.
|
|
191
|
-
3. **User killed it externally**: someone ran `tmux kill-session -t cc-<id>` outside your control.
|
|
192
|
-
|
|
193
|
-
Recovery: surface to the user with whatever you have — `git diff main..cc-<id>` (which still works because the branch exists), `sentinel.json` from any prior turn, the JSONL if it exists. Then clean up: `git worktree remove --force /tmp/cc-<id>` + `git branch -D cc-<id>`. Ask whether to retry.
|
|
194
|
-
|
|
195
|
-
## Capturing the pane (fallback path)
|
|
196
|
-
|
|
197
|
-
When the JSONL is missing or you need to see what the TUI showed:
|
|
198
|
-
|
|
199
|
-
```sh
|
|
200
|
-
tmux capture-pane -t cc-<id> -p -S - -E -
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
Flags:
|
|
204
|
-
|
|
205
|
-
- `-p` — print to stdout (default is to copy to a tmux buffer).
|
|
206
|
-
- `-S -` — start from the beginning of the scrollback.
|
|
207
|
-
- `-E -` — end at the current line.
|
|
208
|
-
- Without `-S -E`, you only capture the visible pane (rows × cols), losing everything that scrolled off.
|
|
209
|
-
|
|
210
|
-
The captured content includes ANSI escape codes by default. Pass `-e` to preserve them explicitly (rarely useful) or omit and strip via a regex after capture: `s/\x1b\[[0-9;]*[a-zA-Z]//g`.
|
|
211
|
-
|
|
212
|
-
### ANSI gotchas
|
|
213
|
-
|
|
214
|
-
- **Progress spinners redraw the same line.** Capture-pane shows the final state of each cell, so spinners look harmless. But mid-capture, if claude is actively redrawing, you may catch a partial frame. Re-capture after `Stop` for a stable view.
|
|
215
|
-
- **Box-drawing characters** for the input box and message frames are Unicode (`╭ ╮ ╰ ╯ │ ─`). They render fine in modern terminals but mangle in some text post-processing. If you're showing pane content to the user via TypeClaw's TUI, just preserve as-is — Bun's stdout handles UTF-8.
|
|
216
|
-
- **Color codes**: standard 8-color (`\x1b[31m` etc.) and 256-color (`\x1b[38;5;Nm`). The strip regex above handles both.
|
|
217
|
-
|
|
218
|
-
## Cleaning up
|
|
219
|
-
|
|
220
|
-
```sh
|
|
221
|
-
tmux send-keys -t cc-<id> "/exit" Enter
|
|
222
|
-
sleep 1
|
|
223
|
-
tmux kill-session -t cc-<id> 2>/dev/null || true
|
|
224
|
-
git -C /agent worktree remove --force /tmp/cc-<id>
|
|
225
|
-
git -C /agent branch -D cc-<id>
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
- `/exit` is Claude Code's built-in exit command. Cleaner than `C-c` — it lets the CLI flush the JSONL and close cleanly.
|
|
229
|
-
- `sleep 1` gives the CLI time to flush. Skip it and you may lose the last few JSONL lines.
|
|
230
|
-
- `kill-session ... || true` because the session may have already exited cleanly after `/exit`.
|
|
231
|
-
- `worktree remove --force` because the working tree has un-cherry-picked changes (claude's edits + the sentinel + the hook). `--force` is correct here because we're explicitly discarding.
|
|
232
|
-
- `branch -D` to delete the throwaway branch. `-D` (capital) because `cc-<id>` is unmerged into anything you care about.
|
|
233
|
-
|
|
234
|
-
## Things you must not do in tmux driving
|
|
235
|
-
|
|
236
|
-
- **Do not omit `-s <name>` on `new-session`.** Anonymous sessions race across delegations.
|
|
237
|
-
- **Do not omit `-c /tmp/cc-<id>` on `new-session`.** The global Stop hook writes its sentinel into `$PWD`; wrong cwd means the sentinel lands somewhere your polling loop isn't watching. Worse: claude in `/agent` operates on the live working tree instead of the worktree.
|
|
238
|
-
- **Do not skip the init wait.** Sending input before the TUI is ready loses the input silently.
|
|
239
|
-
- **Do not use `send-keys` with raw user-supplied strings without escaping.** Tmux's send-keys is mildly shell-like; embedded special chars get interpreted. Use `load-buffer + paste-buffer` for anything untrusted or complex.
|
|
240
|
-
- **Do not poll `capture-pane` as your primary done-signal.** Use the sentinel. `capture-pane` is for content retrieval, not lifecycle.
|
|
241
|
-
- **Do not kill the session with `C-c` if you can avoid it.** `/exit` is cleaner — it gives Claude Code time to flush the JSONL.
|
|
242
|
-
- **Do not assume `tmux has-session` returning success means claude is responsive.** A session can exist while claude is wedged. Pair with a wall-clock budget.
|
|
243
|
-
- **Do not `rm -rf /tmp/cc-<id>` instead of `git worktree remove`.** Pure rm leaves orphan refs in `/agent/.git/worktrees/cc-<id>/` and a dangling branch. The next delegation with the same id will fail with "branch already exists".
|