typeclaw 0.48.3 → 0.48.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.48.3",
3
+ "version": "0.48.4",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -50,7 +50,7 @@
50
50
  "@mariozechner/pi-tui": "^0.73.1",
51
51
  "@modelcontextprotocol/sdk": "^1.29.0",
52
52
  "@mozilla/readability": "^0.6.0",
53
- "agent-messenger": "^2.32.3",
53
+ "agent-messenger": "^2.35.0",
54
54
  "cheerio": "^1.2.0",
55
55
  "citty": "^0.2.2",
56
56
  "cron-parser": "^5.5.0",
@@ -4,6 +4,8 @@ import { parseArgs } from 'node:util'
4
4
 
5
5
  import { composeSystemPrompt, deriveSystemPromptMode, renderTurnTimeAnchor, type SystemPromptMode } from '@/agent'
6
6
  import type { SessionOrigin, SessionRoleContext } from '@/agent/session-origin'
7
+ import { renderRetrievedMemorySection, type RetrievedMemoryItem } from '@/bundled-plugins/memory/load-memory'
8
+ import { composeTurnPrompt } from '@/channels/router'
7
9
 
8
10
  type OriginKind = 'tui' | 'cron' | 'channel' | 'subagent'
9
11
  const ALL_KINDS: readonly OriginKind[] = ['tui', 'cron', 'channel', 'subagent'] as const
@@ -42,6 +44,39 @@ const PLACEHOLDER_GIT_NUDGE = [
42
44
  "These are real, current modifications — not advice. Before declaring this session's task done, commit any of these you're responsible for, with `git add <paths>` and `git commit -m \"…\"` per the version-control rules above. If a listed path is from earlier work you didn't touch, leave it alone.",
43
45
  ].join('\n')
44
46
 
47
+ const PLACEHOLDER_TURN_TEXT: Record<OriginKind, string> = {
48
+ tui: '<PLACEHOLDER: interactive user request from the TUI>',
49
+ cron: '<PLACEHOLDER: scheduled cron job prompt>',
50
+ channel: '<PLACEHOLDER: current channel message addressed to the agent>',
51
+ subagent: '<PLACEHOLDER: delegated subagent task>',
52
+ }
53
+
54
+ const PLACEHOLDER_MEMORY_ITEMS: RetrievedMemoryItem[] = [
55
+ {
56
+ source: 'topic',
57
+ key: 'placeholder-working-preference',
58
+ heading: '<PLACEHOLDER: durable user preference relevant to the current request>',
59
+ excerpt:
60
+ '<PLACEHOLDER: full memory excerpt with the durable preference, supporting context, and fragment citations>',
61
+ },
62
+ {
63
+ source: 'stream',
64
+ key: 'stream:<PLACEHOLDER-fragment-id>',
65
+ heading: '<PLACEHOLDER: recent undreamed observation relevant to this turn>',
66
+ excerpt: '<PLACEHOLDER: recent observation body awaiting dreaming consolidation>',
67
+ who: '<PLACEHOLDER: speaker name>',
68
+ when: '2026-05-21T08:30:00.000Z',
69
+ where: {
70
+ adapter: 'slack-bot',
71
+ workspace: 'T<PLACEHOLDER-WS>',
72
+ workspaceName: '<PLACEHOLDER: workspace display name>',
73
+ chat: 'C<PLACEHOLDER-CH>',
74
+ chatName: '<PLACEHOLDER: channel display name>',
75
+ thread: null,
76
+ },
77
+ },
78
+ ]
79
+
45
80
  type Fixture = {
46
81
  origin: SessionOrigin
47
82
  roleContext: SessionRoleContext
@@ -263,6 +298,106 @@ export function dumpSystemPrompt(kind: OriginKind, options: { gitNudge: boolean
263
298
  return dumpSystemPromptWithBreakdown(kind, options).prompt
264
299
  }
265
300
 
301
+ export function dumpTurnPromptWithBreakdown(kind: OriginKind): DumpResult {
302
+ const fixture = buildFixture(kind)
303
+ const memory = renderRetrievedMemorySection(PLACEHOLDER_MEMORY_ITEMS, { origin: fixture.origin })
304
+ if (kind !== 'channel') {
305
+ const timeAnchor = `${renderTurnTimeAnchor(PLACEHOLDER_NOW)}\n\n`
306
+ const userText = `${PLACEHOLDER_TURN_TEXT[kind]}\n\n`
307
+ const prompt = `${timeAnchor}${userText}${memory}`
308
+ return buildDumpResult(prompt, [
309
+ ['Time anchor', timeAnchor],
310
+ ['User text', userText],
311
+ ['Memory block', memory],
312
+ ])
313
+ }
314
+
315
+ const observed = [
316
+ {
317
+ text: '<PLACEHOLDER: earlier human message observed while the agent was not engaged>',
318
+ authorId: 'U<PLACEHOLDER-OBSERVER-1>',
319
+ authorName: '<PLACEHOLDER: first participant name>',
320
+ authorIsBot: false,
321
+ receivedAt: PLACEHOLDER_NOW.getTime() - 90_000,
322
+ ts: PLACEHOLDER_NOW.getTime() - 90_000,
323
+ source: 'observed' as const,
324
+ },
325
+ {
326
+ text: '<PLACEHOLDER: peer-bot follow-up retained as recent channel context>',
327
+ authorId: 'U<PLACEHOLDER-PEER-BOT>',
328
+ authorName: '<PLACEHOLDER: peer bot name>',
329
+ authorIsBot: true,
330
+ receivedAt: PLACEHOLDER_NOW.getTime() - 45_000,
331
+ ts: PLACEHOLDER_NOW.getTime() - 45_000,
332
+ source: 'observed' as const,
333
+ },
334
+ ]
335
+ const batch = [
336
+ {
337
+ text: PLACEHOLDER_TURN_TEXT.channel,
338
+ authorId: 'U<PLACEHOLDER-AUTHOR>',
339
+ authorName: '<PLACEHOLDER: current speaker name>',
340
+ authorIsBot: false,
341
+ externalMessageId: '<PLACEHOLDER-message-id>',
342
+ isBotMention: true,
343
+ replyToBotMessageId: '<PLACEHOLDER-prior-bot-message-id>',
344
+ isDm: false,
345
+ receivedAt: PLACEHOLDER_NOW.getTime(),
346
+ ts: PLACEHOLDER_NOW.getTime(),
347
+ },
348
+ ]
349
+ const channelTurn = composeTurnPrompt(observed, batch, {
350
+ adapter: 'slack-bot',
351
+ loopGuardActive: false,
352
+ groupChatNudge: true,
353
+ now: PLACEHOLDER_NOW,
354
+ role: fixture.roleContext.role,
355
+ })
356
+ const prompt = `${channelTurn}\n\n${memory}`
357
+ return buildDumpResultFromMarkers(prompt, [
358
+ ['Time anchor', '<current-time>'],
359
+ ['Role anchor', '<your-role authority="current-speaker">'],
360
+ // Anchored on the fence, not the notice's prose: the fence is the invariant
361
+ // every runtime notice carries, so rewording a notice can't break the dump.
362
+ ['Group-chat nudge', '---\n**[SYSTEM MESSAGE — not from a human]**'],
363
+ ['Recent context', '## Recent context (not addressed to you, for awareness only)'],
364
+ ['Current message', 'Note: if earlier turns appear above, they are real conversation history you can use.'],
365
+ ['Memory block (channel headings only)', '# Memory'],
366
+ ])
367
+ }
368
+
369
+ export function dumpTurnPrompt(kind: OriginKind): string {
370
+ return dumpTurnPromptWithBreakdown(kind).prompt
371
+ }
372
+
373
+ function buildDumpResult(prompt: string, parts: ReadonlyArray<readonly [string, string]>): DumpResult {
374
+ if (parts.map(([, body]) => body).join('') !== prompt) {
375
+ throw new Error('turn-prompt breakdown does not cover the rendered prompt exactly')
376
+ }
377
+ return {
378
+ prompt,
379
+ sections: parts.map(([name, body]) => mkSection(name, body)),
380
+ totalBytes: byteLength(prompt),
381
+ totalChars: prompt.length,
382
+ totalTokens: estimateTokens(prompt),
383
+ }
384
+ }
385
+
386
+ function buildDumpResultFromMarkers(prompt: string, markers: ReadonlyArray<readonly [string, string]>): DumpResult {
387
+ const starts = markers.map(([name, marker], index) => {
388
+ const start = prompt.indexOf(marker, index === 0 ? 0 : 1)
389
+ if (start < 0) throw new Error(`turn-prompt section marker not found: ${name}`)
390
+ return { name, start }
391
+ })
392
+ if (starts[0]?.start !== 0 || starts.some((part, index) => index > 0 && part.start <= starts[index - 1]!.start)) {
393
+ throw new Error('turn-prompt section markers are not in rendered order')
394
+ }
395
+ return buildDumpResult(
396
+ prompt,
397
+ starts.map((part, index) => [part.name, prompt.slice(part.start, starts[index + 1]?.start)] as const),
398
+ )
399
+ }
400
+
266
401
  // Slice between two unique headers in the rendered prompt. Both anchors are
267
402
  // guaranteed unique by `composeSystemPrompt`'s contract (each section's
268
403
  // header appears exactly once). Used by the breakdown so we attribute each
@@ -276,10 +411,10 @@ function extractSection(prompt: string, startHeader: string, endHeader: string |
276
411
  return end < 0 ? prompt.slice(afterStart) : prompt.slice(afterStart, end)
277
412
  }
278
413
 
279
- function header(kind: OriginKind, result: DumpResult): string {
414
+ function header(kind: OriginKind, result: DumpResult, label: 'SYSTEM PROMPT' | 'USER TURN'): string {
280
415
  const bar = '═'.repeat(78)
281
416
  const summary = `~${result.totalTokens} tok / ${result.totalChars} chars / ${result.totalBytes} bytes (tok est. chars/4)`
282
- return `\n${bar}\n SYSTEM PROMPT — origin: ${kind} — ${summary}\n${bar}\n`
417
+ return `\n${bar}\n ${label} — origin: ${kind} — ${summary}\n${bar}\n`
283
418
  }
284
419
 
285
420
  function renderBreakdownTable(result: DumpResult): string {
@@ -309,6 +444,7 @@ function main(): void {
309
444
  options: {
310
445
  origin: { type: 'string', short: 'o', default: 'all' },
311
446
  'no-git-nudge': { type: 'boolean', default: false },
447
+ turn: { type: 'boolean', default: false },
312
448
  help: { type: 'boolean', short: 'h', default: false },
313
449
  },
314
450
  allowPositionals: false,
@@ -317,15 +453,17 @@ function main(): void {
317
453
  if (values.help) {
318
454
  process.stdout.write(
319
455
  [
320
- 'Usage: bun run debug:prompt [--origin <kind>] [--no-git-nudge]',
456
+ 'Usage: bun run debug:prompt [--turn] [--origin <kind>] [--no-git-nudge]',
321
457
  '',
322
- 'Dump the rendered system prompt for one or all session-origin kinds,',
458
+ 'Dump the rendered system prompt, or the per-turn user message with --turn,',
459
+ 'for one or all session-origin kinds,',
323
460
  'using placeholder values for every dynamic field. Each dump is prefixed',
324
461
  'with a per-section breakdown showing approximate tokens (chars/4),',
325
462
  'character count, and UTF-8 byte length.',
326
463
  '',
327
464
  'Options:',
328
465
  ' -o, --origin <kind> tui | cron | channel | subagent | all (default: all)',
466
+ ' --turn dump the non-cacheable user-turn message instead',
329
467
  ' --no-git-nudge omit the "Uncommitted changes at session start" block',
330
468
  ' -h, --help show this help',
331
469
  '',
@@ -348,18 +486,15 @@ function main(): void {
348
486
  })()
349
487
 
350
488
  for (const kind of kinds) {
351
- const result = dumpSystemPromptWithBreakdown(kind, { gitNudge: !values['no-git-nudge'] })
352
- process.stdout.write(header(kind, result))
489
+ const result = values.turn
490
+ ? dumpTurnPromptWithBreakdown(kind)
491
+ : dumpSystemPromptWithBreakdown(kind, { gitNudge: !values['no-git-nudge'] })
492
+ process.stdout.write(header(kind, result, values.turn ? 'USER TURN' : 'SYSTEM PROMPT'))
353
493
  process.stdout.write(renderBreakdownTable(result))
354
494
  process.stdout.write('\n\n')
355
495
  process.stdout.write(result.prompt)
356
496
  process.stdout.write('\n')
357
497
  }
358
-
359
- const anchor = renderTurnTimeAnchor(PLACEHOLDER_NOW)
360
- const bar = '═'.repeat(78)
361
- process.stdout.write(`\n${bar}\n PER-TURN INJECTION (prepended to every user message)\n${bar}\n\n`)
362
- process.stdout.write(`${anchor}\n`)
363
498
  }
364
499
 
365
500
  if (import.meta.main) {
@@ -354,6 +354,8 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
354
354
  sessionId: opts.sessionId,
355
355
  callId: toolCallId,
356
356
  args: mutableArgs,
357
+ toolProvenance: 'plugin',
358
+
357
359
  ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
358
360
  ...(tool.fileOperands !== undefined ? { fileOperands: tool.fileOperands } : {}),
359
361
  }
@@ -388,6 +390,7 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
388
390
  tool: opts.toolName,
389
391
  args: before.args,
390
392
  agentDir: opts.agentDir,
393
+ toolProvenance: 'plugin',
391
394
  genericInputs: true,
392
395
  fileOperands: tool.fileOperands,
393
396
  logger: opts.logger,
@@ -453,6 +456,7 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
453
456
  sessionId: opts.sessionId,
454
457
  callId: toolCallId,
455
458
  args: mutableArgs,
459
+ toolProvenance: 'first-party',
456
460
  ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
457
461
  ...(preflightFileOperands !== undefined ? { fileOperands: preflightFileOperands } : {}),
458
462
  })
@@ -485,6 +489,7 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
485
489
  tool: tool.name,
486
490
  args: mutableArgs,
487
491
  agentDir: opts.agentDir,
492
+ toolProvenance: 'first-party',
488
493
  genericInputs: tool.name !== 'mcp_call',
489
494
  ...(opts.permissions !== undefined
490
495
  ? { hidden: resolveHiddenPaths(opts.permissions, liveOrigin, opts.agentDir) }
@@ -562,6 +567,7 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
562
567
  sessionId: opts.sessionId,
563
568
  callId: toolCallId,
564
569
  args: mutableArgs,
570
+ toolProvenance: 'first-party',
565
571
  ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
566
572
  })
567
573
  if (blockResult !== undefined) {
@@ -646,6 +652,7 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
646
652
  tool: tool.name,
647
653
  args: attemptArgs,
648
654
  agentDir: opts.agentDir,
655
+ toolProvenance: 'first-party',
649
656
  ...(opts.permissions !== undefined
650
657
  ? {
651
658
  hidden:
@@ -11,7 +11,7 @@ import {
11
11
  createPrivateSurfaceReadIdentityVerifier,
12
12
  type PrivateSurfaceIdentityVerifier,
13
13
  } from '@/bundled-plugins/security/policies/private-surface-read'
14
- import type { ToolFileOperands, ToolLogger, ToolResult } from '@/plugin'
14
+ import type { ToolFileOperands, ToolLogger, ToolProvenance, ToolResult } from '@/plugin'
15
15
  import { CANONICAL_AGENT_SECRET_FILES } from '@/sandbox/canonical-secrets'
16
16
  import type { HiddenPaths } from '@/sandbox/hidden-paths'
17
17
 
@@ -84,6 +84,7 @@ export async function enforceAndPinToolFiles(
84
84
  hidden?: HiddenPaths
85
85
  logger?: Pick<ToolLogger, 'warn'>
86
86
  signal?: AbortSignal
87
+ toolProvenance?: ToolProvenance
87
88
  },
88
89
  hooks: EnforceAndPinToolFilesHooks = {},
89
90
  ): Promise<PinnedToolFiles> {
@@ -97,6 +98,7 @@ export async function enforceAndPinToolFiles(
97
98
  options.fileOperands,
98
99
  options.agentDir,
99
100
  options.logger,
101
+ options.toolProvenance,
100
102
  )
101
103
  enforceCanonicalSecretDenial(options)
102
104
  const outputs = outputTargets(options.tool, options.args, TOOL_OUTPUT_MAX_COUNT, options.fileOperands)
@@ -254,9 +256,16 @@ export function enforceCanonicalSecretDenial(options: {
254
256
  tool: string
255
257
  args: Record<string, unknown>
256
258
  agentDir: string
259
+ toolProvenance?: ToolProvenance
257
260
  }): void {
258
- const { tool, args, agentDir } = options
259
- const blocked = checkPrivateSurfaceReadGuard({ tool, args, agentDir, hidden: { dirs: [], files: [] } })
261
+ const { tool, args, agentDir, toolProvenance } = options
262
+ const blocked = checkPrivateSurfaceReadGuard({
263
+ tool,
264
+ args,
265
+ agentDir,
266
+ hidden: { dirs: [], files: [] },
267
+ ...(toolProvenance !== undefined ? { toolProvenance } : {}),
268
+ })
260
269
  if (blocked !== undefined) throw new Error(`blocked: ${blocked.reason}`)
261
270
  }
262
271
 
@@ -268,9 +277,10 @@ function fileTargets(
268
277
  fileOperands: ToolFileOperands | undefined,
269
278
  agentDir: string,
270
279
  logger: Pick<ToolLogger, 'warn'> | undefined,
280
+ toolProvenance: ToolProvenance | undefined,
271
281
  ): FileTarget[] {
272
282
  if (isOutputTool(tool)) return []
273
- if (TOOLS_WITHOUT_LOCAL_FILE_OPERANDS.has(tool)) return []
283
+ if (toolProvenance === 'first-party' && TOOLS_WITHOUT_LOCAL_FILE_OPERANDS.has(tool)) return []
274
284
  if (tool === 'read' && typeof args.path === 'string') return [propertyTarget(args, 'path')]
275
285
  if (isTreeInputTool(tool)) {
276
286
  if (typeof args.path !== 'string') args.path = '.'
@@ -29,6 +29,35 @@
29
29
  // a second model family exhibited the same misread, so we accept the
30
30
  // universal cost in exchange for never having to remember to add a new
31
31
  // family to a list.
32
+ // The bracketed marker is what tells the model a block is runtime-emitted, so
33
+ // any untrusted string rendered into a turn must not be able to carry one.
34
+ // Inbound channel text and memory headings/excerpts are both reproduced
35
+ // verbatim, so without this a participant (or a poisoned shard) could forge a
36
+ // fence and inherit whatever standing the real one has.
37
+ //
38
+ // Only the marker is defused, not the `---` rules around it: a horizontal rule
39
+ // is ordinary markdown that appears in pasted diffs, YAML, and tables all the
40
+ // time, and mangling those would corrupt real messages for no gain. The marker
41
+ // is the rare, load-bearing token — neutralize that and the fence cannot form.
42
+ //
43
+ // Matching is deliberately loose (case-insensitive, any wording after the
44
+ // keyword) because an attacker chooses both; the real emitters always produce
45
+ // the canonical form, so a false positive can only ever hit text that was
46
+ // already imitating a runtime marker.
47
+ //
48
+ // Only the OPENER is matched, via a lookahead that consumes nothing past `**[`.
49
+ // Matching the whole `**[...]**` span instead would be exploitable: the span
50
+ // ends at the first `]**`, so a nested opener (`**[SYSTEM MESSAGE a **[SYSTEM
51
+ // MESSAGE b]** c]**`) lands inside the replacement, and `String.replace` never
52
+ // rescans what it just emitted — leaving a live marker behind. Neutralizing
53
+ // openers independently is single-pass safe and idempotent, because the
54
+ // replacement text contains no `**[` for a later pass to find.
55
+ const RUNTIME_MARKER_OPENER = /\*\*\s*\[(?=\s*(?:SYSTEM MESSAGE|MEMORY CONTEXT)\b)/gi
56
+
57
+ export function defuseRuntimeMarkers(text: string): string {
58
+ return text.replace(RUNTIME_MARKER_OPENER, '(quoted from untrusted text) [')
59
+ }
60
+
32
61
  export function fenceRuntimeNotice(body: string): string {
33
62
  return (
34
63
  '\n\n---\n' +