typeclaw 0.39.3 → 0.39.5
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 +1 -1
- package/src/agent/attention-escalation.ts +11 -1
- package/src/agent/index.ts +10 -14
- package/src/agent/model-fallback.ts +13 -4
- package/src/agent/provider-error.ts +36 -1
- package/src/agent/subagents.ts +34 -3
- package/src/agent/throttle-circuit.ts +50 -0
- package/src/agent/tools/channel-reply.ts +48 -3
- package/src/agent/tools/ddg.ts +40 -5
- package/src/agent/tools/keyed-semaphore.ts +114 -0
- package/src/agent/tools/search-retry.ts +82 -0
- package/src/agent/turn-runner.ts +162 -0
- package/src/bundled-plugins/explorer/explorer.ts +5 -0
- package/src/bundled-plugins/memory/README.md +14 -14
- package/src/bundled-plugins/memory/append-tool.ts +98 -8
- package/src/bundled-plugins/memory/dreaming.ts +1 -1
- package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
- package/src/bundled-plugins/memory/load-memory.ts +28 -2
- package/src/bundled-plugins/memory/memory-logger.ts +21 -5
- package/src/bundled-plugins/memory/search-tool.ts +50 -7
- package/src/bundled-plugins/memory/stream-events.ts +23 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
- package/src/bundled-plugins/reviewer/reviewer.ts +3 -1
- package/src/bundled-plugins/scout/scout.ts +5 -0
- package/src/bundled-plugins/security/index.ts +24 -1
- package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
- package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
- package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
- package/src/channels/adapters/github/permission-guidance.ts +18 -0
- package/src/channels/adapters/webex-bot.ts +26 -25
- package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
- package/src/channels/adapters/webex.ts +27 -30
- package/src/channels/manager.ts +64 -57
- package/src/channels/router.ts +134 -4
- package/src/channels/types.ts +8 -1
- package/src/cli/builtins.ts +6 -32
- package/src/cli/channel.ts +7 -11
- package/src/cli/command-meta.ts +93 -0
- package/src/cli/help.ts +24 -0
- package/src/cli/index.ts +34 -10
- package/src/cli/init.ts +2 -2
- package/src/cli/plugin-commands-dispatch.ts +7 -1
- package/src/config/config.ts +27 -1
- package/src/container/start.ts +22 -2
- package/src/hostd/daemon.ts +55 -26
- package/src/hostd/spawn.ts +53 -19
- package/src/permissions/permissions.ts +12 -0
- package/src/run/codex-fetch-observer.ts +11 -6
- package/src/secrets/oauth-xai.ts +2 -2
- package/src/server/index.ts +27 -2
- package/src/skills/typeclaw-channel-github/SKILL.md +59 -13
- package/src/skills/typeclaw-channels/SKILL.md +1 -1
- package/src/skills/typeclaw-config/SKILL.md +1 -0
- package/src/skills/typeclaw-cron/SKILL.md +9 -4
- package/src/skills/typeclaw-permissions/SKILL.md +18 -6
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import type { ModelRef } from '@/config/providers'
|
|
2
|
+
|
|
3
|
+
import type { AgentSession } from './index'
|
|
4
|
+
import { detectProviderError, subscribeProviderErrors } from './provider-error'
|
|
5
|
+
import { modelThrottleCircuit, type ThrottleCircuit } from './throttle-circuit'
|
|
6
|
+
|
|
7
|
+
export type PersistentTurnAttempt = {
|
|
8
|
+
ref: ModelRef
|
|
9
|
+
outcome: 'hard' | 'soft' | 'success'
|
|
10
|
+
errorMessage?: string
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export type PersistentTurnResult = {
|
|
14
|
+
success: boolean
|
|
15
|
+
refUsed: ModelRef
|
|
16
|
+
attempts: PersistentTurnAttempt[]
|
|
17
|
+
lastError?: Error
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
type AttemptActivity = {
|
|
21
|
+
producedAssistantOutput: boolean
|
|
22
|
+
startedToolExecution: boolean
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export async function promptPersistentTurnWithFallback(opts: {
|
|
26
|
+
refs: ModelRef[]
|
|
27
|
+
currentModelRef: ModelRef
|
|
28
|
+
session: AgentSession
|
|
29
|
+
text: string
|
|
30
|
+
shouldFailover: (err: Error) => boolean
|
|
31
|
+
setModelForRef: (ref: ModelRef) => Promise<void>
|
|
32
|
+
profile?: string
|
|
33
|
+
circuit?: ThrottleCircuit
|
|
34
|
+
skipProviderErrorSubscription?: boolean
|
|
35
|
+
detectSoftErrorFromLeaf?: boolean
|
|
36
|
+
beforeAttempt?: (ref: ModelRef) => void
|
|
37
|
+
onAttemptFailed?: (attempt: PersistentTurnAttempt) => void
|
|
38
|
+
}): Promise<PersistentTurnResult> {
|
|
39
|
+
if (opts.refs.length === 0) throw new Error('promptPersistentTurnWithFallback: refs[] must be non-empty')
|
|
40
|
+
const attempts: PersistentTurnAttempt[] = []
|
|
41
|
+
let lastError: Error | undefined
|
|
42
|
+
const circuit = opts.circuit ?? modelThrottleCircuit
|
|
43
|
+
// The model the session currently has loaded; only call setModel when the
|
|
44
|
+
// chosen ref differs from it. Tracked locally so successive setModel calls
|
|
45
|
+
// within a single turn stay coherent.
|
|
46
|
+
let loadedRef = opts.currentModelRef
|
|
47
|
+
// Always start from the head of the chain so a recovered primary is probed
|
|
48
|
+
// again (the circuit breaker, not a sticky start index, decides when to skip
|
|
49
|
+
// a still-throttled ref). Starting at the previous turn's fallback would make
|
|
50
|
+
// a one-time failover permanent and never let the cooldown/half-open path
|
|
51
|
+
// re-test the primary.
|
|
52
|
+
for (let i = 0; i < opts.refs.length; i++) {
|
|
53
|
+
const ref = opts.refs[i]!
|
|
54
|
+
const isLast = i === opts.refs.length - 1
|
|
55
|
+
// Skip a ref whose circuit is open, but never skip the last one — there is
|
|
56
|
+
// nowhere left to fall, so we try it regardless and let the result speak.
|
|
57
|
+
if (!isLast && circuit.isOpen({ profile: opts.profile, ref })) continue
|
|
58
|
+
if (ref !== loadedRef) {
|
|
59
|
+
await opts.setModelForRef(ref)
|
|
60
|
+
loadedRef = ref
|
|
61
|
+
}
|
|
62
|
+
opts.beforeAttempt?.(ref)
|
|
63
|
+
const activity: AttemptActivity = { producedAssistantOutput: false, startedToolExecution: false }
|
|
64
|
+
let softError: Error | undefined
|
|
65
|
+
// Activity tracking ALWAYS runs — the idempotency guard must hold even for
|
|
66
|
+
// subagents. `skipProviderErrorSubscription` only suppresses the soft-error
|
|
67
|
+
// listener (subagents capture their final message off the leaf instead, via
|
|
68
|
+
// detectSoftErrorFromLeaf, so a second listener would race that capture).
|
|
69
|
+
const unsubActivity = subscribeAttemptActivity(opts.session, activity)
|
|
70
|
+
const unsubProvider = opts.skipProviderErrorSubscription
|
|
71
|
+
? () => {}
|
|
72
|
+
: subscribeProviderErrorsIfAvailable(opts.session, (err) => {
|
|
73
|
+
if (softError === undefined) softError = new Error(err.message)
|
|
74
|
+
})
|
|
75
|
+
try {
|
|
76
|
+
try {
|
|
77
|
+
await opts.session.prompt(opts.text)
|
|
78
|
+
} catch (err) {
|
|
79
|
+
const error = err instanceof Error ? err : new Error(String(err))
|
|
80
|
+
const attempt: PersistentTurnAttempt = { ref, outcome: 'hard', errorMessage: error.message }
|
|
81
|
+
attempts.push(attempt)
|
|
82
|
+
lastError = error
|
|
83
|
+
if (opts.shouldFailover(error)) circuit.recordThrottle({ profile: opts.profile, ref })
|
|
84
|
+
if (isLast || !canAdvance(error, activity, opts.shouldFailover)) throw error
|
|
85
|
+
opts.onAttemptFailed?.(attempt)
|
|
86
|
+
continue
|
|
87
|
+
}
|
|
88
|
+
if (softError !== undefined) {
|
|
89
|
+
const attempt: PersistentTurnAttempt = { ref, outcome: 'soft', errorMessage: softError.message }
|
|
90
|
+
attempts.push(attempt)
|
|
91
|
+
lastError = softError
|
|
92
|
+
if (opts.shouldFailover(softError)) circuit.recordThrottle({ profile: opts.profile, ref })
|
|
93
|
+
if (isLast || !canAdvance(softError, activity, opts.shouldFailover)) {
|
|
94
|
+
return { success: false, refUsed: ref, attempts, lastError }
|
|
95
|
+
}
|
|
96
|
+
opts.onAttemptFailed?.(attempt)
|
|
97
|
+
continue
|
|
98
|
+
}
|
|
99
|
+
const leafSoftError = opts.detectSoftErrorFromLeaf ? detectLeafSoftError(opts.session) : undefined
|
|
100
|
+
if (leafSoftError !== undefined) {
|
|
101
|
+
const attempt: PersistentTurnAttempt = { ref, outcome: 'soft', errorMessage: leafSoftError.message }
|
|
102
|
+
attempts.push(attempt)
|
|
103
|
+
lastError = leafSoftError
|
|
104
|
+
if (opts.shouldFailover(leafSoftError)) circuit.recordThrottle({ profile: opts.profile, ref })
|
|
105
|
+
if (isLast || !canAdvance(leafSoftError, activity, opts.shouldFailover)) {
|
|
106
|
+
return { success: false, refUsed: ref, attempts, lastError }
|
|
107
|
+
}
|
|
108
|
+
opts.onAttemptFailed?.(attempt)
|
|
109
|
+
continue
|
|
110
|
+
}
|
|
111
|
+
attempts.push({ ref, outcome: 'success' })
|
|
112
|
+
circuit.recordSuccess({ profile: opts.profile, ref })
|
|
113
|
+
return { success: true, refUsed: ref, attempts }
|
|
114
|
+
} finally {
|
|
115
|
+
unsubProvider()
|
|
116
|
+
unsubActivity()
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
return { success: false, refUsed: opts.refs[opts.refs.length - 1]!, attempts, lastError }
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function canAdvance(error: Error, activity: AttemptActivity, shouldFailover: (err: Error) => boolean): boolean {
|
|
123
|
+
return shouldFailover(error) && !activity.producedAssistantOutput && !activity.startedToolExecution
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function subscribeAttemptActivity(session: AgentSession, activity: AttemptActivity): () => void {
|
|
127
|
+
const subscribe = (session as { subscribe?: unknown }).subscribe
|
|
128
|
+
if (typeof subscribe !== 'function') return () => {}
|
|
129
|
+
return session.subscribe((event: unknown) => {
|
|
130
|
+
if (!isRecord(event)) return
|
|
131
|
+
if (event.type === 'tool_execution_start' || event.type === 'tool_execution_end') {
|
|
132
|
+
activity.startedToolExecution = true
|
|
133
|
+
return
|
|
134
|
+
}
|
|
135
|
+
if (event.type !== 'message_update') return
|
|
136
|
+
const assistantMessageEvent = event.assistantMessageEvent
|
|
137
|
+
if (!isRecord(assistantMessageEvent)) return
|
|
138
|
+
if (assistantMessageEvent.type === 'text_delta' && typeof assistantMessageEvent.delta === 'string') {
|
|
139
|
+
if (assistantMessageEvent.delta.length > 0) activity.producedAssistantOutput = true
|
|
140
|
+
}
|
|
141
|
+
})
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function subscribeProviderErrorsIfAvailable(
|
|
145
|
+
session: AgentSession,
|
|
146
|
+
onError: Parameters<typeof subscribeProviderErrors>[1],
|
|
147
|
+
): () => void {
|
|
148
|
+
const subscribe = (session as { subscribe?: unknown }).subscribe
|
|
149
|
+
if (typeof subscribe !== 'function') return () => {}
|
|
150
|
+
return subscribeProviderErrors(session, onError)
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function detectLeafSoftError(session: AgentSession): Error | undefined {
|
|
154
|
+
const leaf = session.sessionManager?.getLeafEntry()
|
|
155
|
+
if (!leaf || leaf.type !== 'message') return undefined
|
|
156
|
+
const detected = detectProviderError(leaf.message)
|
|
157
|
+
return detected === null ? undefined : new Error(detected.message)
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
161
|
+
return typeof value === 'object' && value !== null
|
|
162
|
+
}
|
|
@@ -77,6 +77,10 @@ End every response with this exact structure:
|
|
|
77
77
|
- If the question requires EXTERNAL/web information (docs, library reference, web search, fetching a URL), say so explicitly and tell the caller to spawn \`scout\` instead. Do not try to answer external questions from memory.
|
|
78
78
|
- If you cannot find what was asked, say so explicitly with what you DID find and what surfaces you searched.`
|
|
79
79
|
|
|
80
|
+
// `profile` is dropped, not passed through: explorer is a fast-tier specialist, so
|
|
81
|
+
// a parent must not bump it off `fast` via a per-spawn `profile` override (which the
|
|
82
|
+
// `spawn_subagent` tool injects into the payload and `profileFromPayload` would
|
|
83
|
+
// otherwise honor). Other fields still pass through untouched.
|
|
80
84
|
export const explorerPayloadSchema = z
|
|
81
85
|
.object({
|
|
82
86
|
requestId: z.string().optional(),
|
|
@@ -84,6 +88,7 @@ export const explorerPayloadSchema = z
|
|
|
84
88
|
description: z.string().optional(),
|
|
85
89
|
})
|
|
86
90
|
.passthrough()
|
|
91
|
+
.transform(({ profile: _profile, ...rest }) => rest)
|
|
87
92
|
|
|
88
93
|
export type ExplorerPayload = z.infer<typeof explorerPayloadSchema>
|
|
89
94
|
|
|
@@ -32,17 +32,17 @@ All fields are **restart-required** — the plugin reads them once at boot. The
|
|
|
32
32
|
|
|
33
33
|
## What it contributes
|
|
34
34
|
|
|
35
|
-
| Kind | Name | Notes
|
|
36
|
-
| -------- | -------------------------- |
|
|
37
|
-
| Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`.
|
|
38
|
-
| Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run.
|
|
39
|
-
| Subagent | `memory-retrieval` | On `session.turn.start` when injection plan is `index` mode, reads the user's actual prompt for this turn + shard listing, writes a focused summary to `memory/.retrieval-cache/<sessionId>.md`. Coalesced per `parentSessionId`. Declares `profile: 'fast'` (retrieval is "≤3 keyword searches + 1 write", no reasoning required) and `timeoutMs: 30_000` so a wedged provider call releases the coalescing key instead of poisoning the cache for every subsequent turn.
|
|
40
|
-
| Tool | `memory_search` | Main-agent tool. Pass `query` to search, or `topic` to look up one shard by exact slug (not both). Search is substring/regex across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Plain queries are phrase-first: the whole query is tried as one substring, and if that finds nothing the query is split on whitespace and the distinct words are OR-matched, ranked by how many words each hit contains (regex queries never fall back). Results are discriminated by `source: "topic" \| "stream"`; exact-phrase (and regex) results list topics first, then streams newest-first, while word-fallback results are ranked by matched-word count with that order as the tiebreak (so a higher-scoring stream can precede a lower-scoring topic). The `topic` mode reads `memory/topics/<slug>.md` directly via `loadShard` and returns that one shard with its full body — no fuzzy search — so a channel agent can open a topic whose slug the per-turn injection already showed it, instead of re-searching for a body the retrieval layer already located. When no topic shard matches the slug it falls back to a reference of the same slug (`memory/references/<slug>.md`), because the per-turn injection renders topic and reference entries with the same `slug:` line and the same `memory_search({ topic: "<slug>" })` recovery hint — so a reference slug surfaced in channel memory must resolve here, not dead-end. Bad slugs (path traversal) come back as a structured error; a slug matching neither a topic nor a reference is an empty match set. |
|
|
41
|
-
| Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded.
|
|
42
|
-
| Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.
|
|
43
|
-
| Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip.
|
|
44
|
-
| Hook | `session.end` | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session.
|
|
45
|
-
| Hook | `session.turn.start` | **Vector on:** renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). **Vector off:** when `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question. Fire-and-forget; failures route through the plugin logger.
|
|
35
|
+
| Kind | Name | Notes |
|
|
36
|
+
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`. |
|
|
38
|
+
| Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run. |
|
|
39
|
+
| Subagent | `memory-retrieval` | On `session.turn.start` when injection plan is `index` mode, reads the user's actual prompt for this turn + shard listing, writes a focused summary to `memory/.retrieval-cache/<sessionId>.md`. Coalesced per `parentSessionId`. Declares `profile: 'fast'` (retrieval is "≤3 keyword searches + 1 write", no reasoning required) and `timeoutMs: 30_000` so a wedged provider call releases the coalescing key instead of poisoning the cache for every subsequent turn. |
|
|
40
|
+
| Tool | `memory_search` | Main-agent tool. Pass `query` to search, or `topic` to look up one shard by exact slug (not both). Search is substring/regex across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Plain queries are phrase-first: the whole query is tried as one substring, and if that finds nothing the query is split on whitespace and the distinct words are OR-matched, ranked by how many words each hit contains (regex queries never fall back). Results are discriminated by `source: "topic" \| "stream"`; exact-phrase (and regex) results list topics first, then streams newest-first, while word-fallback results are ranked by matched-word count with that order as the tiebreak (so a higher-scoring stream can precede a lower-scoring topic). The `topic` mode reads `memory/topics/<slug>.md` directly via `loadShard` and returns that one shard with its full body — no fuzzy search — so a channel agent can open a topic whose slug the per-turn injection already showed it, instead of re-searching for a body the retrieval layer already located. When no topic shard matches the slug it falls back to a reference of the same slug (`memory/references/<slug>.md`), because the per-turn injection renders topic and reference entries with the same `slug:` line and the same `memory_search({ topic: "<slug>" })` recovery hint — so a reference slug surfaced in channel memory must resolve here, not dead-end. Bad slugs (path traversal) come back as a structured error; a slug matching neither a topic nor a reference is an empty match set. The optional `where` param scopes a query to one room (`"#incidents"` or its raw chat id): it keeps only stream fragments whose captured `where` matches the room by raw `chat` id or `chatName` (case-insensitive, leading `#` optional) and — because room is fragment-only provenance — returns ONLY stream matches, excluding topic shards and references. |
|
|
41
|
+
| Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded. |
|
|
42
|
+
| Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`. |
|
|
43
|
+
| Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip. |
|
|
44
|
+
| Hook | `session.end` | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session. |
|
|
45
|
+
| Hook | `session.turn.start` | **Vector on:** renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). **Vector off:** when `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question. Fire-and-forget; failures route through the plugin logger. |
|
|
46
46
|
|
|
47
47
|
## Memory injection (two-tier, topic shards only)
|
|
48
48
|
|
|
@@ -132,10 +132,10 @@ A `[dreaming] citation-superset violation: …` warning logs the dropped ids and
|
|
|
132
132
|
## Files on disk
|
|
133
133
|
|
|
134
134
|
- **`memory/topics/<slug>.md`** — per-topic shards with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, `tags?`) + body markdown. Runtime owns the frontmatter (recomputed after every dreaming run from the body's citations); dreaming subagent writes body only. The body is a **compact belief record**: one belief sentence stating the current truth (subject + predicate + essential scope qualifier; the strength wording — "mentioned" / "consistently" / "always" — is calibrated from `days`), followed by the `fragments:` list (active evidence behind the belief) and an optional `superseded:` list (evidence overturned by a later contradiction — kept cited for GC/history but excluded from vector retrieval). One sentence (not a paragraph) keeps bodies small so more topics stay under the direct-injection budget; the citation lists are the only load-bearing part of the body, so the prose shape is free to be terse. Existing verbose shards are rewritten into this form by the next dreaming run (no migration).
|
|
135
|
-
- **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards.
|
|
135
|
+
- **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards. A `fragment` event carries optional **situational provenance** for "who said what, where, and when": `who` (display name/handle of the attributed speaker, LLM-supplied per-fragment by `memory-logger` only when one transcript speaker clearly owns the evidence), `where` (`{ adapter, workspace, workspaceName?, chat, chatName?, thread }` — runtime-stamped from the session origin in the append tool, channel origins only), and `when` (reuses the existing `ts`). Both are optional, so legacy fragments and non-channel (TUI) origins parse with them absent. `who`/`where` are deliberately NOT in `fragmentContentHash` (dedup stays content-identity) and NOT in `fragmentEmbeddableText` (provenance is retrieval metadata, not embedded — it must not burn the 512-token budget or let same-room/same-person dominate recall). **Secret-scanning covers provenance too**: `who` (LLM-supplied) clears the same `detectSecrets` guard as `topic`/`body` and a credential-shaped value is refused with the retryable error; the origin-derived `where` names (`workspaceName`/`chatName`) are external channel data the agent can't rewrite, so a credential-shaped name is silently dropped (raw id kept) rather than wedging the logger. Raw ids are platform-issued identifiers, not free text, so they are not scanned. `where` is runtime-stamped rather than LLM-supplied because the channel is stable for a whole logger run; `who` is per-fragment because a single run spans many speakers and `origin.lastInboundAuthorId` is only the spawn-time one — auto-stamping it would misattribute fragments about earlier speakers. Surfaced to the agent (not embedded) via `memory_search` (`StreamMatch.who/when/where`), `hybridSearch` (`HybridSearchResult.who/when/where` on self-resolved undreamed fragments), and the per-turn retrieval render (`renderProvenanceLine` → `_Jisoo in #incidents on 2026-06-24_`).
|
|
136
136
|
- **`memory/MEMORY.md.pre-shard.bak`** — legacy pre-shard backup left by older TypeClaw versions. Safe to delete after verifying.
|
|
137
137
|
- **`memory/skills/<name>/SKILL.md`** — muscle memory (Form A). Skills the dreaming subagent distills from repeated procedures. Auto-loaded as first-class skills. CLI/plugin suggestions (Forms B and C) are recorded as topic shards instead — see [Muscle memory](#muscle-memory-three-forms).
|
|
138
|
-
- **`memory/references/<slug>.md`** — verbatim reference artifacts (
|
|
138
|
+
- **`memory/references/<slug>.md`** — verbatim reference artifacts. Written by `store_reference`, a `memory-logger` custom tool that is always registered (there is no `references.enabled` config gate — references are unconditionally available; they simply stay empty until the `memory-logger` chooses to store one). A fragment may cite a stored reference via `append`'s `references: ['<slug>']`, but the append tool validates each slug against the references that actually exist on disk and silently drops the rest (`resolveValidReferences`), so a hallucinated slug never lands a dangling citation in the stream. When vector is enabled, a freshly stored reference is embedded into the vector index immediately via the `store_reference` on-write hook (`vector/reference-index-on-write.ts`), mirroring the stream-fragment on-write hook — so it is vector-retrievable within the same container uptime instead of only after the next startup index build. Chunks are derived by the same `referencePassagesForOne` the startup build uses, and re-storing a shorter body prunes the stale higher-index chunk rows.
|
|
139
139
|
- **`memory/.dreaming-state.json`** — per-day dreamed-id sets.
|
|
140
140
|
- **`memory/.retrieval-cache/<sessionId>.md`** — ephemeral retrieval summaries. Written by `memory-retrieval`, read by `loadMemory` on the next prompt of the same session, unlinked on `session.end`.
|
|
141
141
|
|
|
@@ -145,7 +145,7 @@ The plugin emits structured `[plugin:memory]` log lines (no separate metrics inf
|
|
|
145
145
|
|
|
146
146
|
- **`[memory-logger] <session> done fragments_written=N elapsed_ms=…`** — how many fragments a logger run captured (delta of fragment events in today's stream).
|
|
147
147
|
- **`[dreaming] done topics_created=N topics_removed=N superseded_new=N fragments_dropped=N over_budget=N elapsed_ms=…`** — consolidation activity per run: new/removed topic shards (by snapshot path diff), net citations moved into `superseded:`, fragments GC'd, and `over_budget` (the count of topic shards whose embeddable text exceeds the model token budget — see [Embedding token budget](#embedding-token-budget)). `topics_created` + reinforcement is the "is memory getting sharper" signal; `superseded_new` is contradiction-edit volume; a persistently non-zero `over_budget` means the subagent isn't compacting the flagged shards. Derived by `computeDreamingMetrics` from the pre/post shard snapshots.
|
|
148
|
-
- **`[vector-retrieval] mode=index topic_results=N stream_results=N reference_results=N elapsed_ms=… [suppressed=1]`** (or `mode=direct topics=N`) — per-turn retrieval breakdown. `stream_results` counts undreamed-fragment hits that self-resolved (no citing topic yet) — the freshness-window usage signal that informs whether the undreamed surface earns its keep. `reference_results` counts verbatim-reference hits (
|
|
148
|
+
- **`[vector-retrieval] mode=index topic_results=N stream_results=N reference_results=N elapsed_ms=… [suppressed=1]`** (or `mode=direct topics=N`) — per-turn retrieval breakdown. `stream_results` counts undreamed-fragment hits that self-resolved (no citing topic yet) — the freshness-window usage signal that informs whether the undreamed surface earns its keep. `reference_results` counts verbatim-reference hits (non-zero once the `memory-logger` has stored at least one reference and vector is enabled), broken out from `stream_results` so the two surfaces are distinguishable. `elapsed_ms` times the full `hybridSearch` (embed + cosine scan + keyword lane + RRF fusion) — the on-critical-path retrieval cost. `suppressed=1` appears when the query matched nothing after the relevance gate, so an empty memory block is distinguishable from a missing one.
|
|
149
149
|
|
|
150
150
|
These are intentionally verbose for now so behavior is observable in logs; trim once the useful subset is known.
|
|
151
151
|
|
|
@@ -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,64 @@ 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
|
-
|
|
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
|
+
// Returns the set of reference slugs the agent is allowed to cite from
|
|
25
|
+
// `references[]`: every reference that exists on disk (a `store_reference` call
|
|
26
|
+
// writes the file synchronously before returning the slug, so a same-run store
|
|
27
|
+
// is already on disk by append time). Lets the append tool strip hallucinated
|
|
28
|
+
// slugs the model invents without ever calling `store_reference`.
|
|
29
|
+
export type ReferenceSlugResolver = (agentDir: string) => Promise<Iterable<string>>
|
|
30
|
+
|
|
31
|
+
export type CreateAppendToolOptions = {
|
|
32
|
+
onFragmentsAppended?: FragmentsAppendedHook
|
|
33
|
+
originProvider?: OriginProvider
|
|
34
|
+
referenceSlugResolver?: ReferenceSlugResolver
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// Stamped fields are the stable channel coordinates only. Author identity is
|
|
38
|
+
// deliberately excluded: a channel session sees many speakers and the origin's
|
|
39
|
+
// `lastInboundAuthorId` is just the spawn-time one, so attributing it to every
|
|
40
|
+
// fragment would misattribute fragments about earlier speakers. `who` is the
|
|
41
|
+
// LLM's job, per fragment, from the transcript speaker line.
|
|
42
|
+
export function provenanceFromOrigin(origin: SessionOrigin | undefined): FragmentProvenance | undefined {
|
|
43
|
+
if (origin === undefined || origin.kind !== 'channel') return undefined
|
|
44
|
+
const where: FragmentProvenance = {
|
|
45
|
+
adapter: origin.adapter,
|
|
46
|
+
workspace: origin.workspace,
|
|
47
|
+
chat: origin.chat,
|
|
48
|
+
thread: origin.thread,
|
|
49
|
+
}
|
|
50
|
+
// workspaceName/chatName are external channel data force-committed to memory.
|
|
51
|
+
// The agent cannot rewrite them (they come from the origin, not a tool arg),
|
|
52
|
+
// so a credential-shaped name is dropped rather than thrown — keep the raw id,
|
|
53
|
+
// never let the leaky display string reach git. Raw ids are platform-issued
|
|
54
|
+
// identifiers, not free text, so they are not scanned.
|
|
55
|
+
const workspaceName = redactIfSecret(origin.workspaceName)
|
|
56
|
+
const chatName = redactIfSecret(origin.chatName)
|
|
57
|
+
if (workspaceName !== undefined) where.workspaceName = workspaceName
|
|
58
|
+
if (chatName !== undefined) where.chatName = chatName
|
|
59
|
+
return where
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function redactIfSecret(name: string | undefined): string | undefined {
|
|
63
|
+
if (name === undefined) return undefined
|
|
64
|
+
return detectSecrets(name).length === 0 ? name : undefined
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export function createAppendTool(options: CreateAppendToolOptions = {}) {
|
|
68
|
+
const { onFragmentsAppended, originProvider, referenceSlugResolver } = options
|
|
19
69
|
return defineTool({
|
|
20
70
|
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.",
|
|
71
|
+
"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.",
|
|
22
72
|
parameters: z.object({
|
|
23
73
|
topic: z.string().min(1),
|
|
24
74
|
body: z.string().min(1),
|
|
@@ -26,10 +76,17 @@ export function createAppendTool(onFragmentsAppended?: FragmentsAppendedHook) {
|
|
|
26
76
|
entry: z.string().min(1),
|
|
27
77
|
latestEntryId: z.string().min(1),
|
|
28
78
|
references: z.array(z.string()).optional(),
|
|
79
|
+
who: z.string().min(1).optional(),
|
|
29
80
|
}),
|
|
30
|
-
async execute({ topic, body, source, entry, latestEntryId, references }, ctx) {
|
|
81
|
+
async execute({ topic, body, source, entry, latestEntryId, references, who }, ctx) {
|
|
31
82
|
const streamPath = dailyStreamPath(ctx.agentDir)
|
|
32
|
-
|
|
83
|
+
const where = provenanceFromOrigin(originProvider?.())
|
|
84
|
+
// `who` is LLM-supplied and force-committed to memory, so it clears the
|
|
85
|
+
// same secret guard as topic/body — a token-shaped display name is refused
|
|
86
|
+
// with the same retryable error. (`where` names are origin-derived and the
|
|
87
|
+
// agent can't rewrite them, so they are self-redacted in provenanceFromOrigin
|
|
88
|
+
// instead of throwing here.)
|
|
89
|
+
assertNoSecrets([topic, body, who])
|
|
33
90
|
|
|
34
91
|
const hash = fragmentContentHash({ topic, body })
|
|
35
92
|
const events = await readEvents(streamPath)
|
|
@@ -55,9 +112,12 @@ export function createAppendTool(onFragmentsAppended?: FragmentsAppendedHook) {
|
|
|
55
112
|
topic,
|
|
56
113
|
body,
|
|
57
114
|
}
|
|
58
|
-
|
|
59
|
-
|
|
115
|
+
const validReferences = await resolveValidReferences(references, referenceSlugResolver, ctx)
|
|
116
|
+
if (validReferences.length > 0) {
|
|
117
|
+
fragment.references = validReferences
|
|
60
118
|
}
|
|
119
|
+
if (who !== undefined) fragment.who = who
|
|
120
|
+
if (where !== undefined) fragment.where = where
|
|
61
121
|
const watermark: WatermarkEvent = {
|
|
62
122
|
type: 'watermark',
|
|
63
123
|
id: watermarkId,
|
|
@@ -122,7 +182,37 @@ function dailyStreamPath(agentDir: string): string {
|
|
|
122
182
|
return streamFilePath(agentDir, formatLocalDate())
|
|
123
183
|
}
|
|
124
184
|
|
|
125
|
-
|
|
185
|
+
// The model treats `references[]` as a free-text related-id field, citing empty
|
|
186
|
+
// strings, stream paths, and slugs for references it never stored. Every path
|
|
187
|
+
// first normalizes: trim, drop blank/whitespace-only entries, and de-duplicate
|
|
188
|
+
// — an empty or repeated citation is never meaningful regardless of wiring.
|
|
189
|
+
// With a resolver, only slugs backed by a real reference file then survive; the
|
|
190
|
+
// rest are dropped and logged so dangling citations never reach the stream.
|
|
191
|
+
// Without one (the standalone `appendTool` export, no reference subsystem
|
|
192
|
+
// wired) the normalized slugs pass through.
|
|
193
|
+
async function resolveValidReferences(
|
|
194
|
+
references: string[] | undefined,
|
|
195
|
+
resolver: ReferenceSlugResolver | undefined,
|
|
196
|
+
ctx: { agentDir: string; logger?: { warn(message: string): void } },
|
|
197
|
+
): Promise<string[]> {
|
|
198
|
+
if (references === undefined || references.length === 0) return []
|
|
199
|
+
const requested = [...new Set(references.map((slug) => slug.trim()).filter((slug) => slug.length > 0))]
|
|
200
|
+
if (resolver === undefined) return requested
|
|
201
|
+
|
|
202
|
+
const known = new Set(await resolver(ctx.agentDir))
|
|
203
|
+
const valid = requested.filter((slug) => known.has(slug))
|
|
204
|
+
const dropped = requested.filter((slug) => !known.has(slug))
|
|
205
|
+
if (dropped.length > 0) {
|
|
206
|
+
ctx.logger?.warn(
|
|
207
|
+
`[memory] dropped ${dropped.length} unknown reference slug(s) from fragment: ${dropped.join(', ')}. ` +
|
|
208
|
+
`references[] may only cite slugs returned by store_reference.`,
|
|
209
|
+
)
|
|
210
|
+
}
|
|
211
|
+
return valid
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function assertNoSecrets(parts: ReadonlyArray<string | undefined>): void {
|
|
215
|
+
const content = parts.filter((part): part is string => part !== undefined).join('\n')
|
|
126
216
|
const secrets = detectSecrets(content)
|
|
127
217
|
if (secrets.length === 0) return
|
|
128
218
|
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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()
|