typeclaw 0.39.3 → 0.39.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.
Files changed (42) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +10 -14
  3. package/src/agent/model-fallback.ts +13 -4
  4. package/src/agent/provider-error.ts +36 -1
  5. package/src/agent/subagents.ts +29 -2
  6. package/src/agent/throttle-circuit.ts +50 -0
  7. package/src/agent/turn-runner.ts +162 -0
  8. package/src/bundled-plugins/memory/README.md +12 -12
  9. package/src/bundled-plugins/memory/append-tool.ts +58 -6
  10. package/src/bundled-plugins/memory/dreaming.ts +1 -1
  11. package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
  12. package/src/bundled-plugins/memory/load-memory.ts +28 -2
  13. package/src/bundled-plugins/memory/memory-logger.ts +14 -2
  14. package/src/bundled-plugins/memory/search-tool.ts +50 -7
  15. package/src/bundled-plugins/memory/stream-events.ts +23 -0
  16. package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
  17. package/src/bundled-plugins/security/index.ts +24 -1
  18. package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
  19. package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
  20. package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
  21. package/src/channels/adapters/webex-bot.ts +26 -25
  22. package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
  23. package/src/channels/adapters/webex.ts +27 -30
  24. package/src/channels/manager.ts +64 -57
  25. package/src/channels/router.ts +134 -4
  26. package/src/channels/types.ts +8 -1
  27. package/src/cli/builtins.ts +6 -32
  28. package/src/cli/command-meta.ts +93 -0
  29. package/src/cli/help.ts +24 -0
  30. package/src/cli/index.ts +34 -10
  31. package/src/config/config.ts +27 -1
  32. package/src/container/start.ts +22 -2
  33. package/src/hostd/daemon.ts +55 -26
  34. package/src/hostd/spawn.ts +53 -19
  35. package/src/permissions/permissions.ts +12 -0
  36. package/src/run/codex-fetch-observer.ts +11 -6
  37. package/src/secrets/oauth-xai.ts +2 -2
  38. package/src/server/index.ts +27 -2
  39. package/src/skills/typeclaw-channels/SKILL.md +1 -1
  40. package/src/skills/typeclaw-config/SKILL.md +1 -0
  41. package/src/skills/typeclaw-cron/SKILL.md +9 -4
  42. package/src/skills/typeclaw-permissions/SKILL.md +18 -6
@@ -3,6 +3,7 @@ import { dirname } from 'node:path'
3
3
 
4
4
  import { z } from 'zod'
5
5
 
6
+ import type { SessionOrigin } from '@/agent/session-origin'
6
7
  import { defineTool } from '@/plugin'
7
8
  import { formatLocalDate } from '@/shared'
8
9
 
@@ -10,15 +11,56 @@ import { fragmentContentHash } from './fragment-parser'
10
11
  import { streamFilePath } from './paths'
11
12
  import { detectSecrets } from './secret-detector'
12
13
  import { newEventId, timestampFromId } from './stream-events'
13
- import type { FragmentEvent, WatermarkEvent } from './stream-events'
14
+ import type { FragmentEvent, FragmentProvenance, WatermarkEvent } from './stream-events'
14
15
  import { appendEvents, readEvents, type FragmentsAppendedContext } from './stream-io'
15
16
 
16
17
  export type FragmentsAppendedHook = (fragments: FragmentEvent[], context: FragmentsAppendedContext) => Promise<void>
17
18
 
18
- export function createAppendTool(onFragmentsAppended?: FragmentsAppendedHook) {
19
+ // Lets the memory-logger thread its spawn-time `payload.origin` into the append
20
+ // tool so `where` is stamped server-side. A provider closure (not a static
21
+ // value) because the same factory builds tools whose origin is only known later.
22
+ export type OriginProvider = () => SessionOrigin | undefined
23
+
24
+ export type CreateAppendToolOptions = {
25
+ onFragmentsAppended?: FragmentsAppendedHook
26
+ originProvider?: OriginProvider
27
+ }
28
+
29
+ // Stamped fields are the stable channel coordinates only. Author identity is
30
+ // deliberately excluded: a channel session sees many speakers and the origin's
31
+ // `lastInboundAuthorId` is just the spawn-time one, so attributing it to every
32
+ // fragment would misattribute fragments about earlier speakers. `who` is the
33
+ // LLM's job, per fragment, from the transcript speaker line.
34
+ export function provenanceFromOrigin(origin: SessionOrigin | undefined): FragmentProvenance | undefined {
35
+ if (origin === undefined || origin.kind !== 'channel') return undefined
36
+ const where: FragmentProvenance = {
37
+ adapter: origin.adapter,
38
+ workspace: origin.workspace,
39
+ chat: origin.chat,
40
+ thread: origin.thread,
41
+ }
42
+ // workspaceName/chatName are external channel data force-committed to memory.
43
+ // The agent cannot rewrite them (they come from the origin, not a tool arg),
44
+ // so a credential-shaped name is dropped rather than thrown — keep the raw id,
45
+ // never let the leaky display string reach git. Raw ids are platform-issued
46
+ // identifiers, not free text, so they are not scanned.
47
+ const workspaceName = redactIfSecret(origin.workspaceName)
48
+ const chatName = redactIfSecret(origin.chatName)
49
+ if (workspaceName !== undefined) where.workspaceName = workspaceName
50
+ if (chatName !== undefined) where.chatName = chatName
51
+ return where
52
+ }
53
+
54
+ function redactIfSecret(name: string | undefined): string | undefined {
55
+ if (name === undefined) return undefined
56
+ return detectSecrets(name).length === 0 ? name : undefined
57
+ }
58
+
59
+ export function createAppendTool(options: CreateAppendToolOptions = {}) {
60
+ const { onFragmentsAppended, originProvider } = options
19
61
  return defineTool({
20
62
  description:
21
- "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). Refuses content with recognized credential patterns and refuses byte-equivalent topic+body within the same daily stream.",
63
+ "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). `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.",
22
64
  parameters: z.object({
23
65
  topic: z.string().min(1),
24
66
  body: z.string().min(1),
@@ -26,10 +68,17 @@ export function createAppendTool(onFragmentsAppended?: FragmentsAppendedHook) {
26
68
  entry: z.string().min(1),
27
69
  latestEntryId: z.string().min(1),
28
70
  references: z.array(z.string()).optional(),
71
+ who: z.string().min(1).optional(),
29
72
  }),
30
- async execute({ topic, body, source, entry, latestEntryId, references }, ctx) {
73
+ async execute({ topic, body, source, entry, latestEntryId, references, who }, ctx) {
31
74
  const streamPath = dailyStreamPath(ctx.agentDir)
32
- assertNoSecrets(`${topic}\n${body}`)
75
+ const where = provenanceFromOrigin(originProvider?.())
76
+ // `who` is LLM-supplied and force-committed to memory, so it clears the
77
+ // same secret guard as topic/body — a token-shaped display name is refused
78
+ // with the same retryable error. (`where` names are origin-derived and the
79
+ // agent can't rewrite them, so they are self-redacted in provenanceFromOrigin
80
+ // instead of throwing here.)
81
+ assertNoSecrets([topic, body, who])
33
82
 
34
83
  const hash = fragmentContentHash({ topic, body })
35
84
  const events = await readEvents(streamPath)
@@ -58,6 +107,8 @@ export function createAppendTool(onFragmentsAppended?: FragmentsAppendedHook) {
58
107
  if (references !== undefined && references.length > 0) {
59
108
  fragment.references = references
60
109
  }
110
+ if (who !== undefined) fragment.who = who
111
+ if (where !== undefined) fragment.where = where
61
112
  const watermark: WatermarkEvent = {
62
113
  type: 'watermark',
63
114
  id: watermarkId,
@@ -122,7 +173,8 @@ function dailyStreamPath(agentDir: string): string {
122
173
  return streamFilePath(agentDir, formatLocalDate())
123
174
  }
124
175
 
125
- function assertNoSecrets(content: string): void {
176
+ function assertNoSecrets(parts: ReadonlyArray<string | undefined>): void {
177
+ const content = parts.filter((part): part is string => part !== undefined).join('\n')
126
178
  const secrets = detectSecrets(content)
127
179
  if (secrets.length === 0) return
128
180
 
@@ -1010,7 +1010,7 @@ A fragment with no useful content (a watermark-only marker, a near-duplicate, a
1010
1010
 
1011
1011
  **5. Rebalance every run. Preserve every fact and every cited fragment id.** The shard set is a saturated surface (a fixed prompt-budget), not an append-only log — every run is consolidation, not just the runs that get new fragments. You may merge near-duplicate topics into one, split overloaded topics, rename unclear slugs/headings, and rewrite verbose conclusion paragraphs more tightly. What you must NOT do: drop a fragment id. The merged topic's \`fragments:\` list is the **union** of its source topics' fragment ids. The daily-stream GC depends on shard citations to keep evidence alive; an omitted id means the underlying fragment is permanently deleted on the next compaction. If two topics genuinely cover different facts, leave them separate — premature merging loses signal. If a new fragment contradicts an existing entry, replace the entry's conclusion paragraph to state the new current truth, and **move the old, now-overturned fragment id from \`fragments:\` into a \`superseded:\` list** in the same shard (the new fragment id goes under \`fragments:\`). Both lists keep the ids cited, so no evidence is lost — but \`superseded:\` marks the old evidence as history, not current truth, so retrieval no longer surfaces it as a hook for the new belief. Citation-superset invariant: every previously-cited fragment id must still appear cited in at least one shard after your run, in EITHER \`fragments:\` or \`superseded:\`. If you violate this, the runtime reverts your whole run.
1012
1012
 
1013
- **6. Write a compact belief, not an essay.** An ordinary belief topic's body is **one compact belief sentence** stating the current truth — a durable fact about the user, project, or environment — placed before \`fragments:\`. It carries the subject, the predicate (the preference/habit/fact/decision), and only the essential scope qualifier needed to avoid overgeneralizing ("for this repo", "when committing", "in host-stage code"). Do NOT explain the evidence, the history, or the reasoning ("because…") — the \`fragments:\` and \`superseded:\` citation lists carry that. No lists of preferences ("the user likes X, Y, Z"), no labels, no markdown headings, no multiple sentences. One topic per concept. Keep the sentence natural and keyword-rich (it is embedded and keyword-searched) — do not compress into telegraphic fragments like "bun/typecheck/lint". Smaller bodies let more topics stay in the directly-injected budget, so tightness is load-bearing, not cosmetic. **Exception: CLI/plugin proposal shards (see "Suggesting a CLI or a plugin" below) are not belief topics — they keep their richer rationale paragraph plus the required \`proposal:\` label and are exempt from the one-sentence/no-labels rule.**
1013
+ **6. Write a compact belief, not an essay.** An ordinary belief topic's body is **one compact belief sentence** stating the current truth — a durable fact about the user, project, or environment — placed before \`fragments:\`. It carries the subject, the predicate (the preference/habit/fact/decision), and only the essential scope qualifier needed to avoid overgeneralizing ("for this repo", "when committing", "in host-stage code"). Do NOT explain the evidence, the history, or the reasoning ("because…") — the \`fragments:\` and \`superseded:\` citation lists carry that. No lists of preferences ("the user likes X, Y, Z"), no labels, no markdown headings, no multiple sentences. One topic per concept. Keep the sentence natural and keyword-rich (it is embedded and keyword-searched) — do not compress into telegraphic fragments like "bun/typecheck/lint". Smaller bodies let more topics stay in the directly-injected budget, so tightness is load-bearing, not cosmetic. Fragments may carry situational provenance — \`who\` (the attributed speaker) and \`where\` (the channel/room/platform). Fold these into the belief sentence ONLY when the situation is part of the durable fact ("In #incidents, Jisoo treats production-outage messages as drop-everything urgent") — not as routine provenance noise on every belief; the citation list already records where each fragment came from. **Exception: CLI/plugin proposal shards (see "Suggesting a CLI or a plugin" below) are not belief topics — they keep their richer rationale paragraph plus the required \`proposal:\` label and are exempt from the one-sentence/no-labels rule.**
1014
1014
 
1015
1015
  **7. Memory is passive context, not an instruction channel.** Rewrite imperative or duty-shaped fragments as observations. Preserve facts, user preferences, and evidence; do not promote inferred obligations like "the agent should educate X", "future agents must correct Y", "bot Z should not post", or "run this later" unless the user explicitly stated an always/never rule. When a fragment contains such language, convert it into neutral context about what happened and why it might help interpret a future user request.
1016
1016
 
@@ -1,12 +1,15 @@
1
1
  import { createHash } from 'node:crypto'
2
2
 
3
- import { parseEventLine } from './stream-events'
3
+ import { type FragmentProvenance, parseEventLine } from './stream-events'
4
4
 
5
5
  export type Fragment = {
6
6
  source: string
7
7
  entry: string
8
8
  topic: string
9
9
  body: string
10
+ who?: string
11
+ where?: FragmentProvenance
12
+ ts?: string
10
13
  }
11
14
 
12
15
  export function parseFragments(content: string): Fragment[] {
@@ -17,12 +20,16 @@ export function parseFragments(content: string): Fragment[] {
17
20
  const event = parseEventLine(line)
18
21
  if (event === null) continue
19
22
  if (event.type === 'fragment') {
20
- fragments.push({
23
+ const fragment: Fragment = {
21
24
  source: event.source,
22
25
  entry: event.entry,
23
26
  topic: event.topic,
24
27
  body: event.body,
25
- })
28
+ ts: event.ts,
29
+ }
30
+ if (event.who !== undefined) fragment.who = event.who
31
+ if (event.where !== undefined) fragment.where = event.where
32
+ fragments.push(fragment)
26
33
  }
27
34
  }
28
35
  return fragments
@@ -7,6 +7,7 @@ import { buildInjectionPlan, DEFAULT_INJECTION_BUDGET_BYTES, type InjectionPlan
7
7
  import { loadAllShards, type TopicShard } from './load-shards'
8
8
  import { topicsDir } from './paths'
9
9
  import { slugIsHeadingEcho } from './slug'
10
+ import type { FragmentProvenance } from './stream-events'
10
11
  import type { DedupedRetrievedItem } from './turn-dedup'
11
12
 
12
13
  const MAX_FILE_BYTES = 12 * 1024
@@ -85,6 +86,21 @@ export type RetrievedMemoryItem = {
85
86
  key: string
86
87
  heading: string
87
88
  excerpt: string
89
+ who?: string
90
+ when?: string
91
+ where?: FragmentProvenance
92
+ }
93
+
94
+ // A one-line "<who> in <#room> on <date>" prefix for a stream fragment so a
95
+ // retrieved recent observation carries its situational provenance. Only the
96
+ // parts that exist are shown; an undreamed fragment with none renders nothing.
97
+ export function renderProvenanceLine(item: Pick<RetrievedMemoryItem, 'who' | 'when' | 'where'>): string | null {
98
+ const parts: string[] = []
99
+ if (item.who !== undefined) parts.push(item.who)
100
+ const room = item.where?.chatName ?? item.where?.chat
101
+ if (room !== undefined) parts.push(`in ${item.where?.chatName !== undefined ? `#${room}` : room}`)
102
+ if (item.when !== undefined) parts.push(`on ${item.when.slice(0, 10)}`)
103
+ return parts.length === 0 ? null : `_${parts.join(' ')}_`
88
104
  }
89
105
 
90
106
  // Per-turn vector retrieval keeps repeated content compact across a session: a
@@ -97,7 +113,13 @@ export function renderDedupedRetrievedMemorySection(entries: DedupedRetrievedIte
97
113
  const lines = ['# Memory', '', MEMORY_FRAMING, '']
98
114
  for (const { item, changed } of entries) {
99
115
  lines.push(`## ${item.heading}`)
100
- lines.push(changed ? item.excerpt.trimEnd() : unchangedRetrievedItemReference(item), '')
116
+ if (changed) {
117
+ const provenance = renderProvenanceLine(item)
118
+ if (provenance !== null) lines.push(provenance)
119
+ lines.push(item.excerpt.trimEnd(), '')
120
+ } else {
121
+ lines.push(unchangedRetrievedItemReference(item), '')
122
+ }
101
123
  }
102
124
  return lines.join('\n').trimEnd()
103
125
  }
@@ -129,11 +151,15 @@ export function renderRetrievedMemorySection(
129
151
  for (const item of items) {
130
152
  if (!isChannel) {
131
153
  lines.push(`## ${item.heading}`)
154
+ const provenance = renderProvenanceLine(item)
155
+ if (provenance !== null) lines.push(provenance)
132
156
  lines.push(item.excerpt.trimEnd(), '')
133
157
  } else if (item.source === 'topic' || item.source === 'reference') {
134
158
  lines.push(topicIndexEntry(item.heading, item.key))
135
159
  } else {
136
- lines.push(`- ${item.heading} _(recent observation)_`)
160
+ const provenance = renderProvenanceLine(item)
161
+ const suffix = provenance === null ? '' : ` ${provenance}`
162
+ lines.push(`- ${item.heading} _(recent observation)_${suffix}`)
137
163
  }
138
164
  }
139
165
  return lines.join('\n').trimEnd()
@@ -165,7 +165,7 @@ When a transcript exposes a credential, capture the fact and discovery method, n
165
165
  - Allowed: "The env var \`GH_TOKEN\` is set in this environment and holds a GitHub PAT (discovered via \`env | grep token\`). Use it for private-repo API calls."
166
166
  - Forbidden: "GH_TOKEN=<the literal token characters, in whole or in part>". Even a partial value narrows the search space for an attacker.
167
167
 
168
- The \`append\` tool will refuse content containing a recognizable credential pattern. Treat that as a bug in your fragment: rewrite to name the variable and discovery, then retry.
168
+ The \`append\` tool will refuse content containing a recognizable credential pattern — in \`topic\`, \`body\`, or \`who\`. Treat that as a bug in your fragment: rewrite to name the variable and discovery (or drop a credential-shaped \`who\`), then retry.
169
169
 
170
170
  # Local dedup against today's daily stream
171
171
 
@@ -181,6 +181,11 @@ Recurrence is not duplication. A durable preference, pattern, workaround, or com
181
181
 
182
182
  Call \`append\` with \`{topic, body, source, entry, latestEntryId}\` or \`{topic, body, source, entry, latestEntryId, references}\`. The runtime serializes your call into the daily stream; you never write raw JSON. \`source\` is the parent session id. \`topic\` is a short noun phrase. \`entry\` is the specific transcript-entry-id that anchors this fragment's evidence. Each fragment carries its own entry id; do not stamp every fragment with the same latest evaluated id. \`latestEntryId\` is the latest entry evaluated in this run and advances the watermark. \`references\` is optional slugs from \`store_reference\`.
183
183
 
184
+ **Situational provenance (\`who\` / \`where\`).** Memory is sharper when it remembers who said something and where. Two fields capture this:
185
+
186
+ - **\`where\` is automatic.** The channel, room, and platform of this session are stamped onto every fragment by the runtime from the session origin. Do NOT pass \`where\` and do NOT restate the channel/workspace/thread in the body just to record provenance — it is already attached. Still name a channel in the body when its *purpose* is the durable fact (e.g. "#incidents is the production-outage channel"); that is content, not provenance plumbing.
187
+ - **\`who\` is your judgment, per fragment.** Set the optional \`who\` to the display name or handle of the person whose words or action the fragment's evidence is attributable to — the speaker on the transcript line you anchored to. The Conversation context lists participant names and ids; use them to attribute correctly. Set \`who\` ONLY when one speaker clearly owns the evidence. OMIT it when: the fact is the user's own instruction (the user is implicit), the evidence spans multiple speakers, or you cannot attribute it to one person with confidence. A single run covers many speakers and turns, so never copy one name onto every fragment — attribute each fragment to its own anchored speaker, or leave \`who\` unset. Do not guess.
188
+
184
189
  Every body must be:
185
190
 
186
191
  1. **Self-contained.** A future agent can read it without the transcript. Replace pronouns with names and include enough context to stand alone.
@@ -286,7 +291,13 @@ export function createMemoryLoggerSubagent(
286
291
  options: CreateMemoryLoggerSubagentOptions = {},
287
292
  ): Subagent<MemoryLoggerPayload> {
288
293
  const logger = options.logger ?? consoleLogger
289
- const appendTool = createAppendTool(options.onFragmentsAppended)
294
+ // The handler runs one logger spawn at a time per agentDir (inFlightKey), so a
295
+ // single mutable cell safely carries this spawn's origin to the append tool.
296
+ let currentOrigin: SessionOrigin | undefined
297
+ const appendTool = createAppendTool({
298
+ onFragmentsAppended: options.onFragmentsAppended,
299
+ originProvider: () => currentOrigin,
300
+ })
290
301
  const storeReferenceTool = createStoreReferenceTool(options.onReferenceStored)
291
302
  const customTools = [findEntryTool, appendTool, storeReferenceTool, advanceWatermarkTool]
292
303
  return {
@@ -317,6 +328,7 @@ export function createMemoryLoggerSubagent(
317
328
  exhaustedMessage: memoryLoggerExhaustedMessage,
318
329
  },
319
330
  handler: async (ctx, runSession) => {
331
+ currentOrigin = ctx.payload.origin
320
332
  const today = formatLocalDate()
321
333
  const memoryDir = streamsDir(ctx.payload.agentDir)
322
334
  const streamFile = streamFilePath(ctx.payload.agentDir, today)
@@ -7,7 +7,7 @@ import { defineTool } from '@/plugin'
7
7
  import { loadAllShards, loadShard, type TopicShard } from './load-shards'
8
8
  import { renderReference } from './references/frontmatter'
9
9
  import { loadAllReferences, loadReference, type Reference } from './references/load-references'
10
- import type { FragmentEvent, LegacyProseEvent, StreamEvent } from './stream-events'
10
+ import type { FragmentEvent, FragmentProvenance, LegacyProseEvent, StreamEvent } from './stream-events'
11
11
  import { readAllUndreamedStreamDays, type UndreamedStreamDay } from './stream-io'
12
12
 
13
13
  const DEFAULT_MAX_RESULTS = 10
@@ -31,6 +31,9 @@ export type StreamMatch = {
31
31
  topic: string
32
32
  excerpt: string
33
33
  fullBody?: string
34
+ who?: string
35
+ when?: string
36
+ where?: FragmentProvenance
34
37
  }
35
38
 
36
39
  export type ReferenceMatch = {
@@ -51,7 +54,7 @@ export type Matcher = (haystack: string) => boolean
51
54
  export function createMemorySearchTool() {
52
55
  return defineTool({
53
56
  description:
54
- 'Search the agent\'s long-term memory, or look up one topic shard by exact slug. Covers topic shards under memory/topics/ (consolidated facts), references under memory/references/ (verbatim artifacts), and undreamed daily-stream events under memory/streams/ (recent fragments not yet folded into shards). Pass `query` for search OR `topic` for an exact slug lookup, not both. Search is case-insensitive substring by default: tries the whole query as one phrase first, and if that finds nothing, falls back to OR-matching the individual words (ranked by how many words each hit contains) — so a multi-word query still returns results even when no entry contains the exact phrase. asRegex=true treats query as a JavaScript regex (no word fallback). `topic` skips search entirely and returns that one shard (or reference) with its full body — use it to read a topic OR reference whose slug you already have (e.g. a heading shown in injected memory); it resolves the topic shard first and falls back to a reference of the same slug. Returns matches discriminated by `source: "topic" | "reference" | "stream"`, each with line-context excerpts; full=true includes complete bodies (topic lookups always include the full body). Ordering depends on mode: exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then reference matches, then stream matches (newest day first); word-fallback results are ranked by matched-word count, with that same topic-then-reference-then-stream-newest order as the tiebreak within each score band, so a higher-scoring stream match can precede a lower-scoring topic match.',
57
+ 'Search the agent\'s long-term memory, or look up one topic shard by exact slug. Covers topic shards under memory/topics/ (consolidated facts), references under memory/references/ (verbatim artifacts), and undreamed daily-stream events under memory/streams/ (recent fragments not yet folded into shards). Pass `query` for search OR `topic` for an exact slug lookup, not both. Search is case-insensitive substring by default: tries the whole query as one phrase first, and if that finds nothing, falls back to OR-matching the individual words (ranked by how many words each hit contains) — so a multi-word query still returns results even when no entry contains the exact phrase. asRegex=true treats query as a JavaScript regex (no word fallback). `topic` skips search entirely and returns that one shard (or reference) with its full body — use it to read a topic OR reference whose slug you already have (e.g. a heading shown in injected memory); it resolves the topic shard first and falls back to a reference of the same slug. Returns matches discriminated by `source: "topic" | "reference" | "stream"`, each with line-context excerpts; full=true includes complete bodies (topic lookups always include the full body). Ordering depends on mode: exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then reference matches, then stream matches (newest day first); word-fallback results are ranked by matched-word count, with that same topic-then-reference-then-stream-newest order as the tiebreak within each score band, so a higher-scoring stream match can precede a lower-scoring topic match. Pass `where` (a channel/room name like "#incidents" or its raw chat id) to scope the search to one room — use it for questions like "what did we discuss in #incidents"; it matches a stream fragment by its captured room id or human-readable name (case-insensitive, leading "#" optional) and, because room is fragment-only provenance, returns ONLY stream matches (topic shards and references carry no room).',
55
58
  parameters: z.object({
56
59
  query: z.string().optional(),
57
60
  topic: z.string().optional(),
@@ -60,8 +63,9 @@ export function createMemorySearchTool() {
60
63
  maxResults: z.number().int().min(0).default(DEFAULT_MAX_RESULTS),
61
64
  since: z.string().optional(),
62
65
  before: z.string().optional(),
66
+ where: z.string().optional(),
63
67
  }),
64
- async execute({ query, topic, asRegex, full, maxResults, since, before }, ctx) {
68
+ async execute({ query, topic, asRegex, full, maxResults, since, before, where }, ctx) {
65
69
  if ((query === undefined) === (topic === undefined)) {
66
70
  return resultToToolResult({ error: 'provide exactly one of `query` or `topic`' })
67
71
  }
@@ -83,14 +87,24 @@ export function createMemorySearchTool() {
83
87
  const dateFilter = parseReferenceDateFilter(since, before)
84
88
  if ('error' in dateFilter) return resultToToolResult(dateFilter)
85
89
 
86
- const references = allReferences.filter((reference) => referenceCandidateAllowed(reference, dateFilter))
87
- if (shards.length === 0 && streamDays.length === 0 && references.length === 0) {
90
+ // A `where` filter scopes the search to ONE room. `where` is fragment-only
91
+ // provenance, so a room query excludes topic shards and references (they
92
+ // carry no room) and keeps only stream fragments whose `where` matches.
93
+ const roomFilteredDays = where === undefined ? streamDays : filterStreamDaysByRoom(streamDays, where)
94
+ const scopedShards = where === undefined ? shards : []
95
+ const references =
96
+ where === undefined ? allReferences.filter((r) => referenceCandidateAllowed(r, dateFilter)) : []
97
+
98
+ if (scopedShards.length === 0 && roomFilteredDays.length === 0 && references.length === 0) {
88
99
  return resultToToolResult({ matches: [], truncatedAt: 0 })
89
100
  }
90
101
 
91
- let result = searchAll(shards, streamDays, matcherOrError, { full, maxResults, references })
102
+ let result = searchAll(scopedShards, roomFilteredDays, matcherOrError, { full, maxResults, references })
92
103
  if ('matches' in result && result.matches.length === 0) {
93
- const fallback = tokenFallback(query!, asRegex, shards, streamDays, references, { full, maxResults })
104
+ const fallback = tokenFallback(query!, asRegex, scopedShards, roomFilteredDays, references, {
105
+ full,
106
+ maxResults,
107
+ })
94
108
  if (fallback !== null) result = fallback
95
109
  }
96
110
  if ('matches' in result) await bumpReturnedReferences(allReferences, result.matches)
@@ -449,7 +463,10 @@ function matchFragmentEvent(
449
463
  eventId: `streams/${day.date}#${event.id}`,
450
464
  topic: event.topic,
451
465
  excerpt: firstBodyLineIndex === -1 ? event.topic : excerptForLine(bodyLines, firstBodyLineIndex),
466
+ when: event.ts,
452
467
  }
468
+ if (event.who !== undefined) match.who = event.who
469
+ if (event.where !== undefined) match.where = event.where
453
470
  if (full) match.fullBody = event.body
454
471
  return match
455
472
  }
@@ -513,6 +530,32 @@ function parseDateParam(name: string, value: string): Date | string {
513
530
  return date
514
531
  }
515
532
 
533
+ // Keep only fragments whose `where` names this room, by raw `chat` id (canonical)
534
+ // or `chatName` (convenience, case-insensitive — the agent often knows only
535
+ // "#incidents"). The `#` prefix is stripped so "#incidents" and "incidents"
536
+ // both match. Non-fragment events (watermarks, legacy prose) have no `where` and
537
+ // are dropped under a room filter; days that end up empty are removed.
538
+ function filterStreamDaysByRoom(days: UndreamedStreamDay[], room: string): UndreamedStreamDay[] {
539
+ const normalizedKey = normalizeRoomKey(room)
540
+ return days.flatMap((day) => {
541
+ const events = day.events.filter(
542
+ (event) => event.type === 'fragment' && fragmentMatchesRoom(event, room, normalizedKey),
543
+ )
544
+ return events.length === 0 ? [] : [{ ...day, events }]
545
+ })
546
+ }
547
+
548
+ function fragmentMatchesRoom(event: FragmentEvent, rawRoom: string, normalizedKey: string): boolean {
549
+ const where = event.where
550
+ if (where === undefined) return false
551
+ if (where.chat === rawRoom) return true
552
+ return where.chatName !== undefined && normalizeRoomKey(where.chatName) === normalizedKey
553
+ }
554
+
555
+ function normalizeRoomKey(value: string): string {
556
+ return value.replace(/^#/, '').toLocaleLowerCase()
557
+ }
558
+
516
559
  function referenceCandidateAllowed(reference: Reference, filter: ReferenceDateFilter): boolean {
517
560
  if (reference.frontmatter.demoted) return false
518
561
  const created = new Date(reference.frontmatter.created)
@@ -30,6 +30,21 @@ export function timestampFromId(id: string): string {
30
30
  return new Date(ms).toISOString()
31
31
  }
32
32
 
33
+ // Runtime-stamped (not LLM-supplied): the channel/room/platform is stable for a
34
+ // whole logger run, so unlike `who` it cannot be misattributed across speakers.
35
+ // All-optional so legacy fragments and non-channel (TUI) origins parse with it
36
+ // absent; names are best-effort (resolver may not have run). Never embedded.
37
+ export const fragmentProvenanceSchema = z
38
+ .object({
39
+ adapter: z.string(),
40
+ workspace: z.string(),
41
+ workspaceName: z.string().optional(),
42
+ chat: z.string(),
43
+ chatName: z.string().optional(),
44
+ thread: z.string().nullable().optional(),
45
+ })
46
+ .passthrough()
47
+
33
48
  export const fragmentEventSchema = z
34
49
  .object({
35
50
  type: z.literal('fragment'),
@@ -40,6 +55,13 @@ export const fragmentEventSchema = z
40
55
  topic: z.string(),
41
56
  body: z.string(),
42
57
  references: z.array(z.string()).optional(),
58
+ // WHO the evidence is attributable to (display name/handle of the speaker).
59
+ // LLM-supplied by the memory-logger, set ONLY when one transcript speaker
60
+ // line clearly owns the evidence — a single logger run spans many speakers,
61
+ // so this is per-fragment, never stamped from the spawn-time origin.
62
+ who: z.string().min(1).optional(),
63
+ // WHERE the evidence happened. Runtime-stamped from the session origin.
64
+ where: fragmentProvenanceSchema.optional(),
43
65
  })
44
66
  .passthrough()
45
67
 
@@ -68,6 +90,7 @@ export const streamEventSchema = z.discriminatedUnion('type', [
68
90
  legacyProseEventSchema,
69
91
  ])
70
92
 
93
+ export type FragmentProvenance = z.infer<typeof fragmentProvenanceSchema>
71
94
  export type FragmentEvent = z.infer<typeof fragmentEventSchema>
72
95
  export type WatermarkEvent = z.infer<typeof watermarkEventSchema>
73
96
  export type LegacyProseEvent = z.infer<typeof legacyProseEventSchema>
@@ -12,7 +12,7 @@ import {
12
12
  type MemorySearchMatch,
13
13
  type StreamMatch,
14
14
  } from '../search-tool'
15
- import type { StreamEvent } from '../stream-events'
15
+ import type { FragmentProvenance, StreamEvent } from '../stream-events'
16
16
  import { readAllUndreamedStreamDays, type UndreamedStreamDay } from '../stream-io'
17
17
  import { embed, EMBEDDING_MODEL_ID, type EmbedType } from './embedder'
18
18
  import type { Passage } from './passages'
@@ -29,6 +29,9 @@ export type HybridSearchResult = {
29
29
  heading: string
30
30
  excerpt: string
31
31
  rrfScore: number
32
+ who?: string
33
+ when?: string
34
+ where?: FragmentProvenance
32
35
  }
33
36
 
34
37
  export type EmbedFn = (texts: string[], type: EmbedType) => Promise<Float32Array[]>
@@ -398,12 +401,16 @@ function streamIndexItem(
398
401
  if (event.type === 'watermark') return null
399
402
  if (event.type === 'fragment') {
400
403
  if (supersededFragmentIds.has(event.id)) return null
401
- return {
404
+ const item: Omit<HybridSearchResult, 'rrfScore'> = {
402
405
  source: 'stream',
403
406
  key: `${day.date}#${event.id}`,
404
407
  heading: event.topic,
405
408
  excerpt: excerpt(event.body, event.topic),
409
+ when: event.ts,
406
410
  }
411
+ if (event.who !== undefined) item.who = event.who
412
+ if (event.where !== undefined) item.where = event.where
413
+ return item
407
414
  }
408
415
  return {
409
416
  source: 'stream',
@@ -106,6 +106,24 @@ export default definePlugin({
106
106
  const canBypass = (severity: SecuritySeverity, perGuardPerm: string): boolean =>
107
107
  can(SEVERITY_PERMISSION[severity]) || can(perGuardPerm)
108
108
 
109
+ // The cron guard blocks deferred work that fires as a role granting
110
+ // permissions the caller lacks. Capability dominance — target's
111
+ // permission set must be a SUBSET of the caller's — not the coarse
112
+ // `compareRoleSeverity` tower: every configured custom role ranks
113
+ // equal there, so rank `>= 0` would let one custom role schedule as a
114
+ // different custom role (or `trusted` schedule as a custom role with
115
+ // an extra grant), laundering permissions the caller never had. Unknown
116
+ // caller/target role => undefined permissions => fail closed.
117
+ const callerRole = ctx.permissions.resolveRole(event.origin)
118
+ const canScheduleAs = (targetRole: string | undefined): boolean => {
119
+ if (targetRole === undefined) return false
120
+ const callerPermissions = ctx.permissions.permissionsForRole(callerRole)
121
+ const targetPermissions = ctx.permissions.permissionsForRole(targetRole)
122
+ if (callerPermissions === undefined || targetPermissions === undefined) return false
123
+ const callerSet = new Set(callerPermissions)
124
+ return targetPermissions.every((permission) => callerSet.has(permission))
125
+ }
126
+
109
127
  const rolePromotionResult = canBypass(GUARD_ROLE_PROMOTION_SEVERITY, SECURITY_PERMISSIONS.bypassRolePromotion)
110
128
  ? undefined
111
129
  : withPermissionHint(
@@ -118,7 +136,12 @@ export default definePlugin({
118
136
  const cronPromotionResult = canBypass(GUARD_CRON_PROMOTION_SEVERITY, SECURITY_PERMISSIONS.bypassCronPromotion)
119
137
  ? undefined
120
138
  : withPermissionHint(
121
- await checkCronPromotionGuard({ tool: event.tool, args: event.args, agentDir: ctx.agentDir }),
139
+ await checkCronPromotionGuard({
140
+ tool: event.tool,
141
+ args: event.args,
142
+ agentDir: ctx.agentDir,
143
+ canScheduleAs,
144
+ }),
122
145
  SECURITY_PERMISSIONS.bypassCronPromotion,
123
146
  GUARD_CRON_PROMOTION_SEVERITY,
124
147
  )