typeclaw 0.51.0 → 0.52.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/bash-sandbox-env.d.ts +2 -0
- package/dist/types/agent/bash-sandbox.d.ts +4 -0
- package/dist/types/agent/index.d.ts +5 -0
- package/dist/types/agent/multimodal/look-at.d.ts +1 -1
- package/dist/types/agent/plugin-tools.d.ts +4 -0
- package/dist/types/agent/prompt-cache-key.d.ts +1 -0
- package/dist/types/agent/session-tail.d.ts +12 -0
- package/dist/types/agent/subagents.d.ts +5 -0
- package/dist/types/agent/system-prompt-composition.d.ts +1 -0
- package/dist/types/agent/system-prompt.d.ts +2 -0
- package/dist/types/agent/tools/channel-disengage.d.ts +1 -1
- package/dist/types/agent/tools/channel-edit.d.ts +1 -1
- package/dist/types/agent/tools/channel-fetch-attachment.d.ts +1 -1
- package/dist/types/agent/tools/channel-handoff.d.ts +1 -1
- package/dist/types/agent/tools/channel-history.d.ts +1 -1
- package/dist/types/agent/tools/channel-react.d.ts +1 -1
- package/dist/types/agent/tools/channel-read.d.ts +10 -2
- package/dist/types/agent/tools/channel-reply.d.ts +1 -1
- package/dist/types/agent/tools/channel-send.d.ts +1 -1
- package/dist/types/agent/tools/channel-session-search.d.ts +1 -1
- package/dist/types/agent/tools/grant-role.d.ts +1 -1
- package/dist/types/agent/tools/post-github-review.d.ts +1 -1
- package/dist/types/agent/tools/restart.d.ts +1 -1
- package/dist/types/agent/tools/skip-response.d.ts +1 -1
- package/dist/types/agent/tools/spawn-subagent.d.ts +2 -1
- package/dist/types/agent/tools/stream-snapshot.d.ts +1 -1
- package/dist/types/agent/tools/subagent-cancel.d.ts +1 -1
- package/dist/types/agent/tools/subagent-output.d.ts +1 -1
- package/dist/types/agent/tools/todo/index.d.ts +1 -1
- package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +3 -3
- package/dist/types/agent/tools/webfetch/strategies/readability-process.d.ts +48 -0
- package/dist/types/agent/tools/webfetch/tool.d.ts +2 -2
- package/dist/types/agent/tools/websearch.d.ts +1 -1
- package/dist/types/channels/adapters/github/auth-app.d.ts +25 -0
- package/dist/types/channels/adapters/github/auth-pat.d.ts +17 -0
- package/dist/types/channels/adapters/github/auth.d.ts +24 -0
- package/dist/types/channels/github-token-bridge.d.ts +4 -0
- package/dist/types/channels/lost-background-context.d.ts +2 -0
- package/dist/types/channels/persistence.d.ts +1 -0
- package/dist/types/channels/router.d.ts +5 -1
- package/dist/types/channels/types.d.ts +1 -0
- package/dist/types/coding-agent/tool.d.ts +1 -1
- package/dist/types/config/config.d.ts +20 -11
- package/dist/types/config/providers.d.ts +47 -0
- package/dist/types/eval/sandbox.d.ts +2 -0
- package/dist/types/git/resolve-identity.d.ts +2 -0
- package/dist/types/init/dockerfile.d.ts +1 -0
- package/dist/types/init/gitignore.d.ts +1 -1
- package/dist/types/permissions/builtins.d.ts +1 -0
- package/dist/types/plugin/types.d.ts +3 -0
- package/dist/types/sandbox/canonical-secrets.d.ts +2 -2
- package/dist/types/sandbox/coding-agent.d.ts +1 -1
- package/dist/types/sandbox/dependency-bins.d.ts +1 -0
- package/dist/types/sandbox/dev-source.d.ts +2 -2
- package/dist/types/sandbox/hidden-paths.d.ts +1 -0
- package/dist/types/sandbox/index.d.ts +1 -1
- package/dist/types/sandbox/policy.d.ts +3 -0
- package/dist/types/typevault/cli-path.d.ts +2 -0
- package/dist/types/typevault/envelope-store.d.ts +11 -0
- package/dist/types/typevault/lifecycle.d.ts +13 -0
- package/dist/types/typevault/vault.d.ts +27 -0
- package/package.json +8 -7
- package/scripts/test.ts +252 -0
- package/src/agent/bash-sandbox-env.ts +33 -1
- package/src/agent/bash-sandbox.ts +20 -6
- package/src/agent/index.ts +120 -31
- package/src/agent/multimodal/look-at.ts +1 -1
- package/src/agent/plugin-tools.ts +35 -1
- package/src/agent/prompt-cache-key.ts +26 -3
- package/src/agent/session-origin.ts +39 -18
- package/src/agent/session-tail.ts +28 -0
- package/src/agent/subagents.ts +21 -2
- package/src/agent/system-prompt-composition.ts +18 -0
- package/src/agent/system-prompt.ts +39 -1
- package/src/agent/tool-error-remediation.ts +18 -3
- package/src/agent/tools/channel-disengage.ts +1 -1
- package/src/agent/tools/channel-edit.ts +1 -1
- package/src/agent/tools/channel-fetch-attachment.ts +1 -1
- package/src/agent/tools/channel-handoff.ts +3 -2
- package/src/agent/tools/channel-history.ts +2 -1
- package/src/agent/tools/channel-react.ts +1 -1
- package/src/agent/tools/channel-read.ts +36 -3
- package/src/agent/tools/channel-reply.ts +1 -1
- package/src/agent/tools/channel-send.ts +4 -3
- package/src/agent/tools/channel-session-search.ts +13 -4
- package/src/agent/tools/grant-role.ts +1 -1
- package/src/agent/tools/post-github-review.ts +1 -1
- package/src/agent/tools/restart.ts +1 -1
- package/src/agent/tools/skip-response.ts +1 -1
- package/src/agent/tools/spawn-subagent.ts +15 -1
- package/src/agent/tools/stream-snapshot.ts +1 -1
- package/src/agent/tools/subagent-cancel.ts +1 -1
- package/src/agent/tools/subagent-output.ts +1 -1
- package/src/agent/tools/todo/index.ts +1 -1
- package/src/agent/tools/webfetch/adaptive-html.ts +6 -4
- package/src/agent/tools/webfetch/strategies/readability-child.ts +25 -0
- package/src/agent/tools/webfetch/strategies/readability-process.ts +185 -0
- package/src/agent/tools/webfetch/tool.ts +6 -5
- package/src/agent/tools/websearch.ts +1 -1
- package/src/browser/dockerfile.ts +1 -1
- package/src/browser/fill-secret.ts +92 -35
- package/src/browser/registry.ts +6 -6
- package/src/bundled-plugins/agent-messenger-cli-auth/command.ts +211 -0
- package/src/bundled-plugins/agent-messenger-cli-auth/index.ts +186 -0
- package/src/bundled-plugins/backup/index.ts +17 -2
- package/src/bundled-plugins/backup/runner.ts +37 -2
- package/src/bundled-plugins/browser-agent/browser-agent.ts +51 -14
- package/src/bundled-plugins/browser-agent/index.ts +12 -5
- package/src/bundled-plugins/managed-browser/index.ts +25 -2
- package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +13 -5
- package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +56 -5
- package/src/bundled-plugins/memory/README.md +23 -2
- package/src/bundled-plugins/memory/append-fragment.ts +133 -0
- package/src/bundled-plugins/memory/append-tool.ts +80 -149
- package/src/bundled-plugins/memory/dreaming.ts +2 -0
- package/src/bundled-plugins/memory/index.ts +33 -6
- package/src/bundled-plugins/memory/memory-logger.ts +133 -11
- package/src/bundled-plugins/memory/references/store-reference-tool.ts +56 -32
- package/src/bundled-plugins/memory/remember-tool.ts +81 -0
- package/src/bundled-plugins/memory/search-tool-hybrid.ts +91 -0
- package/src/bundled-plugins/memory/search-tool.ts +58 -12
- package/src/bundled-plugins/memory/stream-events.ts +2 -0
- package/src/bundled-plugins/memory/transcript-cursor.ts +30 -0
- package/src/bundled-plugins/memory/transcript-preload.ts +131 -26
- package/src/bundled-plugins/memory/transcript-view.ts +36 -0
- package/src/bundled-plugins/memory/watermark.ts +19 -10
- package/src/bundled-plugins/reviewer/reviewer.ts +20 -0
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +3 -6
- package/src/bundled-plugins/security/policies/outbound-text.ts +20 -0
- package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -7
- package/src/bundled-plugins/typevault/grants.ts +119 -0
- package/src/bundled-plugins/typevault/index.ts +152 -0
- package/src/bundled-plugins/typevault/request.ts +87 -0
- package/src/bundled-plugins/typevault/runtime.ts +45 -0
- package/src/bundled-plugins/typevault/skills/typevault/SKILL.md +65 -0
- package/src/channels/adapter-halt.ts +17 -0
- package/src/channels/adapters/github/history.ts +23 -2
- package/src/channels/adapters/github/inbound.ts +60 -1
- package/src/channels/adapters/github/index.ts +27 -5
- package/src/channels/adapters/github/reconcile-open-prs.ts +7 -1
- package/src/channels/adapters/kakaotalk-author-resolver.ts +7 -5
- package/src/channels/adapters/kakaotalk-channel-resolver.ts +45 -15
- package/src/channels/adapters/kakaotalk-classify.ts +7 -9
- package/src/channels/adapters/kakaotalk-list.ts +62 -0
- package/src/channels/adapters/kakaotalk-member-cache.ts +67 -0
- package/src/channels/adapters/kakaotalk-membership.ts +27 -10
- package/src/channels/adapters/kakaotalk-mention.ts +61 -0
- package/src/channels/adapters/kakaotalk.ts +159 -125
- package/src/channels/adapters/teams-classify.ts +18 -8
- package/src/channels/github-token-bridge.ts +13 -0
- package/src/channels/lost-background-context.ts +46 -0
- package/src/channels/manager.ts +52 -3
- package/src/channels/persistence.ts +5 -0
- package/src/channels/router.ts +120 -21
- package/src/channels/schema.ts +1 -1
- package/src/channels/types.ts +3 -0
- package/src/coding-agent/tool.ts +1 -1
- package/src/config/config.ts +20 -1
- package/src/config/providers.ts +65 -0
- package/src/container/start.ts +15 -2
- package/src/doctor/channel-checks.ts +33 -0
- package/src/doctor/checks.ts +12 -2
- package/src/eval/sandbox.ts +3 -0
- package/src/eval/tool.ts +1 -0
- package/src/git/resolve-identity.ts +67 -2
- package/src/git/system-commit.ts +7 -0
- package/src/init/dockerfile.ts +5 -1
- package/src/init/gitignore.ts +3 -3
- package/src/init/index.ts +1 -0
- package/src/init/models-dev.ts +2 -0
- package/src/init/validate-api-key.ts +5 -0
- package/src/migrations/secrets-v1-to-v2.ts +2 -0
- package/src/permissions/builtins.ts +8 -0
- package/src/plugin/types.ts +6 -0
- package/src/run/bundled-plugins.ts +12 -0
- package/src/run/channel-session-factory.ts +3 -0
- package/src/run/index.ts +13 -2
- package/src/sandbox/build.ts +1 -0
- package/src/sandbox/canonical-secrets.ts +6 -0
- package/src/sandbox/dependency-bins.ts +13 -1
- package/src/sandbox/dev-source.ts +21 -12
- package/src/sandbox/hidden-paths.ts +1 -1
- package/src/sandbox/index.ts +1 -0
- package/src/sandbox/policy.ts +5 -0
- package/src/secrets/hydrate.ts +4 -1
- package/src/secrets/storage.ts +10 -1
- package/src/server/command-runner.ts +4 -0
- package/src/server/index.ts +8 -1
- package/src/skills/typeclaw-config/SKILL.md +16 -0
- package/src/skills/typeclaw-memory/SKILL.md +3 -1
- package/src/skills/typeclaw-permissions/SKILL.md +8 -8
- package/src/skills/typeclaw-troubleshooting/SKILL.md +18 -1
- package/src/tunnels/active.ts +14 -0
- package/src/typevault/bash-cli.ts +18 -0
- package/src/typevault/cli-path.ts +11 -0
- package/src/typevault/envelope-helper.ts +17 -0
- package/src/typevault/envelope-store.ts +98 -0
- package/src/typevault/lifecycle.ts +132 -0
- package/src/typevault/prompt-tunnel.ts +33 -0
- package/src/typevault/redaction.ts +37 -0
- package/src/typevault/vault.ts +283 -0
- package/typeclaw.schema.json +40 -10
package/src/run/index.ts
CHANGED
|
@@ -86,6 +86,8 @@ import { createSessionFactory, type SessionFactory } from '@/sessions'
|
|
|
86
86
|
import { createStream, type Stream } from '@/stream'
|
|
87
87
|
import { createTui as createTuiDefault, type TuiOptions } from '@/tui'
|
|
88
88
|
import { createTunnelManager, type TunnelManager, type TunnelManagerOptions } from '@/tunnels'
|
|
89
|
+
import { setActiveTunnelManager } from '@/tunnels/active'
|
|
90
|
+
import { runtimeTunnels } from '@/typevault/prompt-tunnel'
|
|
89
91
|
|
|
90
92
|
import { bootChannelRestartGreeting, bootBackgroundObligations } from './background-handoff-boot'
|
|
91
93
|
import { BUNDLED_PLUGINS } from './bundled-plugins'
|
|
@@ -444,13 +446,14 @@ async function startAgentRuntime(
|
|
|
444
446
|
})
|
|
445
447
|
|
|
446
448
|
const tunnelManager: TunnelManager = createTunnelManagerFor({
|
|
447
|
-
tunnels: getConfig()
|
|
449
|
+
tunnels: runtimeTunnels(getConfig()),
|
|
448
450
|
stream,
|
|
449
451
|
resolveChannelUpstreamPort: (name) => {
|
|
450
452
|
if (name === 'github') return getConfig().channels.github?.webhookPort ?? null
|
|
451
453
|
return null
|
|
452
454
|
},
|
|
453
455
|
})
|
|
456
|
+
setActiveTunnelManager(tunnelManager)
|
|
454
457
|
|
|
455
458
|
const legacyBackgroundHandoffs = new LegacyBackgroundHandoffReader(cwd, {
|
|
456
459
|
onError: (error) => console.warn(`[run] legacy background upgrade failed: ${error}`),
|
|
@@ -495,6 +498,7 @@ async function startAgentRuntime(
|
|
|
495
498
|
tunnelUrlForChannel: (name) => resolveTunnelUrlForChannel(name, tunnelManager),
|
|
496
499
|
tunnelConfiguredForChannel: (name) => isTunnelConfiguredForChannel(name),
|
|
497
500
|
createSessionForChannel: buildChannelSessionFactory({
|
|
501
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
498
502
|
cwd,
|
|
499
503
|
sessionFactory,
|
|
500
504
|
stream,
|
|
@@ -583,7 +587,8 @@ async function startAgentRuntime(
|
|
|
583
587
|
const allowBackgroundFromSubagent =
|
|
584
588
|
entry.pluginSubagent.canBackgroundSpawnSubagents === true && entry.pluginSubagent.canSpawnSubagents === true
|
|
585
589
|
const created = await createSessionWithDispose({
|
|
586
|
-
|
|
590
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
591
|
+
systemPromptOverride: subagentOptions?.systemPromptOverride ?? entry.pluginSubagent.systemPrompt,
|
|
587
592
|
sessionManager,
|
|
588
593
|
channelRouter: channelManager.router,
|
|
589
594
|
origin,
|
|
@@ -599,6 +604,7 @@ async function startAgentRuntime(
|
|
|
599
604
|
...(entry.pluginSubagent.tools ? { toolRefs: entry.pluginSubagent.tools } : {}),
|
|
600
605
|
...(entry.pluginSubagent.customTools ? { customTools: entry.pluginSubagent.customTools } : {}),
|
|
601
606
|
toolNamePrefix: `__plugin_${entry.pluginName}_${entry.subagentName}`,
|
|
607
|
+
...(entry.pluginSubagent.pluginTools ? { pluginToolNames: entry.pluginSubagent.pluginTools } : {}),
|
|
602
608
|
},
|
|
603
609
|
// Orchestration wiring is opt-in per subagent (canSpawnSubagents) so
|
|
604
610
|
// only operator/reviewer can delegate; explorer/scout/etc. stay leaves.
|
|
@@ -662,6 +668,7 @@ async function startAgentRuntime(
|
|
|
662
668
|
// attribution stay per-session).
|
|
663
669
|
const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
|
|
664
670
|
return defaultCreateSessionForSubagent(subagent, {
|
|
671
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
665
672
|
...subagentOptions,
|
|
666
673
|
plugins: {
|
|
667
674
|
registry: snap.registry,
|
|
@@ -739,6 +746,7 @@ async function startAgentRuntime(
|
|
|
739
746
|
origin,
|
|
740
747
|
prompt: (text: string) =>
|
|
741
748
|
runPromptForCommand({
|
|
749
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
742
750
|
text,
|
|
743
751
|
origin,
|
|
744
752
|
runtime: pluginRuntime,
|
|
@@ -783,6 +791,7 @@ async function startAgentRuntime(
|
|
|
783
791
|
console.error(`[cron] ${job.id}: clear todos failed: ${err instanceof Error ? err.message : String(err)}`),
|
|
784
792
|
)
|
|
785
793
|
const session = await createSession({
|
|
794
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
786
795
|
reloadRegistry,
|
|
787
796
|
sessionManager,
|
|
788
797
|
stream,
|
|
@@ -1054,6 +1063,7 @@ async function startAgentRuntime(
|
|
|
1054
1063
|
|
|
1055
1064
|
const commandRunnerFactory = (outbound: import('@/server/command-runner').CommandOutbound): CommandRunner =>
|
|
1056
1065
|
createCommandRunner({
|
|
1066
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
1057
1067
|
pluginRuntime,
|
|
1058
1068
|
permissions: pluginsLoaded.permissions,
|
|
1059
1069
|
spawnSubagent: dispatchSpawnSubagent,
|
|
@@ -1067,6 +1077,7 @@ async function startAgentRuntime(
|
|
|
1067
1077
|
})
|
|
1068
1078
|
|
|
1069
1079
|
const serverFactory = createServer({
|
|
1080
|
+
getGithubSelf: githubTokenBridge.getSelf,
|
|
1070
1081
|
port,
|
|
1071
1082
|
reloadAll: reloadAllNonDestructive,
|
|
1072
1083
|
reloadRegistry,
|
package/src/sandbox/build.ts
CHANGED
|
@@ -212,6 +212,7 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
|
|
|
212
212
|
appendWritable(argv, policy)
|
|
213
213
|
appendMasks(argv, policy)
|
|
214
214
|
appendProtected(argv, policy)
|
|
215
|
+
for (const mount of policy.reveal ?? []) appendMount(argv, mount)
|
|
215
216
|
appendSymlinks(argv, policy)
|
|
216
217
|
|
|
217
218
|
if (policy.cwd !== undefined) {
|
|
@@ -16,6 +16,12 @@ export const RUNTIME_OWNED_SECRET_DIRS = [
|
|
|
16
16
|
'.typeclaw/home',
|
|
17
17
|
'.typeclaw/logs',
|
|
18
18
|
BROWSER_PROFILE_RELATIVE_DIR,
|
|
19
|
+
// TypeVault (typevault.enabled): the agent's machine key and typevault's
|
|
20
|
+
// private state, and the vault itself, which holds the secrets.json envelope.
|
|
21
|
+
// Mirrors src/typevault/vault.ts; kept as literals so the sandbox does not
|
|
22
|
+
// load the typevault SDK.
|
|
23
|
+
'.typeclaw/typevault',
|
|
24
|
+
'.typevault',
|
|
19
25
|
] as const
|
|
20
26
|
|
|
21
27
|
// SECURITY / classification: operator-provisioned CLI credential stores. TypeClaw
|
|
@@ -23,6 +23,10 @@ export async function reconcileDependencyBinWrappers(options: {
|
|
|
23
23
|
agentDir: string
|
|
24
24
|
sessionTmp: string
|
|
25
25
|
baselineDirs?: readonly string[]
|
|
26
|
+
// Runtime-provided commands (bin name -> entrypoint), e.g. the TypeVault CLI
|
|
27
|
+
// TypeClaw itself ships. Never derived from the agent's package.json, and
|
|
28
|
+
// they own their name even when an agent dependency ships the same bin.
|
|
29
|
+
runtimeBins?: Readonly<Record<string, string>>
|
|
26
30
|
}): Promise<DependencyBinReconciliation> {
|
|
27
31
|
const dir = join(options.sessionTmp, DEPENDENCY_BIN_DIR_NAME)
|
|
28
32
|
const previous = reconciliationLocks.get(dir) ?? Promise.resolve()
|
|
@@ -42,7 +46,12 @@ export async function reconcileDependencyBinWrappers(options: {
|
|
|
42
46
|
}
|
|
43
47
|
|
|
44
48
|
async function reconcileDependencyBinWrappersUnlocked(
|
|
45
|
-
options: {
|
|
49
|
+
options: {
|
|
50
|
+
agentDir: string
|
|
51
|
+
sessionTmp: string
|
|
52
|
+
baselineDirs?: readonly string[]
|
|
53
|
+
runtimeBins?: Readonly<Record<string, string>>
|
|
54
|
+
},
|
|
46
55
|
dir: string,
|
|
47
56
|
): Promise<DependencyBinReconciliation> {
|
|
48
57
|
const validation = await validateDependencyBins(options.agentDir, options.baselineDirs)
|
|
@@ -52,6 +61,9 @@ async function reconcileDependencyBinWrappersUnlocked(
|
|
|
52
61
|
if (resolution.kind !== 'package' || wrappers.has(resolution.declaration.bin)) continue
|
|
53
62
|
wrappers.set(resolution.declaration.bin, renderWrapper(resolution.containerEntrypoint))
|
|
54
63
|
}
|
|
64
|
+
for (const [bin, entrypoint] of Object.entries(options.runtimeBins ?? {})) {
|
|
65
|
+
wrappers.set(bin, renderWrapper(entrypoint))
|
|
66
|
+
}
|
|
55
67
|
for (const entry of await readdir(dir).catch(() => [])) {
|
|
56
68
|
if (entry.startsWith('.')) continue
|
|
57
69
|
if (!wrappers.has(entry)) await rm(join(dir, entry), { recursive: true, force: true })
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { realpath } from 'node:fs/promises'
|
|
2
|
-
import { dirname, isAbsolute, relative } from 'node:path'
|
|
1
|
+
import { realpath, stat } from 'node:fs/promises'
|
|
2
|
+
import { dirname, isAbsolute, join, relative } from 'node:path'
|
|
3
3
|
import { fileURLToPath } from 'node:url'
|
|
4
4
|
|
|
5
5
|
import type { SandboxMount } from './policy'
|
|
@@ -9,18 +9,27 @@ const RUNTIME_MODULE_FILE = fileURLToPath(import.meta.url)
|
|
|
9
9
|
// Dev mode (`file:`/`link:` typeclaw dep): files under node_modules/typeclaw
|
|
10
10
|
// are symlinks into a checkout outside the agent folder. `typeclaw start`
|
|
11
11
|
// mirror-mounts that checkout read-only into the container, but bwrap only
|
|
12
|
-
// binds the agent folder, so
|
|
13
|
-
// bash. Bind
|
|
14
|
-
//
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
|
|
12
|
+
// binds the agent folder, so anything typeclaw resolves inside the checkout
|
|
13
|
+
// dangles inside model bash. Bind the checkout's `src/` (bundled skills) and
|
|
14
|
+
// `node_modules/` (runtime-provided bins such as `typevault`, which resolve
|
|
15
|
+
// into typeclaw's own dependencies), never the checkout root, so a
|
|
16
|
+
// developer's `.env` or `.git` stays out of the sandbox. The path comes from
|
|
17
|
+
// the running module's own realpath, which the model cannot redirect by
|
|
18
|
+
// rewriting node_modules. Registry installs resolve inside the agent folder
|
|
19
|
+
// and get no mount.
|
|
20
|
+
export async function resolveDevSourceMounts(
|
|
19
21
|
agentDir: string,
|
|
20
22
|
moduleFile: string = RUNTIME_MODULE_FILE,
|
|
21
|
-
): Promise<Extract<SandboxMount, { type: 'ro-bind' }>
|
|
23
|
+
): Promise<Extract<SandboxMount, { type: 'ro-bind' }>[]> {
|
|
22
24
|
const srcDir = dirname(dirname(await realpath(moduleFile)))
|
|
23
25
|
const rel = relative(await realpath(agentDir), srcDir)
|
|
24
|
-
if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return
|
|
25
|
-
|
|
26
|
+
if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return []
|
|
27
|
+
const mounts: Extract<SandboxMount, { type: 'ro-bind' }>[] = [{ type: 'ro-bind', source: srcDir, dest: srcDir }]
|
|
28
|
+
const nodeModules = join(dirname(srcDir), 'node_modules')
|
|
29
|
+
// bwrap aborts on a missing bind source; a checkout that was never
|
|
30
|
+
// installed has nothing there to expose.
|
|
31
|
+
if ((await stat(nodeModules).catch(() => undefined))?.isDirectory()) {
|
|
32
|
+
mounts.push({ type: 'ro-bind', source: nodeModules, dest: nodeModules })
|
|
33
|
+
}
|
|
34
|
+
return mounts
|
|
26
35
|
}
|
|
@@ -63,7 +63,7 @@ export function canWriteAgentRootInSandbox(permissions: PermissionService, origi
|
|
|
63
63
|
return canSeePrivateSurface(permissions, origin) && seesSecrets
|
|
64
64
|
}
|
|
65
65
|
|
|
66
|
-
function canSeePrivateSurface(permissions: PermissionService, origin: SessionOrigin | undefined): boolean {
|
|
66
|
+
export function canSeePrivateSurface(permissions: PermissionService, origin: SessionOrigin | undefined): boolean {
|
|
67
67
|
return (
|
|
68
68
|
permissions.has(origin, CORE_PERMISSIONS.fsSeePrivate) ||
|
|
69
69
|
permissions.has(origin, 'security.bypass.low') ||
|
package/src/sandbox/index.ts
CHANGED
package/src/sandbox/policy.ts
CHANGED
|
@@ -132,6 +132,11 @@ export type SandboxPolicy = {
|
|
|
132
132
|
masks?: SandboxMaskPolicy
|
|
133
133
|
writable?: SandboxWritablePolicy
|
|
134
134
|
protected?: SandboxProtectedPolicy
|
|
135
|
+
// Read-only binds rendered AFTER masks and protected zones, so they deliberately
|
|
136
|
+
// re-expose one path a mask covers. Only trusted runtime hooks set these (the
|
|
137
|
+
// TypeVault plugin re-exposes the ciphertext-only vault and its grant socket
|
|
138
|
+
// to a session holding vault.use); never derive one from model input.
|
|
139
|
+
reveal?: Extract<SandboxMount, { type: 'ro-bind' | 'tmpfs' }>[]
|
|
135
140
|
symlinks?: SandboxSymlinkOp[]
|
|
136
141
|
network?: SandboxNetwork
|
|
137
142
|
env?: SandboxEnvPolicy
|
package/src/secrets/hydrate.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { readFileSync } from 'node:fs'
|
|
2
|
-
import { join } from 'node:path'
|
|
2
|
+
import { dirname, join } from 'node:path'
|
|
3
|
+
|
|
4
|
+
import { isTypevaultMarker, readEnvelopeTextSync } from '@/typevault/envelope-store'
|
|
3
5
|
|
|
4
6
|
import { channelFieldDefaultEnv } from './defaults'
|
|
5
7
|
import { resolveSecret, secretFieldSchema, type Secret } from './resolve'
|
|
@@ -71,6 +73,7 @@ function readChannelSecrets(secretsPath: string): Record<string, Record<string,
|
|
|
71
73
|
let raw: string
|
|
72
74
|
try {
|
|
73
75
|
raw = readFileSync(secretsPath, 'utf8')
|
|
76
|
+
if (isTypevaultMarker(raw)) raw = readEnvelopeTextSync(dirname(secretsPath))
|
|
74
77
|
} catch {
|
|
75
78
|
return {}
|
|
76
79
|
}
|
package/src/secrets/storage.ts
CHANGED
|
@@ -5,6 +5,8 @@ import type { AuthOperationOptions, Credential, CredentialInfo, CredentialStore
|
|
|
5
5
|
import { operationSignal, raceWithAbortSignal } from '@earendil-works/pi-ai/utils/abort'
|
|
6
6
|
import lockfile from 'proper-lockfile'
|
|
7
7
|
|
|
8
|
+
import { isTypevaultMarker, readEnvelopeTextSync, writeEnvelopeTextSync } from '@/typevault/envelope-store'
|
|
9
|
+
|
|
8
10
|
import { providerKeyDefaultEnv } from './defaults'
|
|
9
11
|
import { resolveSecret } from './resolve'
|
|
10
12
|
import {
|
|
@@ -511,7 +513,8 @@ export class SecretsBackend implements CredentialStore {
|
|
|
511
513
|
}
|
|
512
514
|
|
|
513
515
|
private readEnvelope(): SecretsFile {
|
|
514
|
-
const
|
|
516
|
+
const onDisk = existsSync(this.secretsPath) ? readFileSync(this.secretsPath, 'utf8') : ''
|
|
517
|
+
const raw = isTypevaultMarker(onDisk) ? readEnvelopeTextSync(dirname(this.secretsPath)) : onDisk
|
|
515
518
|
if (!raw.trim()) return newEmptyEnvelope()
|
|
516
519
|
let parsed: unknown
|
|
517
520
|
try {
|
|
@@ -527,6 +530,12 @@ export class SecretsBackend implements CredentialStore {
|
|
|
527
530
|
}
|
|
528
531
|
|
|
529
532
|
private writeEnvelopeAtomic(envelope: SecretsFile): void {
|
|
533
|
+
// With typevault enabled, secrets.json is only the marker; the envelope
|
|
534
|
+
// itself is written into the vault and the marker is never rewritten.
|
|
535
|
+
if (existsSync(this.secretsPath) && isTypevaultMarker(readFileSync(this.secretsPath, 'utf8'))) {
|
|
536
|
+
writeEnvelopeTextSync(dirname(this.secretsPath), stringifyEnvelope(envelope))
|
|
537
|
+
return
|
|
538
|
+
}
|
|
530
539
|
const tmp = `${this.secretsPath}.${process.pid}.${Date.now()}.${tempSequence++}.tmp`
|
|
531
540
|
writeFileSync(tmp, stringifyEnvelope(envelope), { encoding: 'utf8', mode: FILE_MODE })
|
|
532
541
|
try {
|
|
@@ -37,6 +37,7 @@ export type CommandOutbound = {
|
|
|
37
37
|
}
|
|
38
38
|
|
|
39
39
|
export type CommandRunnerOptions = {
|
|
40
|
+
readonly getGithubSelf?: CreateSessionOptions['getGithubSelf']
|
|
40
41
|
pluginRuntime: PluginRuntime
|
|
41
42
|
permissions: PermissionService
|
|
42
43
|
spawnSubagent: CommandSpawnSubagent
|
|
@@ -190,6 +191,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
|
|
|
190
191
|
origin,
|
|
191
192
|
prompt: (text) =>
|
|
192
193
|
runPromptForCommand({
|
|
194
|
+
getGithubSelf: opts.getGithubSelf,
|
|
193
195
|
text,
|
|
194
196
|
origin,
|
|
195
197
|
runtime: opts.pluginRuntime,
|
|
@@ -413,6 +415,7 @@ function drainWrites(stream: WritableStream<Uint8Array>): Promise<void> {
|
|
|
413
415
|
export type CreateSessionForCommand = (options: CreateSessionOptions) => Promise<CreateSessionResult>
|
|
414
416
|
|
|
415
417
|
export async function runPromptForCommand(args: {
|
|
418
|
+
readonly getGithubSelf?: CreateSessionOptions['getGithubSelf']
|
|
416
419
|
text: string
|
|
417
420
|
origin: SessionOrigin
|
|
418
421
|
runtime: PluginRuntime
|
|
@@ -446,6 +449,7 @@ export async function runPromptForCommand(args: {
|
|
|
446
449
|
const sessionId = resolveSessionIdForOrigin(args.origin)
|
|
447
450
|
const create = args._createSession ?? createSessionWithDispose
|
|
448
451
|
const { session, dispose } = await create({
|
|
452
|
+
getGithubSelf: args.getGithubSelf,
|
|
449
453
|
origin: args.origin,
|
|
450
454
|
permissions: args.permissions,
|
|
451
455
|
sessionManager: args.sessionFactory.createPersisted(),
|
package/src/server/index.ts
CHANGED
|
@@ -74,6 +74,7 @@ export type ServerLogger = {
|
|
|
74
74
|
}
|
|
75
75
|
|
|
76
76
|
export type ServerOptions = {
|
|
77
|
+
readonly getGithubSelf?: CreateSessionOptions['getGithubSelf']
|
|
77
78
|
port: number
|
|
78
79
|
reloadAll?: ReloadAllFn
|
|
79
80
|
reloadRegistry?: ReloadRegistry
|
|
@@ -197,7 +198,7 @@ type QueuedPrompt = {
|
|
|
197
198
|
}
|
|
198
199
|
|
|
199
200
|
type SessionState = {
|
|
200
|
-
session: AgentSession
|
|
201
|
+
session: AgentSession & { resetLoopGuard?: () => void }
|
|
201
202
|
activeModelRef: ReturnType<typeof resolveFallbackChain>[number]
|
|
202
203
|
// The session's creation-time thinking level, captured once. An escalated turn
|
|
203
204
|
// moves `session.thinkingLevel` to `high`, so neither turn-driving path (drain
|
|
@@ -286,6 +287,7 @@ function encodeBase64(bytes: Uint8Array): string {
|
|
|
286
287
|
}
|
|
287
288
|
|
|
288
289
|
export function createServer({
|
|
290
|
+
getGithubSelf,
|
|
289
291
|
port,
|
|
290
292
|
reloadAll,
|
|
291
293
|
reloadRegistry,
|
|
@@ -548,6 +550,7 @@ export function createServer({
|
|
|
548
550
|
// either side at exactly its current tool surface.
|
|
549
551
|
const subagentRegistry = runtimeSnapshot?.subagents
|
|
550
552
|
const result = await createSession({
|
|
553
|
+
getGithubSelf,
|
|
551
554
|
reloadRegistry,
|
|
552
555
|
sessionManager,
|
|
553
556
|
origin,
|
|
@@ -836,6 +839,7 @@ export function createServer({
|
|
|
836
839
|
return
|
|
837
840
|
}
|
|
838
841
|
send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
|
|
842
|
+
state.session.resetLoopGuard?.()
|
|
839
843
|
const fallbackHooks = state.runtimeSnapshot?.hooks
|
|
840
844
|
const retrievalContext: { results: string } = { results: '' }
|
|
841
845
|
if (fallbackHooks !== undefined && agentDir !== undefined) {
|
|
@@ -1195,6 +1199,9 @@ async function drain(
|
|
|
1195
1199
|
if (!item) break
|
|
1196
1200
|
pushQueueState(ws, state)
|
|
1197
1201
|
send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
|
|
1202
|
+
// Only a prompt typed in the TUI is a new request; continuations,
|
|
1203
|
+
// subagent completions, and restart handoffs keep the loop guard's history.
|
|
1204
|
+
if (item.source === 'tui') state.session.resetLoopGuard?.()
|
|
1198
1205
|
|
|
1199
1206
|
if (agentDir !== undefined) {
|
|
1200
1207
|
// recordTurnStart is a read-modify-write of the same state file; let
|
|
@@ -324,6 +324,22 @@ Off switch — the broker is constructed but never opens a WS, no LISTEN gets fo
|
|
|
324
324
|
|
|
325
325
|
This is an ordinary operator config change, not a security request to push back on. Follow **Editing `typeclaw.json` safely**: set `eval.enabled` to `true`, and set `origins` to what they named (drop the key for "all origins"). Write, commit, and tell them: "Edited `eval` — restart-required. Run `typeclaw restart` (host stage)." If the installed TypeClaw predates `eval` (the field is missing from `typeclaw.schema.json`), say it needs a TypeClaw upgrade first instead of writing a field that would be dropped.
|
|
326
326
|
|
|
327
|
+
## typevault (experimental)
|
|
328
|
+
|
|
329
|
+
```json
|
|
330
|
+
"typevault": { "enabled": true, "promptPort": 8976 }
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
`enabled` (default `false`) keeps the agent's `secrets.json` (provider keys, channel tokens, MCP logins) in the agent's own TypeVault vault instead of a plaintext file. **Restart-required**: the move happens in `typeclaw start`. Setting it back to `false` and restarting restores `secrets.json` from the vault; anything else stored in the vault stays there for the next time it is enabled. `.env` is never touched. While enabled, `secrets.json` only holds a marker; never edit it or `.typevault/` by hand.
|
|
334
|
+
|
|
335
|
+
### When the user asks "turn on TypeVault" / "move my secrets into the vault"
|
|
336
|
+
|
|
337
|
+
Follow **Editing `typeclaw.json` safely**: set `typevault.enabled` to `true`, commit, and tell them: "Edited `typevault` — restart-required. Run `typeclaw restart` (host stage)." Mention that it is experimental. If the installed TypeClaw predates `typevault` (the field is missing from `typeclaw.schema.json`), say it needs an upgrade first.
|
|
338
|
+
|
|
339
|
+
### The `vault_request` secret page
|
|
340
|
+
|
|
341
|
+
The one-time secret page is served on the container port in `typevault.promptPort` (default `8976`; **restart-required**), which must not match `channels.github.webhookPort` or any other listener. To move it, set the field, commit, and tell them to run `typeclaw restart`. With `typevault.enabled`, TypeClaw opens a free Cloudflare quick tunnel to it at boot and builds `cloudflared` into the image, so nothing needs configuring. An operator who wants a stable URL can add their own `manual` tunnel with `upstreamPort` set to that port, or a `cloudflare-named` one named `typevault` (its upstream is set in Cloudflare, so it has no `upstreamPort`); either replaces the implicit one. TypeClaw can't see or change a `cloudflare-named` tunnel's origin: whenever `typevault.promptPort` changes, the operator must also retarget the origin in Cloudflare, or the link opens but no page is served.
|
|
342
|
+
|
|
327
343
|
## Network and model HTTP internal destinations
|
|
328
344
|
|
|
329
345
|
These are two independent gates:
|
|
@@ -15,7 +15,9 @@ Under budget you get shard bodies de-duplicated across turns; over budget you ge
|
|
|
15
15
|
|
|
16
16
|
## Writing
|
|
17
17
|
|
|
18
|
-
You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards. Do not edit `memory/topics/`, `memory/skills/`, or the stream files yourself — the dreaming subagent and runtime own them.
|
|
18
|
+
You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards. Do not edit `memory/topics/`, `memory/skills/`, or the stream files yourself — the dreaming subagent and runtime own them. Use `memory_remember({ topic, body, who?, verbatim? })` when asked to remember something, when correcting a fact, or when a durable decision or preference is established; skip routine chatter. Supply a short topic and self-contained body in the evidence language. `who` optionally names the attributed person; `verbatim: true` also saves the exact body as a linked reference.
|
|
19
|
+
|
|
20
|
+
`memory_remember` is available to every role alongside `memory_search`. The runtime stamps the session, transcript anchor, and channel provenance; the fragment and optional reference are indexed immediately. Deliberate fragments carry `kind: "explicit"` but still undergo normal dreaming consolidation. The tool never advances the memory-logger watermark, and memory-logger skips facts already saved by successful calls.
|
|
19
21
|
|
|
20
22
|
`memory/skills/<name>/SKILL.md` is muscle memory the dreaming subagent distills from recurring procedures; the runtime auto-loads those as first-class skills on next boot. A durable task procedure you want to keep goes to its existing editable owner skill (or a support file that skill links) first — see `typeclaw-skills` for who owns which skill — not into `memory/skills/` or `AGENTS.md`.
|
|
21
23
|
|
|
@@ -25,12 +25,12 @@ You always have these four, even if `typeclaw.json` declares zero `roles`. User-
|
|
|
25
25
|
|
|
26
26
|
Roles form a strict tower for **bypassable plugin guards**: each role bypasses guards at its tier and below. The canonical-secret invariant sits outside this tower.
|
|
27
27
|
|
|
28
|
-
| Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]`
|
|
29
|
-
| --------- | ----------------------------------------------------------------- | --------------- |
|
|
30
|
-
| `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
|
|
31
|
-
| `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium` |
|
|
32
|
-
| `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `browser.shared`, `security.bypass.low` |
|
|
33
|
-
| `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none
|
|
28
|
+
| Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
|
|
29
|
+
| --------- | ----------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `vault.use`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
|
|
31
|
+
| `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `vault.use`, `security.bypass.low`, `security.bypass.medium` |
|
|
32
|
+
| `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `browser.shared`, `vault.use`, `security.bypass.low` |
|
|
33
|
+
| `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
|
|
34
34
|
|
|
35
35
|
A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
|
|
36
36
|
|
|
@@ -58,7 +58,7 @@ For each user turn, the current speaker's effective role is delivered in the tur
|
|
|
58
58
|
|
|
59
59
|
**The permission list (cron/subagent block) is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
|
|
60
60
|
|
|
61
|
-
Memory recall is globally visible by default across all roles and origins. Provenance is additive searchable metadata, not an authorization boundary. The optional `workspace`, `chat`, and `thread` parameters on `memory_search` narrow results when a focused subset is needed; no memory-specific permission grant is required.
|
|
61
|
+
Memory recall is globally visible by default across all roles and origins. Provenance is additive searchable metadata, not an authorization boundary. The optional `workspace`, `chat`, and `thread` parameters on `memory_search` narrow results when a focused subset is needed; no memory-specific permission grant is required. `memory_remember` is likewise available to every role; it appends a runtime-stamped fragment to the daily stream for dreaming to consolidate.
|
|
62
62
|
|
|
63
63
|
## The match-rule DSL
|
|
64
64
|
|
|
@@ -92,7 +92,7 @@ Things the DSL rejects (the parser emits actionable errors at boot, but you shou
|
|
|
92
92
|
|
|
93
93
|
Three sources contribute permission strings:
|
|
94
94
|
|
|
95
|
-
1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `browser.shared
|
|
95
|
+
1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `browser.shared`, `vault.use` (with `typevault.enabled`, bash gets a TypeVault grant for the role's tier and the tiers below it).
|
|
96
96
|
2. **Bundled security plugin** (always loaded): the eight per-guard strings (`security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`) AND three severity-tier strings (`security.bypass.low`, `security.bypass.medium`, `security.bypass.high`).
|
|
97
97
|
3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
|
|
98
98
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: typeclaw-troubleshooting
|
|
3
|
-
description: Use this skill when you are stuck in a fix-it loop — you've made roughly three attempts at the same failure and you're still cycling shell commands (kill the process, re-run, `sleep`, `capture-pane`, inspect, retry) without converging. Triggers include a hung or runaway process that won't die, a `C-c` that didn't stop the program, `<defunct>`/zombie processes piling up in `ps`, an interactive program that blocks `bash` waiting for input, a script that "ran" but produced no output and no file, repeated "not found"/timeout/same-error-again loops, and any moment you catch yourself thinking "let me wait a bit more and check again" for the third time. Also read it before you start a minutes-long or input-waiting program in your own session (dev server, REPL, watcher, `docker compose up`, interactive installer) — foreground `bash` blocks until exit, and this skill has the detached tmux start/observe/drive/stop pattern. Read it before you spawn `operator` to take over the debugging — it covers the operator hand-off prompt, the tmux session pattern, killing stuck/zombie processes properly, and the edge-triggered capture-pane polling loop that the inline retry-and-sleep approach gets wrong. Also read it when `gh` works but `git push`/`git fetch` to GitHub fails with 403, "Permission denied", or "Authentication failed", or when `gh` and git seem to act as different GitHub accounts.
|
|
3
|
+
description: Use this skill when you are stuck in a fix-it loop — you've made roughly three attempts at the same failure and you're still cycling shell commands (kill the process, re-run, `sleep`, `capture-pane`, inspect, retry) without converging. Triggers include a hung or runaway process that won't die, a `C-c` that didn't stop the program, `<defunct>`/zombie processes piling up in `ps`, an interactive program that blocks `bash` waiting for input, a script that "ran" but produced no output and no file, repeated "not found"/timeout/same-error-again loops, and any moment you catch yourself thinking "let me wait a bit more and check again" for the third time. Also read it before you start a minutes-long or input-waiting program in your own session (dev server, REPL, watcher, `docker compose up`, interactive installer) — foreground `bash` blocks until exit, and this skill has the detached tmux start/observe/drive/stop pattern. Read it before you spawn `operator` to take over the debugging — it covers the operator hand-off prompt, the tmux session pattern, killing stuck/zombie processes properly, and the edge-triggered capture-pane polling loop that the inline retry-and-sleep approach gets wrong. Also read it when `gh` works but `git push`/`git fetch` to GitHub fails with 403, "Permission denied", or "Authentication failed", or when `gh` and git seem to act as different GitHub accounts. Also read it when `vault_request` fails with `internal daemon error`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# typeclaw-troubleshooting
|
|
@@ -126,3 +126,20 @@ TypeClaw has two GitHub credential sources, and you cannot see either one (`secr
|
|
|
126
126
|
These can belong to different GitHub accounts. A green `gh auth status` or a working `gh api` call proves nothing about the account `git push` uses. When a brokered git command fails on auth, TypeClaw appends a note to the result naming the credential source it used and that account's login. Read it before retrying.
|
|
127
127
|
|
|
128
128
|
Do not try to fix this from inside the session. Don't rewrite the remote URL, embed a token, run `gh auth login`, or edit git credential config: the broker owns these credentials, and you can't read or change them. Report the mismatch to the operator, naming both accounts and the target repo, and tell them how to recover: correct or remove the mismatched push credential (`channels.github` in `secrets.json`, or the declared `GH_TOKEN` in `.env`), then run `typeclaw restart`.
|
|
129
|
+
|
|
130
|
+
## TypeVault: `vault_request` fails with `internal daemon error`
|
|
131
|
+
|
|
132
|
+
The daemon returns this text for every unexpected failure and writes the real exception to its log. `.typeclaw/typevault/` is masked from your tools, so you can't read that log and shouldn't spawn `operator` to look for it. Tell the operator to run this on the host, in the agent folder:
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
tail -n 40 .typeclaw/typevault/config/typevault/checkouts/*/run/daemon.log
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
If the log says `Failed to start server. Is port <port> in use?` (`EADDRINUSE`), another process in the container holds the secret-page port (`typevault.promptPort`, default `8976`). The daemon binds that port on the first request, so `typevault whoami` still succeeds and nothing fails at boot.
|
|
139
|
+
|
|
140
|
+
- **Check first:** `channels.github.webhookPort` may match it. `typeclaw doctor` warns about this as `channel.github.webhook-port`.
|
|
141
|
+
- **Otherwise:** a service the agent or operator started is listening on that port.
|
|
142
|
+
- **Fix:** set `typevault.promptPort` in `typeclaw.json` to a free port, and don't stop the other listener. See the `typeclaw-config` skill for the edit.
|
|
143
|
+
- **Then restart:** after a failed bind the daemon keeps returning this error until it restarts, even once the port is free. The field is restart-required too. Tell the operator to run `typeclaw restart`, then retry `vault_request`.
|
|
144
|
+
|
|
145
|
+
Never ask the user to paste the secret into chat while this is broken.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { TunnelManager } from './manager'
|
|
2
|
+
|
|
3
|
+
// The container's running tunnel manager, for in-process runtime code that
|
|
4
|
+
// needs a tunnel's current public URL at call time (quick-tunnel URLs rotate
|
|
5
|
+
// on every restart, so a boot-time snapshot would go stale).
|
|
6
|
+
let active: Pick<TunnelManager, 'urlFor'> | undefined
|
|
7
|
+
|
|
8
|
+
export function setActiveTunnelManager(manager: Pick<TunnelManager, 'urlFor'> | undefined): void {
|
|
9
|
+
active = manager
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export function activeTunnelUrl(tunnelName: string): string | null {
|
|
13
|
+
return active?.urlFor(tunnelName) ?? null
|
|
14
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { typevaultCliPath } from './cli-path'
|
|
2
|
+
|
|
3
|
+
// The `typevault` command in model bash. Its grant and vault reach bash under
|
|
4
|
+
// TypeClaw's own names, so a project's own typevault CLI (`bun typevault` in a
|
|
5
|
+
// checkout) never finds a TYPEVAULT_* variable steering it to the agent's
|
|
6
|
+
// vault. Only this command maps them back.
|
|
7
|
+
const env = process.env
|
|
8
|
+
if (env.TYPECLAW_VAULT_DIR) {
|
|
9
|
+
env.TYPEVAULT_DIR = env.TYPECLAW_VAULT_DIR
|
|
10
|
+
env.TYPEVAULT_GLOBAL = '1'
|
|
11
|
+
}
|
|
12
|
+
if (env.TYPECLAW_VAULT_GRANT) env.TYPEVAULT_GRANT = env.TYPECLAW_VAULT_GRANT
|
|
13
|
+
// typevault strips its own TYPEVAULT_* variables from a `run` child; these
|
|
14
|
+
// would otherwise hand the child the session's whole grant.
|
|
15
|
+
delete env.TYPECLAW_VAULT_DIR
|
|
16
|
+
delete env.TYPECLAW_VAULT_GRANT
|
|
17
|
+
|
|
18
|
+
await import(typevaultCliPath())
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { dirname, join } from 'node:path'
|
|
2
|
+
|
|
3
|
+
// Resolved without importing the SDK, so the bash sandbox can wrap the CLI
|
|
4
|
+
// without loading typevault on every agent.
|
|
5
|
+
export function typevaultCliPath(): string {
|
|
6
|
+
return join(dirname(Bun.resolveSync('typevault', import.meta.dir)), 'cli', 'index.ts')
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
export function typevaultBashCliPath(): string {
|
|
10
|
+
return join(import.meta.dir, 'bash-cli.ts')
|
|
11
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { requireSecretsEntry, writeSecretsEntry } from './vault'
|
|
2
|
+
|
|
3
|
+
const [op, agentDir] = process.argv.slice(2)
|
|
4
|
+
|
|
5
|
+
try {
|
|
6
|
+
if (agentDir === undefined) throw new Error('usage: envelope-helper.ts <read|write> <agentDir>')
|
|
7
|
+
if (op === 'read') {
|
|
8
|
+
process.stdout.write(await requireSecretsEntry(agentDir))
|
|
9
|
+
} else if (op === 'write') {
|
|
10
|
+
await writeSecretsEntry(agentDir, await Bun.stdin.text())
|
|
11
|
+
} else {
|
|
12
|
+
throw new Error(`unknown operation: ${op}`)
|
|
13
|
+
}
|
|
14
|
+
} catch (error) {
|
|
15
|
+
process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
|
|
16
|
+
process.exit(1)
|
|
17
|
+
}
|