typeclaw 0.47.2 → 0.48.1

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.
Files changed (129) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +1 -2
  3. package/src/agent/loop-guard.ts +71 -41
  4. package/src/agent/plugin-tools.ts +234 -58
  5. package/src/agent/system-prompt.ts +1 -1
  6. package/src/agent/turn-runner.ts +12 -2
  7. package/src/agent-messenger/config-dir.ts +131 -0
  8. package/src/agent-messenger/host-config-dir.ts +121 -0
  9. package/src/bundled-plugins/agent-browser/index.ts +0 -38
  10. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
  11. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
  12. package/src/bundled-plugins/memory/append-tool.ts +75 -2
  13. package/src/bundled-plugins/memory/frontmatter.ts +13 -2
  14. package/src/bundled-plugins/memory/load-memory.ts +1 -1
  15. package/src/bundled-plugins/memory/memory-logger.ts +5 -1
  16. package/src/bundled-plugins/memory/secret-detector.ts +7 -0
  17. package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
  18. package/src/bundled-plugins/memory/vector/passages.ts +5 -1
  19. package/src/bundled-plugins/security/index.ts +148 -98
  20. package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
  21. package/src/channels/adapters/discord-bot-edit.ts +3 -5
  22. package/src/channels/adapters/discord-bot-reactions.ts +4 -6
  23. package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
  24. package/src/channels/adapters/discord-bot.ts +20 -23
  25. package/src/channels/adapters/discord-edit.ts +3 -5
  26. package/src/channels/adapters/discord-reactions.ts +4 -6
  27. package/src/channels/adapters/discord.ts +1 -1
  28. package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
  29. package/src/channels/adapters/github/history.ts +2 -1
  30. package/src/channels/adapters/github/inbound.ts +4 -11
  31. package/src/channels/adapters/github/index.ts +6 -9
  32. package/src/channels/adapters/github/outbound.ts +3 -6
  33. package/src/channels/adapters/github/reactions.ts +3 -2
  34. package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
  35. package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
  36. package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
  37. package/src/channels/adapters/github/review-state.ts +3 -2
  38. package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
  39. package/src/channels/adapters/github/webhook-register.ts +5 -8
  40. package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
  41. package/src/channels/adapters/instagram.ts +1 -1
  42. package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
  43. package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
  44. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
  45. package/src/channels/adapters/kakaotalk-membership.ts +2 -5
  46. package/src/channels/adapters/kakaotalk-typing.ts +1 -1
  47. package/src/channels/adapters/kakaotalk.ts +1 -1
  48. package/src/channels/adapters/line-channel-resolver.ts +3 -5
  49. package/src/channels/adapters/line.ts +1 -1
  50. package/src/channels/adapters/slack-bot-edit.ts +1 -1
  51. package/src/channels/adapters/slack-bot-reactions.ts +4 -6
  52. package/src/channels/adapters/slack-bot.ts +8 -8
  53. package/src/channels/adapters/slack-edit.ts +3 -5
  54. package/src/channels/adapters/slack-reactions.ts +4 -6
  55. package/src/channels/adapters/slack.ts +1 -1
  56. package/src/channels/adapters/teams-edit.ts +2 -5
  57. package/src/channels/adapters/teams.ts +1 -1
  58. package/src/channels/adapters/telegram-bot-edit.ts +4 -7
  59. package/src/channels/adapters/telegram-bot.ts +1 -1
  60. package/src/channels/adapters/webex-bot.ts +1 -1
  61. package/src/channels/adapters/webex-edit.ts +3 -5
  62. package/src/channels/adapters/webex.ts +1 -1
  63. package/src/channels/github-review-claim.ts +89 -4
  64. package/src/channels/github-token-bridge.ts +2 -1
  65. package/src/channels/manager.ts +478 -64
  66. package/src/channels/membership-cache.ts +2 -5
  67. package/src/channels/persistence.ts +3 -6
  68. package/src/channels/reloadable.ts +23 -6
  69. package/src/channels/router.ts +134 -56
  70. package/src/channels/tunnel-bridge.ts +2 -1
  71. package/src/channels/types.ts +6 -3
  72. package/src/cli/channel.ts +15 -16
  73. package/src/cli/hostd.ts +61 -38
  74. package/src/cli/init.ts +21 -7
  75. package/src/cli/model.ts +6 -3
  76. package/src/cli/restart.ts +13 -15
  77. package/src/compose/restart.ts +14 -6
  78. package/src/config/config.ts +10 -0
  79. package/src/config/providers.ts +68 -0
  80. package/src/container/agent-operation-lock.ts +85 -0
  81. package/src/container/controller.ts +6 -0
  82. package/src/container/index.ts +8 -0
  83. package/src/container/restart.ts +55 -0
  84. package/src/container/shared.ts +5 -0
  85. package/src/container/start.ts +70 -4
  86. package/src/container/stop.ts +17 -1
  87. package/src/dependencies/bin-resolver.ts +88 -0
  88. package/src/dependencies/bins.ts +227 -0
  89. package/src/dependencies/index.ts +17 -0
  90. package/src/doctor/checks.ts +2 -0
  91. package/src/doctor/operational-incidents.ts +32 -0
  92. package/src/hostd/credential-rotation-apply.ts +94 -0
  93. package/src/hostd/daemon.ts +1 -1
  94. package/src/hostd/paths.ts +17 -0
  95. package/src/hostd/supervisor.ts +27 -10
  96. package/src/init/dockerfile.ts +6 -5
  97. package/src/init/env-file.ts +42 -18
  98. package/src/init/instagram-auth.ts +55 -31
  99. package/src/init/kakaotalk-auth.ts +1 -5
  100. package/src/init/line-auth.ts +45 -29
  101. package/src/init/models-dev.ts +131 -10
  102. package/src/init/opengateway-catalog.ts +120 -0
  103. package/src/init/validate-api-key.ts +26 -4
  104. package/src/operations/classify-tool-outcome.ts +151 -0
  105. package/src/operations/incidents.ts +274 -0
  106. package/src/operations/index.ts +3 -0
  107. package/src/operations/remediations.ts +41 -0
  108. package/src/reload/client.ts +8 -2
  109. package/src/reload/docker-exec-client.ts +10 -2
  110. package/src/reload/index.ts +1 -1
  111. package/src/reload/recover.ts +5 -3
  112. package/src/reload/registry.ts +5 -5
  113. package/src/reload/types.ts +9 -1
  114. package/src/run/index.ts +5 -0
  115. package/src/sandbox/canonical-secrets.ts +10 -1
  116. package/src/sandbox/dependency-bins.ts +125 -0
  117. package/src/sandbox/hidden-paths.ts +4 -1
  118. package/src/sandbox/index.ts +8 -0
  119. package/src/sandbox/policy.ts +1 -1
  120. package/src/sandbox/privileged-runtime.ts +7 -12
  121. package/src/sandbox/runtime-private.ts +4 -0
  122. package/src/sandbox/writable-zones.ts +4 -4
  123. package/src/server/index.ts +7 -5
  124. package/src/shared/protocol.ts +6 -1
  125. package/src/test-helpers/fake-agent-operation-lock.ts +66 -0
  126. package/typeclaw.schema.json +10 -5
  127. package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
  128. package/src/bundled-plugins/agent-browser/shim.ts +0 -108
  129. /package/src/channels/{adapters/describe-error.ts → describe-error.ts} +0 -0
@@ -61,6 +61,10 @@ export async function promptPersistentTurnWithFallback(opts: {
61
61
  onRetryBackoffStart?: () => void
62
62
  beforeAttempt?: (ref: ModelRef) => void
63
63
  onAttemptFailed?: (attempt: PersistentTurnAttempt) => void
64
+ // Fired the first time an attempt starts executing a tool. Callers use it to
65
+ // learn that the turn stopped being silent even when the turn ultimately
66
+ // fails — including the hard-throw path, where no result is ever returned.
67
+ onToolExecutionStarted?: () => void
64
68
  now?: () => number
65
69
  }): Promise<PersistentTurnResult> {
66
70
  if (opts.refs.length === 0) throw new Error('promptPersistentTurnWithFallback: refs[] must be non-empty')
@@ -106,7 +110,7 @@ export async function promptPersistentTurnWithFallback(opts: {
106
110
  // subagents. `skipProviderErrorSubscription` only suppresses the soft-error
107
111
  // listener (subagents capture their final message off the leaf instead, via
108
112
  // detectSoftErrorFromLeaf, so a second listener would race that capture).
109
- const unsubActivity = subscribeAttemptActivity(opts.session, activity)
113
+ const unsubActivity = subscribeAttemptActivity(opts.session, activity, opts.onToolExecutionStarted)
110
114
  const unsubProvider = opts.skipProviderErrorSubscription
111
115
  ? () => {}
112
116
  : subscribeProviderErrorsIfAvailable(opts.session, (err) => {
@@ -291,13 +295,19 @@ function isRefUsable(
291
295
  return !circuit.isProviderOpen({ profile, ref })
292
296
  }
293
297
 
294
- function subscribeAttemptActivity(session: AgentSession, activity: AttemptActivity): () => void {
298
+ function subscribeAttemptActivity(
299
+ session: AgentSession,
300
+ activity: AttemptActivity,
301
+ onToolExecutionStarted?: () => void,
302
+ ): () => void {
295
303
  const subscribe = (session as { subscribe?: unknown }).subscribe
296
304
  if (typeof subscribe !== 'function') return () => {}
297
305
  return session.subscribe((event: unknown) => {
298
306
  if (!isRecord(event)) return
299
307
  if (event.type === 'tool_execution_start' || event.type === 'tool_execution_end') {
308
+ const alreadyStarted = activity.startedToolExecution
300
309
  activity.startedToolExecution = true
310
+ if (!alreadyStarted) onToolExecutionStarted?.()
301
311
  return
302
312
  }
303
313
  if (event.type !== 'message_update') return
@@ -0,0 +1,131 @@
1
+ import { lstat, mkdir, readdir, rename, rmdir } from 'node:fs/promises'
2
+ import { dirname, join, posix } from 'node:path'
3
+
4
+ import { readEnvFile } from '@/init/env-file'
5
+
6
+ export const AGENT_MESSENGER_CONFIG_RELATIVE_DIR = 'workspace/.config/agent-messenger'
7
+ export const LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR = 'workspace/.agent-messenger'
8
+
9
+ const CONTAINER_AGENT_DIR = '/agent'
10
+
11
+ // posix.join, not join: this path is baked into the Dockerfile ENV and the
12
+ // `docker run -e` override, so it must stay `/agent/...` even when the host
13
+ // stage runs on native Windows (where join would emit backslashes).
14
+ export const CONTAINER_AGENT_MESSENGER_CONFIG_DIR = posix.join(CONTAINER_AGENT_DIR, AGENT_MESSENGER_CONFIG_RELATIVE_DIR)
15
+
16
+ export type MigrationResult = { ok: true; migrated: boolean } | { ok: false; reason: string }
17
+
18
+ export type AgentMessengerConfigPolicy = {
19
+ override: string | null
20
+ containerDir: string
21
+ migrate: boolean
22
+ }
23
+
24
+ export function agentMessengerConfigDir(agentDir: string): string {
25
+ return join(agentDir, AGENT_MESSENGER_CONFIG_RELATIVE_DIR)
26
+ }
27
+
28
+ export function legacyAgentMessengerConfigDir(agentDir: string): string {
29
+ return join(agentDir, LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR)
30
+ }
31
+
32
+ export function resolveAgentMessengerConfigPolicy(agentDir: string): AgentMessengerConfigPolicy {
33
+ const value = readEnvFile(agentDir).get('AGENT_MESSENGER_CONFIG_DIR')
34
+ if (value === undefined || value.length === 0) {
35
+ return { override: null, containerDir: CONTAINER_AGENT_MESSENGER_CONFIG_DIR, migrate: true }
36
+ }
37
+
38
+ const containerDir = posix.resolve(CONTAINER_AGENT_DIR, value)
39
+ return {
40
+ override: value,
41
+ containerDir,
42
+ migrate: containerDir === CONTAINER_AGENT_MESSENGER_CONFIG_DIR,
43
+ }
44
+ }
45
+
46
+ export async function migrateAgentMessengerConfigDir(agentDir: string): Promise<MigrationResult> {
47
+ const legacyDir = legacyAgentMessengerConfigDir(agentDir)
48
+ const configDir = agentMessengerConfigDir(agentDir)
49
+
50
+ const legacy = await inspectDirectory(legacyDir)
51
+ const current = await inspectDirectory(configDir)
52
+ if (legacy.exists && !legacy.directory) return invalidDirectoryResult(legacyDir, legacy.kind)
53
+ if (current.exists && !current.directory) return invalidDirectoryResult(configDir, current.kind)
54
+
55
+ // Validated before the nothing-to-migrate return below: callers use the
56
+ // destination for host-stage credential writes even when no legacy tree
57
+ // exists, and lstat on the leaf follows a symlinked parent. Checking this
58
+ // only on the migrating path would leave the common post-migration state
59
+ // writing E2EE key material through an unvalidated symlink.
60
+ const configParent = await inspectDirectory(dirname(configDir))
61
+ if (configParent.exists && !configParent.directory) {
62
+ return invalidDirectoryResult(dirname(configDir), configParent.kind)
63
+ }
64
+
65
+ if (!legacy.exists) return { ok: true, migrated: false }
66
+
67
+ if (!current.exists) {
68
+ await mkdir(dirname(configDir), { recursive: true })
69
+ return renameForMigration(legacyDir, configDir)
70
+ }
71
+
72
+ if (legacy.empty) {
73
+ await rmdir(legacyDir)
74
+ return { ok: true, migrated: false }
75
+ }
76
+ if (current.empty) {
77
+ await rmdir(configDir)
78
+ return renameForMigration(legacyDir, configDir)
79
+ }
80
+
81
+ return {
82
+ ok: false,
83
+ reason: `Agent-messenger config exists in both ${legacyDir} and ${configDir}. Merge them manually, then remove the legacy directory before starting TypeClaw.`,
84
+ }
85
+ }
86
+
87
+ type DirectoryInspection =
88
+ | { exists: false }
89
+ | { exists: true; directory: false; kind: 'symbolic link' | 'non-directory' }
90
+ | { exists: true; directory: true; empty: boolean }
91
+
92
+ async function inspectDirectory(path: string): Promise<DirectoryInspection> {
93
+ try {
94
+ const entry = await lstat(path)
95
+ if (entry.isSymbolicLink()) return { exists: true, directory: false, kind: 'symbolic link' }
96
+ if (!entry.isDirectory()) return { exists: true, directory: false, kind: 'non-directory' }
97
+ return { exists: true, directory: true, empty: (await readdir(path)).length === 0 }
98
+ } catch (error) {
99
+ if (isErrorCode(error, 'ENOENT')) return { exists: false }
100
+ throw error
101
+ }
102
+ }
103
+
104
+ function invalidDirectoryResult(path: string, kind: 'symbolic link' | 'non-directory'): { ok: false; reason: string } {
105
+ return {
106
+ ok: false,
107
+ reason: `Agent-messenger config path ${path} is a ${kind}; refusing to migrate. Resolve it manually before starting TypeClaw.`,
108
+ }
109
+ }
110
+
111
+ async function renameForMigration(legacyDir: string, configDir: string): Promise<MigrationResult> {
112
+ try {
113
+ await rename(legacyDir, configDir)
114
+ return { ok: true, migrated: true }
115
+ } catch (error) {
116
+ if (isErrorCode(error, 'EXDEV')) {
117
+ return {
118
+ ok: false,
119
+ reason: `Cannot move agent-messenger config from ${legacyDir} to ${configDir} across filesystems. Move it manually before starting TypeClaw; TypeClaw will not copy credential data.`,
120
+ }
121
+ }
122
+ return {
123
+ ok: false,
124
+ reason: `Could not move agent-messenger config from ${legacyDir} to ${configDir}: ${error instanceof Error ? error.message : String(error)}`,
125
+ }
126
+ }
127
+ }
128
+
129
+ function isErrorCode(error: unknown, code: string): boolean {
130
+ return error instanceof Error && 'code' in error && error.code === code
131
+ }
@@ -0,0 +1,121 @@
1
+ import { join, posix } from 'node:path'
2
+
3
+ import type { WithAgentOperationLock } from '@/container/agent-operation-lock'
4
+ import { containerNameFromCwd, defaultDockerExec, type DockerExec, isGenuineMissingContainer } from '@/container/shared'
5
+
6
+ import { migrateAgentMessengerConfigDir, resolveAgentMessengerConfigPolicy } from './config-dir'
7
+
8
+ const CONTAINER_AGENT_DIR = '/agent'
9
+ const CONFIG_ENV_PREFIX = 'AGENT_MESSENGER_CONFIG_DIR='
10
+
11
+ export type HostAgentMessengerConfigResult = { ok: true; hostDir: string } | { ok: false; reason: string }
12
+
13
+ export type HostAgentMessengerConfigDeps = { exec?: DockerExec; operationLock?: WithAgentOperationLock }
14
+
15
+ export async function prepareAgentMessengerHostConfigDir(
16
+ agentDir: string,
17
+ deps: HostAgentMessengerConfigDeps = {},
18
+ ): Promise<HostAgentMessengerConfigResult> {
19
+ const exec = deps.exec ?? defaultDockerExec
20
+ const containerName = containerNameFromCwd(agentDir)
21
+ const inspected = await inspectRunningConfig(exec, containerName)
22
+ if (!inspected.ok) return inspected
23
+
24
+ if (inspected.state === 'running') {
25
+ return mapContainerDirToHost(agentDir, inspected.containerDir)
26
+ }
27
+
28
+ try {
29
+ const policy = resolveAgentMessengerConfigPolicy(agentDir)
30
+ if (policy.migrate) {
31
+ const reprobed = await inspectRunningConfig(exec, containerName)
32
+ if (!reprobed.ok) return reprobed
33
+ if (reprobed.state === 'running') {
34
+ return {
35
+ ok: false,
36
+ reason: `Container ${containerName} became running while authentication was being prepared. No credentials were written; retry authentication.`,
37
+ }
38
+ }
39
+ const migration = await migrateAgentMessengerConfigDir(agentDir)
40
+ if (!migration.ok) return migration
41
+ }
42
+ return mapContainerDirToHost(agentDir, policy.containerDir)
43
+ } catch (error) {
44
+ return {
45
+ ok: false,
46
+ reason: `Could not prepare the host agent-messenger config directory: ${error instanceof Error ? error.message : String(error)}`,
47
+ }
48
+ }
49
+ }
50
+
51
+ type RunningConfigInspection =
52
+ | { ok: true; state: 'running'; containerDir: string }
53
+ | { ok: true; state: 'stopped-or-missing' }
54
+ | { ok: false; reason: string }
55
+
56
+ async function inspectRunningConfig(exec: DockerExec, containerName: string): Promise<RunningConfigInspection> {
57
+ let result
58
+ try {
59
+ result = await exec(['inspect', '--format', '{{.State.Running}}\n{{json .Config.Env}}', containerName])
60
+ } catch (error) {
61
+ return indeterminateDockerState(error instanceof Error ? error.message : String(error))
62
+ }
63
+
64
+ if (result.exitCode !== 0) {
65
+ if (isGenuineMissingContainer(result.stderr)) return { ok: true, state: 'stopped-or-missing' }
66
+ return indeterminateDockerState(result.stderr.trim() || `docker inspect exited with code ${result.exitCode}`)
67
+ }
68
+
69
+ const parsed = parseInspectOutput(result.stdout)
70
+ if (!parsed.ok) return indeterminateDockerState(parsed.reason)
71
+ if (!parsed.running) return { ok: true, state: 'stopped-or-missing' }
72
+
73
+ const activeEnv = parsed.env.find((entry) => entry.startsWith(CONFIG_ENV_PREFIX))
74
+ const activeDir = activeEnv?.slice(CONFIG_ENV_PREFIX.length)
75
+ // Empty means unset here to mirror the SDK's `override && override.length > 0` check.
76
+ if (activeDir === undefined || activeDir.length === 0) {
77
+ return {
78
+ ok: false,
79
+ reason:
80
+ 'The running TypeClaw container has no non-empty AGENT_MESSENGER_CONFIG_DIR and is using its in-container HOME fallback, which the host cannot write. Set AGENT_MESSENGER_CONFIG_DIR to a path under /agent or stop the container before authenticating.',
81
+ }
82
+ }
83
+ return { ok: true, state: 'running', containerDir: posix.resolve(CONTAINER_AGENT_DIR, activeDir) }
84
+ }
85
+
86
+ function indeterminateDockerState(detail: string): { ok: false; reason: string } {
87
+ return {
88
+ ok: false,
89
+ reason: `Could not determine whether the TypeClaw container is running; refusing to migrate or authenticate. Resolve Docker access and retry. ${detail}`,
90
+ }
91
+ }
92
+
93
+ type ParsedInspectOutput = { ok: true; running: boolean; env: string[] } | { ok: false; reason: string }
94
+
95
+ function parseInspectOutput(stdout: string): ParsedInspectOutput {
96
+ const lines = stdout.trimEnd().split('\n')
97
+ if (lines.length !== 2 || (lines[0] !== 'true' && lines[0] !== 'false')) {
98
+ return { ok: false, reason: 'docker inspect returned malformed running-state/config output' }
99
+ }
100
+ try {
101
+ const env: unknown = JSON.parse(lines[1]!)
102
+ if (!Array.isArray(env) || !env.every((entry) => typeof entry === 'string')) {
103
+ return { ok: false, reason: 'docker inspect returned a malformed container environment' }
104
+ }
105
+ return { ok: true, running: lines[0] === 'true', env }
106
+ } catch {
107
+ return { ok: false, reason: 'docker inspect returned malformed environment JSON' }
108
+ }
109
+ }
110
+
111
+ function mapContainerDirToHost(agentDir: string, containerDir: string): HostAgentMessengerConfigResult {
112
+ const resolved = posix.resolve(CONTAINER_AGENT_DIR, containerDir)
113
+ const relative = posix.relative(CONTAINER_AGENT_DIR, resolved)
114
+ if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
115
+ return {
116
+ ok: false,
117
+ reason: `AGENT_MESSENGER_CONFIG_DIR resolves outside /agent (${resolved}) and cannot be mapped to the host agent directory. Set it to /agent or a path beneath /agent before authenticating.`,
118
+ }
119
+ }
120
+ return { ok: true, hostDir: relative === '' ? agentDir : join(agentDir, ...relative.split('/')) }
121
+ }
@@ -3,10 +3,6 @@ import { join } from 'node:path'
3
3
  import { definePlugin } from '@/plugin'
4
4
  import { publishForwardRequest, subscribeForwardResult } from '@/portbroker'
5
5
 
6
- import { installShim, KNOWN_BIN_PATHS, type InstallShimResult } from './shim-install'
7
-
8
- type SafeResult = InstallShimResult | { kind: 'error'; binPath: string; error: unknown }
9
-
10
6
  // Documented in skills/agent-browser/SKILL.md so the agent can discover which
11
7
  // host port the reserved dashboard forward actually bound. Moving or renaming
12
8
  // this path requires updating the skill in lockstep. The env override is an
@@ -27,9 +23,6 @@ let unsubscribeForwardResult: (() => void) | null = null
27
23
 
28
24
  export default definePlugin({
29
25
  plugin: async (ctx) => {
30
- logInstallResult(ctx.logger, safeInstallShim(KNOWN_BIN_PATHS.global))
31
- logInstallResult(ctx.logger, safeInstallShim(KNOWN_BIN_PATHS.local, KNOWN_BIN_PATHS.global))
32
-
33
26
  requestDashboardForward(ctx.logger)
34
27
 
35
28
  return {
@@ -84,34 +77,3 @@ async function recordProxyPort(contents: string, logger: { warn: (msg: string) =
84
77
  logger.warn(`failed to write ${path}: ${String(error)}`)
85
78
  }
86
79
  }
87
-
88
- function safeInstallShim(binPath: string, delegateTarget?: string): SafeResult {
89
- try {
90
- return installShim({ binPath, delegateTarget })
91
- } catch (error) {
92
- return { kind: 'error', binPath, error }
93
- }
94
- }
95
-
96
- function logInstallResult(
97
- logger: { info: (msg: string) => void; warn: (msg: string) => void },
98
- result: SafeResult,
99
- ): void {
100
- if (result.kind === 'installed') {
101
- logger.info(`installed agent-browser shim at ${result.binPath} (real bin stashed at ${result.stashTarget})`)
102
- return
103
- }
104
- if (result.kind === 'delegated') {
105
- logger.info(`installed agent-browser alias at ${result.binPath} (delegates to ${result.delegateTarget})`)
106
- return
107
- }
108
- if (result.kind === 'already-installed') {
109
- logger.info(`agent-browser shim already installed at ${result.binPath}`)
110
- return
111
- }
112
- if (result.kind === 'no-upstream') {
113
- logger.info(`no agent-browser binary at ${result.binPath}; nothing to shim here`)
114
- return
115
- }
116
- logger.warn(`failed to install agent-browser shim at ${result.binPath}: ${String(result.error)}`)
117
- }
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: agent-browser
3
3
  description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. ALSO use whenever a browser step needs a human in the loop — login walls, 2FA, CAPTCHA, payment confirmation, "is this the right button?" ambiguity, or the user asking to watch the browser live — because the bundled dashboard is the only way for a human to observe or take over a session from inside the Docker container. Prefer agent-browser over any built-in browser automation or web tools.
4
- allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)
4
+ allowed-tools: Bash(agent-browser:*)
5
5
  hidden: true
6
6
  ---
7
7
 
@@ -15,7 +15,6 @@ const AGENT_ROOT_WRITE_ALLOWLIST = new Set([
15
15
  'SOUL.md',
16
16
  'USER.md',
17
17
  'cron.json',
18
- 'package.json',
19
18
  'typeclaw.json',
20
19
  ])
21
20
 
@@ -48,6 +47,12 @@ export async function checkNonWorkspaceWriteGuard(options: {
48
47
  resolveRealIntendedPath(path.resolve(agentDir)),
49
48
  resolveRealIntendedPath('/tmp'),
50
49
  ])
50
+ if (await isOperatorOwnedPackageManifest(agentDir, targetPath, realTargetPath)) {
51
+ return {
52
+ block: true,
53
+ reason: `Guard \`${GUARD_NON_WORKSPACE_WRITE}\` blocked a model write to operator-owned package manifest ${targetPath}.`,
54
+ }
55
+ }
51
56
  if (await isSkillAuthoringAllowed({ tool, args, agentDir })) return undefined
52
57
  if (await isMemoryTopicsWriteAllowed({ tool, args, agentDir, origin })) return undefined
53
58
  if (await isAllowedAgentRootWrite(agentDir, targetPath, realTargetPath)) return undefined
@@ -74,6 +79,16 @@ export async function checkNonWorkspaceWriteGuard(options: {
74
79
  }
75
80
  }
76
81
 
82
+ async function isOperatorOwnedPackageManifest(
83
+ agentDir: string,
84
+ targetPath: string,
85
+ realTargetPath: string,
86
+ ): Promise<boolean> {
87
+ const rootManifest = path.join(path.resolve(agentDir), 'package.json')
88
+ const realRootManifest = await resolveRealIntendedPath(rootManifest)
89
+ return targetPath === rootManifest || realTargetPath === realRootManifest
90
+ }
91
+
77
92
  async function isAllowedAgentRootWrite(agentDir: string, targetPath: string, realTargetPath: string): Promise<boolean> {
78
93
  const resolvedAgentDir = path.resolve(agentDir)
79
94
  if (path.dirname(targetPath) === resolvedAgentDir && AGENT_ROOT_WRITE_ALLOWLIST.has(path.basename(targetPath))) {
@@ -1,4 +1,4 @@
1
- import { mkdir } from 'node:fs/promises'
1
+ import { mkdir, readFile } from 'node:fs/promises'
2
2
  import { dirname } from 'node:path'
3
3
 
4
4
  import { z } from 'zod'
@@ -28,11 +28,13 @@ export type OriginProvider = () => SessionOrigin | undefined
28
28
  // is already on disk by append time). Lets the append tool strip hallucinated
29
29
  // slugs the model invents without ever calling `store_reference`.
30
30
  export type ReferenceSlugResolver = (agentDir: string) => Promise<Iterable<string>>
31
+ export type TranscriptPathProvider = () => string | undefined
31
32
 
32
33
  export type CreateAppendToolOptions = {
33
34
  onFragmentsAppended?: FragmentsAppendedHook
34
35
  originProvider?: OriginProvider
35
36
  referenceSlugResolver?: ReferenceSlugResolver
37
+ transcriptPathProvider?: TranscriptPathProvider
36
38
  }
37
39
 
38
40
  // Stamped fields are the stable channel coordinates only. Author identity is
@@ -64,7 +66,7 @@ export function provenanceFromOrigin(origin: SessionOrigin | undefined): Fragmen
64
66
  }
65
67
 
66
68
  export function createAppendTool(options: CreateAppendToolOptions = {}) {
67
- const { onFragmentsAppended, originProvider, referenceSlugResolver } = options
69
+ const { onFragmentsAppended, originProvider, referenceSlugResolver, transcriptPathProvider } = options
68
70
  return defineTool({
69
71
  description:
70
72
  "Append a memory fragment to today's JSONL daily stream and advance the watermark. The runtime serializes your call into a JSON line and chooses the filename — do not emit raw JSON and do not pass a path. `topic`/`body` are the fragment's substance; `source` is the parent session id; `entry` is the transcript-entry-id this fragment anchors to; `latestEntryId` is the latest transcript-entry-id you evaluated in this run (advances the watermark, may equal `entry` or be later). `references` may ONLY contain slugs returned by `store_reference` (it returns the slug it wrote) — never topic ids, PR names, stream paths, or invented labels; unknown slugs are dropped. `who` is the display name/handle of the person the fragment's evidence is attributable to — set it ONLY when one transcript speaker clearly owns the evidence; omit it when the fact is the user's own, spans multiple speakers, or is not attributable. The channel/room/platform (`where`) is stamped automatically from the session origin — do not pass it and do not restate it in the body. Refuses content with recognized credential patterns and refuses byte-equivalent topic+body within the same daily stream.",
@@ -87,6 +89,16 @@ export function createAppendTool(options: CreateAppendToolOptions = {}) {
87
89
  async execute({ topic, body, source, entry, latestEntryId, references, who }, ctx) {
88
90
  const streamPath = dailyStreamPath(ctx.agentDir)
89
91
  const where = provenanceFromOrigin(originProvider?.())
92
+ const transcriptPath = transcriptPathProvider?.()
93
+ if (
94
+ transcriptPath !== undefined &&
95
+ (await anchorBelongsToOperationalIncident(transcriptPath, entry, latestEntryId))
96
+ ) {
97
+ throw new Error(
98
+ 'Refusing to append: the transcript anchor belongs to a deterministic operational incident sequence. ' +
99
+ 'Operational defects are owned by the incident ledger, not semantic memory.',
100
+ )
101
+ }
90
102
  // `who` is LLM-supplied and force-committed to memory, so it clears the
91
103
  // same secret guard as topic/body — a token-shaped display name is refused
92
104
  // with the same retryable error. (`where` names are origin-derived and the
@@ -155,6 +167,67 @@ export function createAppendTool(options: CreateAppendToolOptions = {}) {
155
167
  })
156
168
  }
157
169
 
170
+ const OPERATIONAL_INCIDENT_MARKER = 'TYPECLAW_OPERATIONAL_INCIDENT '
171
+
172
+ export async function anchorBelongsToOperationalIncident(
173
+ transcriptPath: string,
174
+ entryId: string,
175
+ latestEntryId = entryId,
176
+ ): Promise<boolean> {
177
+ let raw: string
178
+ try {
179
+ raw = await readFile(transcriptPath, 'utf8')
180
+ } catch {
181
+ return false
182
+ }
183
+ const entries = raw
184
+ .split('\n')
185
+ .filter((line) => line.length > 0)
186
+ .flatMap((line): unknown[] => {
187
+ try {
188
+ return [JSON.parse(line) as unknown]
189
+ } catch {
190
+ return []
191
+ }
192
+ })
193
+ const anchorIndex = entries.findIndex((entry) => entryIdOf(entry) === entryId)
194
+ const latestIndex = entries.findIndex((entry) => entryIdOf(entry) === latestEntryId)
195
+ if (anchorIndex < 0 || latestIndex < anchorIndex) return false
196
+
197
+ for (let i = anchorIndex; i <= latestIndex; i++) {
198
+ if (entryBelongsToOperationalIncident(entries, i)) return true
199
+ }
200
+ return false
201
+ }
202
+
203
+ function entryBelongsToOperationalIncident(entries: unknown[], entryIndex: number): boolean {
204
+ if (containsIncidentMarker(entries[entryIndex])) return true
205
+ for (let i = entryIndex - 1; i >= 0; i--) {
206
+ const entry = entries[i]
207
+ if (containsIncidentMarker(entry)) return true
208
+ if (messageRole(entry) === 'user') return false
209
+ }
210
+ return false
211
+ }
212
+
213
+ function entryIdOf(entry: unknown): string | undefined {
214
+ if (typeof entry !== 'object' || entry === null) return undefined
215
+ const id = (entry as { id?: unknown }).id
216
+ return typeof id === 'string' ? id : undefined
217
+ }
218
+
219
+ function messageRole(entry: unknown): string | undefined {
220
+ if (typeof entry !== 'object' || entry === null) return undefined
221
+ const message = (entry as { message?: unknown }).message
222
+ if (typeof message !== 'object' || message === null) return undefined
223
+ const role = (message as { role?: unknown }).role
224
+ return typeof role === 'string' ? role : undefined
225
+ }
226
+
227
+ function containsIncidentMarker(entry: unknown): boolean {
228
+ return JSON.stringify(entry).includes(OPERATIONAL_INCIDENT_MARKER)
229
+ }
230
+
158
231
  export const appendTool = createAppendTool()
159
232
 
160
233
  export const advanceWatermarkTool = defineTool({
@@ -1,11 +1,14 @@
1
1
  export type ShardFrontmatter = {
2
2
  heading: string
3
+ kind?: ShardKind
3
4
  cites: number
4
5
  days: number
5
6
  lastReinforced: string
6
7
  tags?: string[]
7
8
  }
8
9
 
10
+ export type ShardKind = 'belief' | 'procedure' | 'environmental-incident'
11
+
9
12
  const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/
10
13
 
11
14
  export function parseShard(text: string): { frontmatter: ShardFrontmatter; body: string } {
@@ -111,7 +114,8 @@ function parseFrontmatterBlock(text: string): ShardFrontmatter {
111
114
  throw new Error(`frontmatter field 'lastReinforced': expected YYYY-MM-DD, got '${values.lastReinforced}'`)
112
115
  }
113
116
 
114
- const result: ShardFrontmatter = { heading, cites, days, lastReinforced }
117
+ const kind = values.kind ?? 'belief'
118
+ const result: ShardFrontmatter = { heading, kind: kind as ShardKind, cites, days, lastReinforced }
115
119
  if ('tags' in values) {
116
120
  result.tags = values.tags as string[]
117
121
  }
@@ -120,9 +124,15 @@ function parseFrontmatterBlock(text: string): ShardFrontmatter {
120
124
  }
121
125
 
122
126
  const FRONTMATTER_PARSERS: {
123
- [K in keyof Omit<ShardFrontmatter, 'tags'>]: (value: string) => unknown
127
+ [K in keyof Required<Omit<ShardFrontmatter, 'tags'>>]: (value: string) => unknown
124
128
  } = {
125
129
  heading: (v) => v,
130
+ kind: (v) => {
131
+ if (v !== 'belief' && v !== 'procedure' && v !== 'environmental-incident') {
132
+ throw new Error(`expected belief, procedure, or environmental-incident, got '${v}'`)
133
+ }
134
+ return v
135
+ },
126
136
  cites: parseNonNegativeInt,
127
137
  days: parseNonNegativeInt,
128
138
  lastReinforced: (v) => v,
@@ -140,6 +150,7 @@ function parseNonNegativeInt(value: string): number {
140
150
  export function renderShard(frontmatter: ShardFrontmatter, body: string): string {
141
151
  const lines = ['---']
142
152
  lines.push(`heading: ${frontmatter.heading}`)
153
+ if (frontmatter.kind !== undefined && frontmatter.kind !== 'belief') lines.push(`kind: ${frontmatter.kind}`)
143
154
  lines.push(`cites: ${frontmatter.cites}`)
144
155
  lines.push(`days: ${frontmatter.days}`)
145
156
  lines.push(`lastReinforced: ${frontmatter.lastReinforced}`)
@@ -50,7 +50,7 @@ export async function loadMemoryInjectionPlan(
50
50
  if (rootMemory.content !== null && !hasTopicsDir) {
51
51
  return buildInjectionPlan([rootFallbackEntry(rootMemory)], { budgetBytes: options.injectionBudgetBytes })
52
52
  }
53
- const shards = await loadAllShards(agentDir)
53
+ const shards = (await loadAllShards(agentDir)).filter((shard) => shard.frontmatter.kind !== 'environmental-incident')
54
54
  return buildInjectionPlan(shards, { budgetBytes: options.injectionBudgetBytes })
55
55
  }
56
56
 
@@ -68,7 +68,7 @@ export function isMemoryLoggerPayload(value: unknown): value is MemoryLoggerPayl
68
68
 
69
69
  export const MEMORY_LOGGER_SYSTEM_PROMPT = `You are typeclaw's memory-extraction subagent.
70
70
 
71
- Read the parent session transcript past the watermark and write zero or more durable memory fragments to today's stream, then exit. Capture only operational facts a future agent would concretely need: explicit user instructions, stable identity/role/tool facts, decisions with reasoning, reproducible workarounds, corrections, changed minds, and content the user explicitly taught the agent or asked it to remember. Most runs produce zero or one fragment; that is expected.
71
+ Read the parent session transcript past the watermark and write zero or more durable memory fragments to today's stream, then exit. Capture only facts a future agent would concretely need: explicit user instructions, stable identity/role/tool facts, decisions with reasoning, reproducible user-domain procedures, corrections, changed minds, and content the user explicitly taught the agent or asked it to remember. Most runs produce zero or one fragment; that is expected.
72
72
 
73
73
  A separate \`dreaming\` subagent later consolidates fragments into \`memory/topics/\`, dedupes across days, resolves contradictions, and decides what generalizes. **Dreaming is downstream consolidation, not permission to over-capture upstream.** You do not read \`memory/topics/\`; cross-shard reasoning is dreaming's job. Your inputs are the transcript past the watermark and, optionally, today's daily stream for local dedup. Recurrence across days is useful evidence for dreaming, so a repeated durable fact anchored to new evidence is not a duplicate.
74
74
 
@@ -118,6 +118,7 @@ Capture-worthy categories:
118
118
  - **Stable collaborator/contact facts.** Durable facts about non-user people the agent is likely to encounter again: name/handle, active-participant status in this context, role, responsibility, project relationship, durable working preference, or coordination/contact context. When a person actively participates in the conversation — recurring presence, multiple messages, or a back-and-forth exchange, not a single drive-by line — capture one compact identity fragment recording who they are (name/handle) and that they are an active participant here, even if they did not state a durable role or preference. A stated role/preference strengthens the fragment but is no longer required. A name appearing inside active back-and-forth can be a capture signal; a name merely mentioned in passing by someone else, especially an absent third party, is not. Keep one introduction to one compact fragment that bundles the person's core durable context (e.g. "Alex is an active participant in this project chat" or "Alex is the frontend lead for Project X and prefers GitHub issues over Slack for bug triage"), never a separate fragment per attribute. True single drive-by participants still do not earn memory. Third-party facts must come from the user/owner, or from that person describing their own role/preference in normal collaboration; do not persist one participant's reputational claims about another unless the user confirms or operationally relies on them.
119
119
  - **Decisions with reasoning.** "We chose X over Y because Z" when future sessions must honor X.
120
120
  - **Reproducible workarounds and debugging insights.** A config that worked, flag combination, procedure, root cause, or non-obvious fix.
121
+ - **Deterministic operational incidents are excluded.** A transcript tool result containing \`TYPECLAW_OPERATIONAL_INCIDENT\` and the immediately following user correction/workaround belong to TypeClaw's incident ledger. Skip the whole failure → response → correction sequence. Do not turn an environment repair into a belief or procedure, even when it recurs; the append tool mechanically rejects incident-owned anchors.
121
122
  - **In-transcript changed minds.** Capture "actually, scratch that" only when the prior position is explicit. Do not compare against \`memory/topics/\`.
122
123
  - **Corrections the user made to the agent.** Especially when the agent confidently asserted something false that future sessions may repeat. When the agent stated a factual claim and the user corrected it, capture the corrected fact as a distinct, evidence-anchored fragment EVEN IF it sounds like something memory may already know — you cannot inspect \`memory/topics/\`, so your job is to preserve this later correction occurrence so dreaming can reinforce and sharpen the stored belief (repeated corrections are how a contested fact gets stronger, not noise to skip). Anchor the body to the correction: what the agent said, what the user corrected it to. This is semantic and **language-independent** — recognize corrections in any language (Korean, Japanese, Chinese, Arabic, and every Latin-script language), not from English cue phrases.
123
124
  - **Content the user explicitly taught, trained on, or asked the agent to remember.** Capture the substance taught, not merely that teaching happened. Treat these six intent families as representative, not exhaustive:
@@ -304,10 +305,12 @@ export function createMemoryLoggerSubagent(
304
305
  // The handler runs one logger spawn at a time per agentDir (inFlightKey), so a
305
306
  // single mutable cell safely carries this spawn's origin to the append tool.
306
307
  let currentOrigin: SessionOrigin | undefined
308
+ let currentTranscriptPath: string | undefined
307
309
  const appendTool = createAppendTool({
308
310
  onFragmentsAppended: options.onFragmentsAppended,
309
311
  originProvider: () => currentOrigin,
310
312
  referenceSlugResolver: (agentDir) => listReferenceSlugs(agentDir),
313
+ transcriptPathProvider: () => currentTranscriptPath,
311
314
  })
312
315
  const storeReferenceTool = createStoreReferenceTool(options.onReferenceStored)
313
316
  const customTools = [findEntryTool, appendTool, storeReferenceTool, advanceWatermarkTool]
@@ -340,6 +343,7 @@ export function createMemoryLoggerSubagent(
340
343
  },
341
344
  handler: async (ctx, runSession) => {
342
345
  currentOrigin = ctx.payload.origin
346
+ currentTranscriptPath = ctx.payload.parentTranscriptPath
343
347
  const today = formatLocalDate()
344
348
  const memoryDir = streamsDir(ctx.payload.agentDir)
345
349
  const streamFile = streamFilePath(ctx.payload.agentDir, today)
@@ -29,6 +29,7 @@ export const SECRET_RULES: readonly SecretRule[] = [
29
29
  { name: 'google-api-key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
30
30
  { name: 'stripe-secret', pattern: /\bsk_live_[0-9A-Za-z]{24,}\b/ },
31
31
  { name: 'stripe-restricted', pattern: /\brk_live_[0-9A-Za-z]{24,}\b/ },
32
+ { name: 'jwt', pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
32
33
  { name: 'rsa-private-key', pattern: /-----BEGIN (?:RSA |OPENSSH |EC |DSA |PGP )?PRIVATE KEY-----/ },
33
34
  ]
34
35
 
@@ -47,3 +48,9 @@ export function detectSecrets(content: string): SecretMatch[] {
47
48
  }
48
49
  return matches
49
50
  }
51
+
52
+ export function isSecretShapedToken(token: string): boolean {
53
+ if (detectSecrets(token).length > 0) return true
54
+ if (/^[A-Fa-f0-9]{48,}$/.test(token)) return true
55
+ return /^[A-Za-z0-9_+-]{48,}$/.test(token)
56
+ }
@@ -94,7 +94,9 @@ export async function hybridSearch(
94
94
  })
95
95
  return events.length === 0 ? [] : [{ ...day, events }]
96
96
  })
97
- const eligibleShards = shards.filter((shard) => provenanceIndex.topicEligible(shard.slug, scope))
97
+ const eligibleShards = shards.filter(
98
+ (shard) => shard.frontmatter.kind !== 'environmental-incident' && provenanceIndex.topicEligible(shard.slug, scope),
99
+ )
98
100
  const eligibleReferences = scoped ? [] : references
99
101
 
100
102
  const { supersededFragmentIds } = buildParentLinks(shards)
@@ -72,7 +72,11 @@ export function findMissingPassages(store: VectorStore, passages: Passage[]): Pa
72
72
  function buildPassages(shards: TopicShard[], streamDays: UndreamedStreamDay[]): Passage[] {
73
73
  const { supersededFragmentIds } = buildParentLinks(shards)
74
74
  return [
75
- ...shards.map((shard): Passage => topicPassage(shard.slug, shard.frontmatter.heading, shard.body)),
75
+ ...shards.flatMap((shard): Passage[] =>
76
+ shard.frontmatter.kind === 'environmental-incident'
77
+ ? []
78
+ : [topicPassage(shard.slug, shard.frontmatter.heading, shard.body)],
79
+ ),
76
80
  ...streamDays.flatMap((day) =>
77
81
  day.events.flatMap((event): Passage[] => {
78
82
  if (event.type === 'watermark') return []