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,92 +0,0 @@
|
|
|
1
|
-
# Stop hook — schema and gotchas (Codex CLI)
|
|
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
|
-
Codex CLI ships a hook system that closely mirrors Claude Code's. Events relevant to delegation:
|
|
8
|
-
|
|
9
|
-
- **`Stop`** — fires every time the main agent finishes responding. Per-turn, not per-session. A 5-turn conversation fires `Stop` five times. The "task is done" signal is just "the latest Stop, where codex's message looks like a result not a question" — that's the multi-turn decision loop in `SKILL.md`.
|
|
10
|
-
- **`SessionStart`** — fires once when the session begins. The pre-baked `typeclaw-cx-session-start-hook` uses this to write `$PWD/.session-id` so the operator learns the session UUID before any Stop fires.
|
|
11
|
-
- **`SubagentStop`** — fires when a Codex subagent (Task tool invocation, plan-mode subagents) finishes. Sub-agents are codex spawning codex. You don't typically need to handle this — the parent's `Stop` fires after its subagents are done. Configure it only if you want progress signals during a subagent-heavy turn.
|
|
12
|
-
|
|
13
|
-
Other hooks that Codex CLI supports (`PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `PreCompact`, `PostCompact`, 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.
|
|
14
|
-
|
|
15
|
-
## Stop event JSON schema
|
|
16
|
-
|
|
17
|
-
The hook command receives a single JSON object on stdin. Fields observed in current Codex CLI (subject to upstream churn — the docs page is at `developers.openai.com/codex/hooks`):
|
|
18
|
-
|
|
19
|
-
```jsonc
|
|
20
|
-
{
|
|
21
|
-
"session_id": "abc123…",
|
|
22
|
-
"transcript_path": "/root/.codex/sessions/abc123.jsonl",
|
|
23
|
-
"cwd": "/tmp/cx-foo",
|
|
24
|
-
"model": "gpt-5.5",
|
|
25
|
-
"hook_event_name": "Stop",
|
|
26
|
-
"last_assistant_message": "…",
|
|
27
|
-
"turn_id": "tu_xyz",
|
|
28
|
-
}
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Fields you actually use:
|
|
32
|
-
|
|
33
|
-
- **`last_assistant_message`** — your primary capture for the multi-turn decision loop. Read this from `sentinel.json`, classify (question / permission / result / spurious), act.
|
|
34
|
-
- **`transcript_path`** — points at the JSONL with the full conversation. Useful when `last_assistant_message` isn't enough.
|
|
35
|
-
- **`cwd`** — sanity check. If this isn't `/tmp/cx-<id>`, something is wrong with your tmux spawn (likely missing `-c`).
|
|
36
|
-
- **`session_id`** — useful for logging or if you want to correlate with the JSONL filename. Already extracted into the sentinel filename by the hook.
|
|
37
|
-
- **`turn_id`** — Codex-specific (no equivalent in Claude Code's payload). Useful for correlating a Stop event with the specific assistant turn in the JSONL.
|
|
38
|
-
|
|
39
|
-
Fields you ignore:
|
|
40
|
-
|
|
41
|
-
- `model`, `hook_event_name` — fixed-per-session metadata; not useful for lifecycle decisions.
|
|
42
|
-
|
|
43
|
-
## The transcript JSONL
|
|
44
|
-
|
|
45
|
-
`transcript_path` points at a JSONL file with one JSON object per line. Codex's JSONL is similar in shape to Claude Code's but the type tags differ. Per OpenAI's docs, expect events of the form:
|
|
46
|
-
|
|
47
|
-
- **`{ "type": "thread.started", "thread_id": "..." }`** — session boot.
|
|
48
|
-
- **`{ "type": "turn.started" }`** — a new agent turn.
|
|
49
|
-
- **`{ "type": "turn.completed", "usage": { ... } }`** — turn ended.
|
|
50
|
-
- **`{ "type": "item.started", "item": { "type": "agent_message" | "tool_call" | ..., ... } }`** — a content/tool item began.
|
|
51
|
-
- **`{ "type": "item.completed", "item": { "id": "...", "type": "agent_message", "text": "..." } }`** — a content item finished.
|
|
52
|
-
- **`{ "type": "error", ... }`** — an error item.
|
|
53
|
-
|
|
54
|
-
To extract codex's final text answer when `last_assistant_message` isn't enough:
|
|
55
|
-
|
|
56
|
-
```sh
|
|
57
|
-
jq -r 'select(.type == "item.completed") | .item | select(.type == "agent_message") | .text' "$transcript_path"
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
The exact field names and item types may drift between Codex versions — confirm against `developers.openai.com/codex/noninteractive` (which documents the JSONL schema for `codex exec --json`, the same event types).
|
|
61
|
-
|
|
62
|
-
## Documented race conditions
|
|
63
|
-
|
|
64
|
-
Race conditions in Codex CLI's hook system aren't as well-documented as Claude Code's (which has a richer GitHub-issues catalog). The hook's own design — temp-file-then-rename for atomic sentinel writes, `.done` touch after the rename, per-session filenames — already defends against the main classes of race the Claude Code hook surfaces in #15813, #20612, etc. Treat these as defense-in-depth:
|
|
65
|
-
|
|
66
|
-
1. **Stale transcript on Stop**: the hook payload's `last_assistant_message` field carries the same content the JSONL eventually flushes, so prefer it over a re-read of `transcript_path` immediately on hook fire. Wait 1–2 seconds before reading the JSONL if you need it.
|
|
67
|
-
2. **Missing transcript file**: rare in observed practice, but possible during heavy concurrent invocations. Mitigation: capture `last_assistant_message` on every Stop and accumulate it yourself if you need the full history.
|
|
68
|
-
3. **Token-count drift**: Codex's `turn.completed` usage field has been observed to underreport `output_tokens` in some streaming edge cases (similar to Claude Code's #27361). Don't rely on JSONL token counts for cost calculations; the OpenAI dashboard is the authoritative source.
|
|
69
|
-
|
|
70
|
-
## Permission prompts vs Stop
|
|
71
|
-
|
|
72
|
-
Codex CLI's default `approval_policy` is `on-request`: the model asks for permission before each tool with side effects, and the user (you, via tmux) answers. **Permission prompts do not fire `Stop`** — when codex is waiting for a "Allow this command?" yes/no, the turn isn't over.
|
|
73
|
-
|
|
74
|
-
- **Permission prompt appears** → no `Stop`, no `.done`, you keep polling.
|
|
75
|
-
- **You answer the prompt** (via `tmux send-keys "y" Enter`) → codex continues, eventually finishes its turn → `Stop` fires.
|
|
76
|
-
|
|
77
|
-
The multi-turn loop's classification looks for content-level questions (questions codex wrote as part of its response), not permission-tool prompts. Permission prompts only appear in the pane, not in `last_assistant_message`.
|
|
78
|
-
|
|
79
|
-
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. This is risky to automate. 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.
|
|
80
|
-
|
|
81
|
-
**Alternative — bypass permissions for vetted automation.** If you want codex to run without per-tool prompts (because the worktree is sandboxed and you've vetted the task), pass `--ask-for-approval never --sandbox workspace-write` to `codex` on spawn. This is the Codex equivalent of "give the agent unattended tool access for this delegation"; use sparingly and only when the worktree's worst-case blast radius is bounded.
|
|
82
|
-
|
|
83
|
-
## Things you must not do with the Stop hook
|
|
84
|
-
|
|
85
|
-
- **Do not write a per-worktree `~/.codex/hooks.json` from operator code.** The hook is pre-baked into the image at build time (see `src/init/dockerfile.ts`, constants `TYPECLAW_CX_STOP_HOOK_PATH` and `TYPECLAW_CX_GLOBAL_HOOKS`) precisely so the operator subagent never has to construct that JSON itself. The shape is identical to Claude Code's `settings.json` hooks block (deliberately — same nesting, same exec-form via `args: []`), but Codex's parser silently ignores unknown keys the same way Claude's does. Wrong-shape configs disable the done-signal and burn the polling loop's wall-clock budget. If you ever find yourself wanting to write a per-worktree hooks 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.
|
|
86
|
-
- **Do not edit the in-Dockerfile hook config in a way that bypasses `JSON.stringify` + the regression test.** `TYPECLAW_CX_GLOBAL_HOOKS` 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.
|
|
87
|
-
- **Do not set the Stop 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.
|
|
88
|
-
- **Do not put long-running commands in the hook.** The hook runs synchronously on the Codex CLI 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.
|
|
89
|
-
- **Do not skip the temp-file rename pattern.** Writing `sentinel.json` directly with `>` lets readers see partial JSON if they poll mid-write. Always temp-then-rename. The pre-baked hook script already does this — don't replace it with a per-worktree variant.
|
|
90
|
-
- **Do not delete `transcript_path` from inside the hook.** The path is shared with `SessionEnd` and other lifecycle events; deleting it breaks downstream hooks.
|
|
91
|
-
- **Do not log the full hook payload to a place you don't control.** It contains `last_assistant_message`, which can contain anything codex said — including code, secrets the user pasted, or private context. Sentinel is fine (it's in `/tmp/`); piping to a shared log is not.
|
|
92
|
-
- **Do not assume the JSONL event-type names are identical to Claude Code's.** They're shaped similarly but differ (`item.completed` vs `assistant`/`content[].type`). When extracting content from the JSONL, write Codex-specific `jq` filters; don't reuse Claude Code's.
|
|
@@ -1,239 +0,0 @@
|
|
|
1
|
-
# Tmux driving — full reference (Codex CLI)
|
|
2
|
-
|
|
3
|
-
Deep dive for driving `codex` (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 codex isn't responsive" situation.
|
|
4
|
-
|
|
5
|
-
The shape of this reference is intentionally a mirror of `typeclaw-claude-code`'s `references/tmux-driving.md`. The differences are noted inline; everything not flagged is the same.
|
|
6
|
-
|
|
7
|
-
## Why tmux
|
|
8
|
-
|
|
9
|
-
The agent process has no TTY. `codex` (interactive) is a TUI built on `ratatui` + `crossterm` that uses raw terminal modes — it reads stdin one byte at a time with echo off, draws with ANSI escapes, and refuses to start sensibly if stdin/stdout aren't terminals. Piping into `codex` doesn't work; the CLI detects the absence of a TTY and either falls back to non-interactive semantics or fails outright.
|
|
10
|
-
|
|
11
|
-
`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).
|
|
12
|
-
|
|
13
|
-
## Why `/tmp/cx-<id>` and not `workspace/cx-<id>`
|
|
14
|
-
|
|
15
|
-
Same reasoning as Claude Code's `cc-<id>`:
|
|
16
|
-
|
|
17
|
-
1. **Worktree-vs-scratch:** the `cx-<id>` directory is a real git checkout managed by `git worktree`, with refs in `/agent/.git/worktrees/cx-<id>/`. Putting it under `workspace/` would mean the agent folder contains a worktree of itself, which works mechanically but is recursive and confusing.
|
|
18
|
-
2. **The global SessionStart and Stop hooks write their per-session files into cwd.** Both hook scripts read `$PWD` (the literal cwd Codex CLI 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/cx-<id>` sets codex's cwd there.
|
|
19
|
-
3. **The worktree IS the codebase.** Codex can read every file at `HEAD` directly — it doesn't need a separate scratch area.
|
|
20
|
-
|
|
21
|
-
The `cx-` prefix (vs Claude Code's `cc-`) keeps the two CLIs' worktrees, branches, and tmux sessions in parallel namespaces. An agent running both can delegate concurrently without collision; `git worktree list` shows both kinds clearly; `tmux ls` is unambiguous.
|
|
22
|
-
|
|
23
|
-
## Spawning the session
|
|
24
|
-
|
|
25
|
-
The canonical spawn (per `SKILL.md`):
|
|
26
|
-
|
|
27
|
-
```sh
|
|
28
|
-
tmux new-session -d -s cx-<task-id> -c /tmp/cx-<task-id> codex
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Flags worth knowing:
|
|
32
|
-
|
|
33
|
-
- `-d` — detached. The session runs in the background; your shell doesn't attach.
|
|
34
|
-
- `-s cx-<task-id>` — explicit session name. Required. Without `-s`, tmux picks `0`, `1`, … and a sibling delegation will clobber yours.
|
|
35
|
-
- `-c /tmp/cx-<task-id>` — start directory. Must be the worktree path. The global Stop hook at `~/.codex/hooks.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.
|
|
36
|
-
- `codex` — the command. Just `codex`, not `codex exec`. The interactive TUI is the whole point.
|
|
37
|
-
|
|
38
|
-
Common mistakes:
|
|
39
|
-
|
|
40
|
-
- 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/cx-<id>/`, and the loop times out at its wall-clock budget. Worse: codex in `/agent` operates on the live working tree instead of the worktree.
|
|
41
|
-
- Passing flags Codex CLI doesn't recognize. Codex is a Rust binary with a strict clap parser — unknown flags fail at startup, not silently.
|
|
42
|
-
|
|
43
|
-
### Alternate-screen vs inline mode
|
|
44
|
-
|
|
45
|
-
Codex CLI's TUI defaults to **alternate-screen mode** (the same mode `vim` uses) — it takes over the entire terminal and restores the previous screen on exit. This means `tmux capture-pane -S -` only captures what's currently visible, not the full conversation history.
|
|
46
|
-
|
|
47
|
-
For our workflow this is fine: we use the Stop sentinel as the done-signal, not pane-content parsing. But if you ever need to capture the full TUI history (e.g. for a post-mortem when the JSONL is missing), spawn codex with `--no-alt-screen`:
|
|
48
|
-
|
|
49
|
-
```sh
|
|
50
|
-
tmux new-session -d -s cx-<id> -c /tmp/cx-<id> codex --no-alt-screen
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
`--no-alt-screen` runs the TUI inline, preserving terminal scrollback. The trade-off is that the rendering is slightly less stable (the TUI's redraws collide with normal scrollback flow), but `capture-pane -S -` will then see the full history.
|
|
54
|
-
|
|
55
|
-
Default to alternate-screen mode (no flag); reach for `--no-alt-screen` only when you genuinely need scrollback capture for debugging.
|
|
56
|
-
|
|
57
|
-
## The init wait
|
|
58
|
-
|
|
59
|
-
`codex` prints a brief Welcome animation, then renders its TUI. The animation takes ~1 second; after that the input composer appears immediately if no dialogs fire, or one or more dialog modals appear in sequence. You must wait for the input composer (and clear any dialogs) before sending the first prompt.
|
|
60
|
-
|
|
61
|
-
The skill body's flow uses dialog-polling rather than a fixed sleep: every 500ms, `tmux capture-pane -t cx-<id> -p -S -15` and check for the input composer (bottom-of-pane prompt indicator) OR a known dialog (Auth picker / TrustDirectory / hook trust). Clear dialogs as they appear, exit the loop when the input composer is visible. Give up after ~10s and surface to the user.
|
|
62
|
-
|
|
63
|
-
Unlike Claude Code, Codex's `.session-id` IS a reliable readiness signal in most cases: Codex's SessionStart hook does NOT get suppressed while the TrustDirectory dialog is pending (different upstream architecture than Claude Code's #11519 issue). The fast path — read `.session-id` after ~1 second — usually wins. But the dialog-polling loop is still required to clear TrustDirectory before sending the first prompt; otherwise the prompt is interpreted as a dialog answer.
|
|
64
|
-
|
|
65
|
-
## Sending input
|
|
66
|
-
|
|
67
|
-
```sh
|
|
68
|
-
tmux send-keys -t cx-<id> "<text>" Enter
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
Notes:
|
|
72
|
-
|
|
73
|
-
- **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`:
|
|
74
|
-
|
|
75
|
-
```sh
|
|
76
|
-
echo "<prompt>" > prompt.txt
|
|
77
|
-
tmux load-buffer -t cx-<id> prompt.txt
|
|
78
|
-
tmux paste-buffer -t cx-<id>
|
|
79
|
-
tmux send-keys -t cx-<id> Enter
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
- **Bracketed paste is enabled** by default in Codex's TUI (`EnableBracketedPaste` in `tui.rs`), so `paste-buffer` content arrives intact even with newlines.
|
|
83
|
-
|
|
84
|
-
- **`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). Codex's composer also honors `Ctrl-M` as submit (configurable per `tui.keymap.composer.submit` in `~/.codex/config.toml`, but our flow assumes the default).
|
|
85
|
-
|
|
86
|
-
- **Multi-line prompts**: send the body, then `Enter`. Codex's composer treats Enter as submit by default, so newlines in your text become submitted lines. For genuinely multi-line input, use the paste-buffer flow above — bracketed paste passes the newlines through to the composer's input buffer without submitting until you press Enter explicitly.
|
|
87
|
-
|
|
88
|
-
## Discovering `cx_session_id` and polling for `.done-<session_id>`
|
|
89
|
-
|
|
90
|
-
Same edge-triggered polling pattern as Claude Code. Track which sentinels you've already processed by UUID; on every poll, enumerate ALL `.done-*` files, ignore the ones you've already processed, and pick the **newest by mtime** of what remains.
|
|
91
|
-
|
|
92
|
-
### Phase 1 — first-turn discovery
|
|
93
|
-
|
|
94
|
-
Fast path: after spawning codex and waiting ~1s, check `/tmp/cx-<id>/.session-id`. If it exists and contains a real UUID, that's `cx_session_id`. Otherwise fall through to the same first-turn polling as Claude Code (translate to your tool calls; the shell snippet is illustrative):
|
|
95
|
-
|
|
96
|
-
```sh
|
|
97
|
-
budget=600
|
|
98
|
-
elapsed=0
|
|
99
|
-
processed=""
|
|
100
|
-
cx_session_id=""
|
|
101
|
-
# Fast path
|
|
102
|
-
if [ -f /tmp/cx-<id>/.session-id ]; then
|
|
103
|
-
candidate="$(cat /tmp/cx-<id>/.session-id 2>/dev/null)"
|
|
104
|
-
case "$candidate" in
|
|
105
|
-
[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-*) cx_session_id="$candidate" ;;
|
|
106
|
-
malformed) echo "SessionStart fired but session_id was bad" ; exit 1 ;;
|
|
107
|
-
esac
|
|
108
|
-
fi
|
|
109
|
-
# Discovery path (fallback or wait for the first Stop)
|
|
110
|
-
while [ -z "$cx_session_id" ]; do
|
|
111
|
-
newest=""
|
|
112
|
-
for f in $(ls -t /tmp/cx-<id>/.done-* 2>/dev/null); do
|
|
113
|
-
[ -f "$f" ] || continue
|
|
114
|
-
uuid="${f##*/.done-}"
|
|
115
|
-
case " $processed " in *" $uuid "*) continue ;; esac
|
|
116
|
-
if [ "$uuid" = "malformed" ]; then
|
|
117
|
-
malformed_fallback="$f"
|
|
118
|
-
continue
|
|
119
|
-
fi
|
|
120
|
-
newest="$f"
|
|
121
|
-
cx_session_id="$uuid"
|
|
122
|
-
break
|
|
123
|
-
done
|
|
124
|
-
if [ -n "$cx_session_id" ]; then break; fi
|
|
125
|
-
if [ -n "${malformed_fallback:-}" ]; then
|
|
126
|
-
echo "Stop hook fired but couldn't extract a UUID-shape session_id"
|
|
127
|
-
exit 1
|
|
128
|
-
fi
|
|
129
|
-
if [ "$elapsed" -ge "$budget" ]; then echo "Timeout reached"; break; fi
|
|
130
|
-
if ! tmux has-session -t cx-<id> 2>/dev/null; then echo "tmux session died"; break; fi
|
|
131
|
-
sleep 0.5
|
|
132
|
-
elapsed=$((elapsed + 1))
|
|
133
|
-
done
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
### Phase 2 — per-turn polling (turns 2 onward)
|
|
137
|
-
|
|
138
|
-
Same shape as Claude Code's phase 2. `processed` carries over from phase 1; add the just-consumed UUID before entering phase 2. On every iteration, glob `.done-*`, pick newest unprocessed real-UUID, update `cx_session_id` if it differs (rotation), read the sentinel, `rm` ONLY the specific `.done-<uuid>` you processed.
|
|
139
|
-
|
|
140
|
-
```sh
|
|
141
|
-
budget=600
|
|
142
|
-
elapsed=0
|
|
143
|
-
processed="$processed $cx_session_id"
|
|
144
|
-
new_sid=""
|
|
145
|
-
while [ -z "$new_sid" ]; do
|
|
146
|
-
for f in $(ls -t /tmp/cx-<id>/.done-* 2>/dev/null); do
|
|
147
|
-
[ -f "$f" ] || continue
|
|
148
|
-
uuid="${f##*/.done-}"
|
|
149
|
-
case " $processed " in *" $uuid "*) continue ;; esac
|
|
150
|
-
if [ "$uuid" = "malformed" ]; then echo "bad session_id"; exit 1; fi
|
|
151
|
-
new_sid="$uuid"
|
|
152
|
-
break
|
|
153
|
-
done
|
|
154
|
-
if [ -n "$new_sid" ]; then break; fi
|
|
155
|
-
if [ "$elapsed" -ge "$budget" ]; then echo "Timeout"; break; fi
|
|
156
|
-
if ! tmux has-session -t cx-<id> 2>/dev/null; then echo "tmux died"; break; fi
|
|
157
|
-
sleep 0.5
|
|
158
|
-
elapsed=$((elapsed + 1))
|
|
159
|
-
done
|
|
160
|
-
|
|
161
|
-
if [ "$new_sid" != "$cx_session_id" ]; then
|
|
162
|
-
echo "Detected session_id rotation: ${cx_session_id} → ${new_sid}"
|
|
163
|
-
cx_session_id="$new_sid"
|
|
164
|
-
fi
|
|
165
|
-
cat "/tmp/cx-<id>/sentinel-${cx_session_id}.json"
|
|
166
|
-
rm -f "/tmp/cx-<id>/.done-${cx_session_id}"
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
### Why edge-triggered, not level-triggered
|
|
170
|
-
|
|
171
|
-
Same reasoning as Claude Code. Level-triggered polling on a fixed `.done-<sid>` filename breaks on session rotation and on the "old marker still exists when new one arrives" race. Newest-by-mtime + processed-set is the only correct pattern.
|
|
172
|
-
|
|
173
|
-
### Why 500ms cadence
|
|
174
|
-
|
|
175
|
-
- Faster polling (50–100ms) wastes CPU and is invisible to the user.
|
|
176
|
-
- Slower polling (2s+) adds visible latency.
|
|
177
|
-
- 500ms is the sweet spot — same calibration as Claude Code, same reasoning.
|
|
178
|
-
|
|
179
|
-
### Session-died recovery
|
|
180
|
-
|
|
181
|
-
`tmux has-session` returns non-zero when the session is gone. Three reasons:
|
|
182
|
-
|
|
183
|
-
1. **Codex crashed**: panic, segfault. `capture-pane` before tmux GC'd would show the panic message.
|
|
184
|
-
2. **Auth failed**: `codex` exited cleanly with "Unauthorized" or similar. Pane would have shown the error briefly.
|
|
185
|
-
3. **User killed it externally**: someone ran `tmux kill-session -t cx-<id>` outside your control.
|
|
186
|
-
|
|
187
|
-
Recovery: surface to the user with whatever you have — `git diff main..cx-<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/cx-<id>` + `git branch -D cx-<id>`. Ask whether to retry.
|
|
188
|
-
|
|
189
|
-
## Capturing the pane (fallback path)
|
|
190
|
-
|
|
191
|
-
When the JSONL is missing or you need to see what the TUI showed:
|
|
192
|
-
|
|
193
|
-
```sh
|
|
194
|
-
tmux capture-pane -t cx-<id> -p -S - -E -
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
Flags:
|
|
198
|
-
|
|
199
|
-
- `-p` — print to stdout.
|
|
200
|
-
- `-S -` — start from the beginning of the scrollback.
|
|
201
|
-
- `-E -` — end at the current line.
|
|
202
|
-
|
|
203
|
-
If codex was spawned in alternate-screen mode (the default), `-S -` only captures the current screen. For full history, spawn with `--no-alt-screen`.
|
|
204
|
-
|
|
205
|
-
### ANSI gotchas
|
|
206
|
-
|
|
207
|
-
- **Codex uses crossterm + ratatui** with bracketed paste, focus tracking, and keyboard enhancement modes enabled. Captures will contain ANSI escapes for color, cursor positioning, and bracketed-paste markers (`\x1b[200~` / `\x1b[201~`).
|
|
208
|
-
- **Progress indicators** in Codex's tool-use UI redraw in place. Captures show the final state of each cell.
|
|
209
|
-
- **Box-drawing characters** for input frames are Unicode (`╭ ╮ ╰ ╯ │ ─`). Preserve as UTF-8.
|
|
210
|
-
- **Color codes**: standard 8-color and 256-color. Strip with `s/\x1b\[[0-9;]*[a-zA-Z]//g` if you need plain text.
|
|
211
|
-
|
|
212
|
-
## Cleaning up
|
|
213
|
-
|
|
214
|
-
```sh
|
|
215
|
-
tmux send-keys -t cx-<id> "/exit" Enter
|
|
216
|
-
sleep 1
|
|
217
|
-
tmux kill-session -t cx-<id> 2>/dev/null || true
|
|
218
|
-
git -C /agent worktree remove --force /tmp/cx-<id>
|
|
219
|
-
git -C /agent branch -D cx-<id>
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
- `/exit` is Codex CLI's built-in exit command. Cleaner than `C-c` — it lets the CLI flush the JSONL and close cleanly.
|
|
223
|
-
- `sleep 1` gives the CLI time to flush. Skip it and you may lose the last few JSONL lines.
|
|
224
|
-
- `kill-session ... || true` because the session may have already exited cleanly after `/exit`.
|
|
225
|
-
- `worktree remove --force` because the working tree has un-cherry-picked changes. `--force` is correct here because we're explicitly discarding.
|
|
226
|
-
- `branch -D` to delete the throwaway branch.
|
|
227
|
-
|
|
228
|
-
## Things you must not do in tmux driving
|
|
229
|
-
|
|
230
|
-
- **Do not omit `-s <name>` on `new-session`.** Anonymous sessions race across delegations.
|
|
231
|
-
- **Do not omit `-c /tmp/cx-<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: codex in `/agent` operates on the live working tree instead of the worktree.
|
|
232
|
-
- **Do not skip the init wait.** Sending input before the TUI is ready loses the input silently — or worse, the input lands inside a dialog modal and gets interpreted as a yes/no answer.
|
|
233
|
-
- **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.
|
|
234
|
-
- **Do not poll `capture-pane` as your primary done-signal.** Use the sentinel. `capture-pane` is for content retrieval, not lifecycle.
|
|
235
|
-
- **Do not kill the session with `C-c` if you can avoid it.** `/exit` is cleaner.
|
|
236
|
-
- **Do not assume `tmux has-session` returning success means codex is responsive.** A session can exist while codex is wedged. Pair with a wall-clock budget.
|
|
237
|
-
- **Do not `rm -rf /tmp/cx-<id>` instead of `git worktree remove`.** Pure rm leaves orphan refs and a dangling branch.
|
|
238
|
-
- **Do not mix `cx-` and `cc-` prefixes within one delegation.** They're parallel namespaces by design — Codex sessions use `cx-`, Claude Code sessions use `cc-`. Cross-using leaves orphans in both worktree lists.
|
|
239
|
-
- **Do not pass `codex --no-alt-screen` reflexively.** Alternate-screen mode is the default for good reason (cleaner TUI rendering). Reach for the flag only when you need full-scrollback capture for debugging.
|