@arcforge/kernel 2.0.143 → 2.0.145

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": "@arcforge/kernel",
3
- "version": "2.0.143",
3
+ "version": "2.0.145",
4
4
  "description": "The Axon kernel — ring 0. Owns resources and execution, enforces policy, and is the only constructor of the unprivileged capsule.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -15,13 +15,13 @@
15
15
  "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
16
16
  },
17
17
  "dependencies": {
18
- "@arcforge/air": "2.0.143",
19
- "@arcforge/engines": "2.0.143",
20
- "@arcforge/err": "2.0.143",
21
- "@arcforge/session": "2.0.143",
22
- "@arcforge/types": "2.0.143",
23
- "@arclabs/cloud": "2.0.143",
24
- "@axon/capsule": "2.0.143"
18
+ "@arcforge/air": "2.0.145",
19
+ "@arcforge/engines": "2.0.145",
20
+ "@arcforge/err": "2.0.145",
21
+ "@arcforge/session": "2.0.145",
22
+ "@arcforge/types": "2.0.145",
23
+ "@arclabs/cloud": "2.0.145",
24
+ "@axon/capsule": "2.0.145"
25
25
  },
26
26
  "devDependencies": {
27
27
  "@types/bun": "latest",
package/src/capsule.ts CHANGED
@@ -2,9 +2,9 @@ import { isAbsolute, resolve } from "node:path"
2
2
  import { Capsule, CapsuleT } from "@axon/capsule"
3
3
  import type { CapsulePartialConfig, CapsuleTool } from "@axon/capsule"
4
4
  import { err } from "@arcforge/err"
5
- import { CAPSULE_TRANSIENT_EVENTS } from "@arcforge/types"
6
- import type { AxonBlueprint, AxonEventMap, CapsulePolicy } from "@arcforge/types"
7
- import type { AxonHost } from "@arcforge/types"
5
+ import { CAPSULE_TRANSIENT_EVENTS, resolveIsolation } from "@arcforge/types"
6
+ import type { AxonBlueprint, AxonEventMap, CapsulePolicy, PolicyRule } from "@arcforge/types"
7
+ import type { AxonEscalate, AxonHost } from "@arcforge/types"
8
8
  import type { KernelBus } from "./contracts"
9
9
  import type { AxonSessionT } from "@arcforge/session"
10
10
  import { isLoadable, toScopeModule } from "./scope"
@@ -56,13 +56,25 @@ function defaultPolicy(blueprint: AxonBlueprint): CapsulePartialConfig["policy"]
56
56
  const tools: Record<string, true> = {}
57
57
  for (const tool of blueprint.tools.filter(isLoadable)) tools[tool.name] = true
58
58
 
59
- const userPolicy = blueprint.config.policy ?? {}
59
+ // The two layers, intersected into what the capsule enforces.
60
+ //
61
+ // The profile is a CEILING: an agent narrows within it and can never widen
62
+ // it. Resolved HERE rather than in the TUI, because this is the one seam
63
+ // every consumer passes through — `axon dev`, `axon run` in a script, a
64
+ // test harness. A ceiling applied only on the TUI's spawn path would be
65
+ // advisory, and the CLI is exactly where someone scripting would bypass it
66
+ // without meaning to.
67
+ const userPolicy = intersect(blueprint.profilePolicy, blueprint.config.policy ?? {})
60
68
 
61
69
  // The invariant: not setting a security policy means "I don't care" — the
62
70
  // agent gets full access to the machine, no hassle, no dependencies. Setting
63
71
  // ANY containment intent (fs/network/limits) opts into rootless confinement,
64
72
  // which needs no privilege and just works. A user can always name isolation
65
73
  // explicitly to force a tier (e.g. "hardened", or "none" despite having fs).
74
+ //
75
+ // Read off the INTERSECTED policy, so a profile declaring containment opts
76
+ // every agent on the machine into it — an agent that declares nothing still
77
+ // gets the wall its profile asked for.
66
78
  const wantsContainment =
67
79
  userPolicy.fs !== undefined || userPolicy.network !== undefined || userPolicy.limits !== undefined
68
80
  const isolation = userPolicy.isolation ?? (wantsContainment ? "auto" : "none")
@@ -81,6 +93,93 @@ function defaultPolicy(blueprint: AxonBlueprint): CapsulePartialConfig["policy"]
81
93
  }
82
94
  }
83
95
 
96
+ /**
97
+ * Intersect the profile ceiling with an agent's own policy.
98
+ *
99
+ * ── Why this is a UNION of keys, not of permissions ─────────────────────────
100
+ *
101
+ * Both layers' rules are carried forward per capability, and the MEDIATOR
102
+ * evaluates the pair at call time (see resolveVerdict in @arcforge/types).
103
+ * That split is deliberate: merging two glob rules into one is where a ceiling
104
+ * silently springs a leak — `allow: ["git status"]` unioned with
105
+ * `allow: ["git push"]` permits a command neither layer permitted alone.
106
+ *
107
+ * So this composes the SHAPE (which capabilities each layer has an opinion
108
+ * about) and leaves the VERDICT to per-call evaluation, where both rules are
109
+ * still separately available and the answer can name which one decided.
110
+ *
111
+ * ── The bare cases collapse here ────────────────────────────────────────────
112
+ *
113
+ * `true`/`false`/`"escalate"` carry no patterns, so there is nothing to defer:
114
+ * a profile `false` is final regardless of what the agent says, and a profile
115
+ * `true` adds no constraint the agent could violate. Collapsing them at this
116
+ * seam keeps the common case (a profile that just says "no shell") from
117
+ * costing a pair lookup on every call.
118
+ *
119
+ * fs and limits are NOT intersected: they are OS-layer facts (bind mounts,
120
+ * cgroups) with no verdict to evaluate, and the mediator never sees them. The
121
+ * profile's are taken when present, since a ceiling that a bind mount ignores
122
+ * is not a ceiling.
123
+ */
124
+ function intersect(
125
+ profile: CapsulePartialConfig["policy"] | undefined,
126
+ agent: NonNullable<CapsulePartialConfig["policy"]>,
127
+ ): NonNullable<CapsulePartialConfig["policy"]> {
128
+ if (!profile) return agent
129
+
130
+ return {
131
+ ...agent,
132
+ isolation: resolveIsolation(profile.isolation, agent.isolation) ?? agent.isolation,
133
+
134
+ // The OS wall. A profile grant is the outer bound, so an agent's paths
135
+ // are kept only where the profile has no opinion at all — otherwise a
136
+ // narrower mount would have to be computed, which bind mounts cannot
137
+ // express as an intersection of globs.
138
+ ...(profile.fs ? { fs: profile.fs } : {}),
139
+ ...(profile.limits ? { limits: profile.limits } : {}),
140
+
141
+ ...(profile.network || agent.network
142
+ ? { network: pairRules(profile.network, agent.network) }
143
+ : {}),
144
+ ...(profile.tools || agent.tools
145
+ ? { tools: pairRules(profile.tools, agent.tools) }
146
+ : {}),
147
+
148
+ process: {
149
+ spawn: pairRule(profile.process?.spawn, agent.process?.spawn),
150
+ run: pairRule(profile.process?.run, agent.process?.run),
151
+ },
152
+ }
153
+ }
154
+
155
+ /**
156
+ * One capability's rule under both layers.
157
+ *
158
+ * A bare profile verdict wins outright — it cannot be narrowed further by a
159
+ * pattern and cannot be widened at all. Otherwise the agent's rule stands and
160
+ * the profile's is carried alongside for the mediator to evaluate against.
161
+ */
162
+ function pairRule(profile: PolicyRule | undefined, agent: PolicyRule | undefined): PolicyRule {
163
+ if (profile === false) return false
164
+ if (profile === "escalate" && agent !== false) return "escalate"
165
+ if (profile === undefined) return agent ?? true
166
+ if (profile === true) return agent ?? true
167
+ // Profile is glob-shaped: the agent narrows within it, and the pair is
168
+ // evaluated per call. With no agent rule, the profile IS the rule.
169
+ return agent ?? profile
170
+ }
171
+
172
+ /** pairRule across two keyed maps, over the union of their keys. */
173
+ function pairRules(
174
+ profile: Record<string, PolicyRule> | undefined,
175
+ agent: Record<string, PolicyRule> | undefined,
176
+ ): Record<string, PolicyRule> {
177
+ const keys = new Set([...Object.keys(profile ?? {}), ...Object.keys(agent ?? {})])
178
+ const out: Record<string, PolicyRule> = {}
179
+ for (const key of keys) out[key] = pairRule(profile?.[key], agent?.[key])
180
+ return out
181
+ }
182
+
84
183
  /** Resolve an fs policy's relative paths against the agent project root. */
85
184
  function resolveFsPaths(fs: NonNullable<CapsulePolicy["fs"]>, root: string): CapsulePolicy["fs"] {
86
185
  const abs = (p: string) => (isAbsolute(p) ? p : resolve(root, p))
@@ -100,6 +199,13 @@ type AxonCapsuleOpts = {
100
199
  run?: () => { runId: string } | null
101
200
  boot: boolean
102
201
  host?: AxonHost
202
+ /**
203
+ * The platform's policy decider. Handed to the capsule as its `escalate`
204
+ * callback — the one wire that makes a rule saying "escalate" mean
205
+ * anything. Without it the capsule denies after its own timeout, which is
206
+ * how every escalation behaved before this was connected.
207
+ */
208
+ escalate?: AxonEscalate
103
209
  }
104
210
 
105
211
  /**
@@ -136,6 +242,7 @@ export async function AxonCapsule(opts: AxonCapsuleOpts) {
136
242
  env: blueprint.env,
137
243
  tools: toCapsuleTools(blueprint),
138
244
  policy: defaultPolicy(blueprint),
245
+ ...(opts.escalate ? { escalate: opts.escalate } : {}),
139
246
  ...(opts.host ? {
140
247
  host: {
141
248
  call: request => opts.host!.call({
package/src/contracts.ts CHANGED
@@ -26,6 +26,14 @@ export type KernelBus = {
26
26
  export type KernelCognet = {
27
27
  readonly name: string
28
28
  readonly mode: CognetSchedule
29
+ /**
30
+ * Which entry types wake this brain. Absent = everything.
31
+ *
32
+ * Read by the scheduler's stimulus trigger. A conversational cognet
33
+ * declares nothing and hears all of it; one attached to a firehose
34
+ * sensor names the few kinds worth a thought.
35
+ */
36
+ readonly wakeOn?: readonly string[]
29
37
  load(abi: KernelAbi): Promise<void>
30
38
  wake(wake: CognetWake): Promise<void>
31
39
  update(blueprint: AxonBlueprint): Promise<void> | void
package/src/engine.ts CHANGED
@@ -18,8 +18,15 @@ type EngineOpts = {
18
18
  session: AxonSessionT
19
19
  /** The runtime's cloud client — handed to drivers at create(); engines call what they need. */
20
20
  cloud: EngineCloud
21
- /** Commit a format violation the model must read and correct. */
22
- fault(input: { code: string; message: string; excerpt?: string }): Promise<void>
21
+ /**
22
+ * Commit a format violation the model must read and correct.
23
+ *
24
+ * `rejected` is the reply that earned it, verbatim. Without it the next
25
+ * attempt reads a correction whose subject is missing — the malformed text
26
+ * never entered the log, so the model was asked to fix a shape it could
27
+ * not see. Absent only where no reply exists to quote.
28
+ */
29
+ fault(input: { code: string; message: string; excerpt?: string; rejected?: string; attempt?: number }): Promise<void>
23
30
  }
24
31
 
25
32
  type EngineContext = {
@@ -38,43 +45,320 @@ const RETRY_DELAYS_MS = [100, 300] as const
38
45
  */
39
46
  const DEFAULT_OUTPUT_RETRIES = 2
40
47
 
48
+ /**
49
+ * How long the engine wire may go silent before the call is abandoned.
50
+ *
51
+ * Measured BETWEEN events, not across the call: a model thinking hard for two
52
+ * minutes is working, and a wall-clock cap would kill it. A stream that has
53
+ * produced nothing for this long has stalled — the connection is open, the
54
+ * provider is not sending, and nothing downstream will ever fire.
55
+ *
56
+ * That is not hypothetical. A run hung indefinitely after `firstToken`: the
57
+ * upstream went quiet mid-stream, and because the only abort path was the
58
+ * caller's own signal, nothing on this side was watching. The agent sat on
59
+ * "Working…" until the process was killed.
60
+ *
61
+ * Generous, because the cost of being wrong differs by direction. Too short
62
+ * kills a slow-but-live provider; too long only delays a retry that was always
63
+ * going to happen.
64
+ */
65
+ const STREAM_IDLE_DEFAULT_MS = 90_000
66
+
67
+ /**
68
+ * Read per call rather than captured at import: a module-level constant is
69
+ * evaluated once, before a test has had any chance to set the override, so
70
+ * the guard could not be exercised without waiting the full window.
71
+ */
72
+ const streamIdleMs = (): number => Number(process.env.AXON_STREAM_IDLE_MS) || STREAM_IDLE_DEFAULT_MS
73
+
74
+ /**
75
+ * The driver's stream, abandoned if it goes quiet.
76
+ *
77
+ * Wraps rather than replaces: the driver keeps its own signal handling, and
78
+ * this adds the guard it cannot provide — a driver cannot know whether silence
79
+ * means the provider is thinking or gone. Racing each `next()` against a timer
80
+ * is what makes the distinction observable at all.
81
+ *
82
+ * Throws on stall so the existing catch treats it exactly as any other engine
83
+ * fault: it retries, backs off, and records the attempt.
84
+ */
85
+ async function* withIdleTimeout<T>(
86
+ source: AsyncIterable<T>,
87
+ idleMs: number,
88
+ onStall: () => Error,
89
+ ): AsyncGenerator<T> {
90
+ const iterator = source[Symbol.asyncIterator]()
91
+ try {
92
+ for (;;) {
93
+ let timer: ReturnType<typeof setTimeout> | undefined
94
+ const stalled = new Promise<never>((_, reject) => {
95
+ timer = setTimeout(() => reject(onStall()), idleMs)
96
+ })
97
+ try {
98
+ const step = await Promise.race([iterator.next(), stalled])
99
+ if (step.done) return
100
+ yield step.value
101
+ } finally {
102
+ if (timer) clearTimeout(timer)
103
+ }
104
+ }
105
+ } finally {
106
+ // A stall leaves the underlying stream open — the provider still holds
107
+ // a connection nobody is reading. Closing it is what makes the retry a
108
+ // fresh call rather than a second reader on a dead socket.
109
+ //
110
+ // NOT awaited. `return()` resumes the generator at its suspension
111
+ // point, and a stalled one is suspended on a promise that never
112
+ // settles — so awaiting it deadlocks in the very case this guard
113
+ // exists to escape. Fire it and move on; the socket is closed by the
114
+ // driver's own signal handling and by process teardown.
115
+ void Promise.resolve(iterator.return?.()).catch(() => {})
116
+ }
117
+ }
118
+
119
+ /**
120
+ * The request for the next attempt, re-rendered from the session.
121
+ *
122
+ * The diagnostic reaches the model as part of the DOCUMENT, not appended after
123
+ * it. A violation is committed as an entry before this runs, so re-rendering
124
+ * now produces a context whose timeline ends with the rejected reply and the
125
+ * correction it earned — in the structure, in the order, where the contract
126
+ * says a `<system>` block lives.
127
+ *
128
+ * The previous version appended the correction as an extra message, which put
129
+ * it AFTER `</timeline>` — outside every structure the context had just spent
130
+ * ten thousand tokens establishing, in the last and highest-attention position
131
+ * on the wire. That is a demonstration that blocks may float free, delivered
132
+ * immediately before an instruction not to let blocks float free, and models
133
+ * were observed doing exactly that: emitting bare prose after being corrected
134
+ * for emitting bare prose.
135
+ *
136
+ * Always derived from the ORIGINAL call, never chained from the previous
137
+ * attempt's — the render decides what history to show, and stacking messages
138
+ * here would fight it.
139
+ */
140
+ async function reframe(call: AxonEngineCall, correction: string): Promise<AxonEngineCall> {
141
+ // A caller with no renderer (an internal one-shot with hand-built
142
+ // messages) has no document to rebuild. It still gets the correction —
143
+ // appended, since there is no structure to place it inside — because one
144
+ // out-of-band block in a two-message call is not the failure above.
145
+ if (!call.rerender) {
146
+ const framed = `<system type="format-violation" lang="md">\n${correction}\n</system>`
147
+ return { ...call, messages: [...call.messages, { role: "user" as const, content: framed }] }
148
+ }
149
+ return { ...call, messages: await call.rerender() }
150
+ }
151
+
152
+ /**
153
+ * What the model is told when a block never closed.
154
+ *
155
+ * Almost always a truncated stream rather than a choice — the provider stopped
156
+ * mid-block — so the instruction is "send it again", not "stop doing that".
157
+ * Naming the specific tag matters: the previous behaviour dropped the block
158
+ * silently and reported OUTPUT_EMPTY, which told a model that had just sent a
159
+ * script that it had sent no script, and quoted the script as proof.
160
+ */
161
+ function describeTruncatedBlock(tag: "text" | "script", raw: string | undefined): string {
162
+ const tail = (raw ?? "").trimEnd().slice(-160)
163
+ return [
164
+ `## Your \`<${tag}>\` block never closed`,
165
+ "",
166
+ `The reply ended part-way through a \`<${tag}>\` block — there was no \`</${tag}>\`, so nothing in it could be used.`,
167
+ "",
168
+ "This is usually a cut-off response rather than anything you did wrong.",
169
+ "",
170
+ ...(tail ? ["It ended here:", "", "```", tail, "```", ""] : []),
171
+ `Send the block again, complete, and close it with \`</${tag}>\`. If it was long, send a smaller step.`,
172
+ ].join("\n")
173
+ }
174
+
175
+ /**
176
+ * What the model is told when it sent more blocks than the grammar allows.
177
+ *
178
+ * Leads with the consequence rather than the rule. "One script per message" is
179
+ * a constraint to comply with; "your blocks all run at once, so the second
180
+ * cannot see what the first wrote" is a reason, and a model given the reason
181
+ * splits the work correctly instead of merely obeying.
182
+ */
183
+ function describeTooManyBlocks(texts: number, scripts: number): string {
184
+ const fence = (body: string): string => ["```", body, "```"].join("\n")
185
+ const over: string[] = []
186
+ if (scripts > 1) over.push(`${scripts} \`<script>\` blocks`)
187
+ if (texts > 1) over.push(`${texts} \`<text>\` blocks`)
188
+
189
+ return [
190
+ "## Too many blocks",
191
+ "",
192
+ `You sent ${over.join(" and ")}. A message carries at most one of each.`,
193
+ "",
194
+ ...(scripts > 1
195
+ ? [
196
+ "Every `<script>` in one message runs **at the same time**, not in order — so a later block cannot use what an earlier one wrote, and one failure discards them all.",
197
+ "",
198
+ "Send the FIRST step only. Its output comes back to you next turn, and you write the next step knowing what it returned.",
199
+ "",
200
+ ]
201
+ : []),
202
+ "Reply with one block:",
203
+ "",
204
+ fence("<text>…what you want to say…</text>\n<script>…one step of work…</script>"),
205
+ ].join("\n")
206
+ }
207
+
41
208
  /** Type errors as the model reads them — its own line numbers, its own code. */
42
- function describeViolations(problems: readonly OutputDiagnostic[]): string {
43
- const lines = problems.map(p => (p.line ? `line ${p.line}: ${p.message}` : p.message))
209
+ function describeViolations(problems: readonly OutputDiagnostic[], script?: string): string {
210
+ const fence = (body: string): string => ["```", body, "```"].join("\n")
211
+ const lines = problems.map(p => (p.line ? `- line ${p.line}: ${p.message}` : `- ${p.message}`))
44
212
  return [
45
- "Your <script> does not produce the required `result` shape:",
46
- ...lines.map(l => ` ${l}`),
47
- "Fix the script so `result` matches the declared type, then reply again.",
213
+ "## Your `<script>` does not produce the required shape",
214
+ "",
215
+ ...lines,
216
+ "",
217
+ // The script itself, quoted back.
218
+ //
219
+ // Without it the model reads a line number against code it can no
220
+ // longer see: the reply was discarded, so "line 3" refers to nothing
221
+ // in its context. A diagnostic that names a location has to show the
222
+ // thing the location is in.
223
+ ...(script ? ["This is the script that was rejected:", "", fence(script.trim()), ""] : []),
224
+ "Fix it so `result` matches the declared type, then reply again.",
48
225
  ].join("\n")
49
226
  }
50
227
 
228
+ /**
229
+ * The tags the protocol actually defines. Anything else in a reply is a tag
230
+ * the model invented, and naming it back is the whole difference between a
231
+ * correctable instruction and a restatement of the rules it already read.
232
+ */
233
+ const KNOWN_BLOCKS = new Set(["text", "script", "done", "thinking"])
234
+
235
+ /**
236
+ * The first tag in a reply that is NOT one of ours, or undefined.
237
+ *
238
+ * This is what turns "your reply had no block" — which reads as false to a
239
+ * model that plainly wrapped its content — into "you used <lemma_code>, which
240
+ * is not a block". A model given the second has somewhere to go.
241
+ */
242
+ function unknownTagIn(text: string | undefined): string | undefined {
243
+ if (!text) return undefined
244
+ for (const match of text.matchAll(/<\s*([a-zA-Z][\w:-]*)/g)) {
245
+ const tag = match[1]!
246
+ if (!KNOWN_BLOCKS.has(tag.toLowerCase())) return tag
247
+ }
248
+ return undefined
249
+ }
250
+
251
+ /** Does this look like code rather than prose? Used only to pick which block to name. */
252
+ function looksLikeCode(text: string): boolean {
253
+ return /\b(?:const|let|var|await|function|import|return|=>)\b/.test(text)
254
+ }
255
+
51
256
  /**
52
257
  * What the model is told when its reply parsed to nothing at all.
53
258
  *
54
259
  * Written as an instruction rather than a report, and it names the exact tags,
55
260
  * because this is fed straight back as the next attempt's context and the model
56
- * has to act on it without any other explanation. The most common cause is
57
- * prose emitted bare — the reply is right there, just outside any block, and
58
- * the parser has nowhere to put it.
261
+ * has to act on it without any other explanation.
262
+ *
263
+ * ── Why it diagnoses instead of restating ────────────────────────────────────
264
+ *
265
+ * The first version said the same nine lines every attempt and varied only the
266
+ * quoted excerpt. That is a weak steer, and against a specific failure it is
267
+ * actively confusing: a model that replied `<lemma_code><code>…</code>` DID
268
+ * wrap its content, so "wrap your content" reads as a contradiction and offers
269
+ * no gradient. A real run died that way — three attempts, the third carrying
270
+ * complete correct TypeScript one tag-name away from valid.
271
+ *
272
+ * So the message leads with what THIS reply did wrong. An invented tag gets
273
+ * named and mapped to the block it should have been; a bare fragment gets told
274
+ * it was cut short; prose outside a block gets the original explanation, which
275
+ * was always right for that case.
276
+ *
277
+ * `attempt` escalates the tone. By the last try the model has read the rules
278
+ * twice and not complied, so repeating them a third time is not the move —
279
+ * the final message is short, imperative, and asks for one block and nothing
280
+ * else.
59
281
  */
60
- function describeEmptyResponse(protocol: string | undefined, excerpt: string): string {
61
- return [
62
- "Your reply contained no <template> or <script> block, so none of it could be used.",
63
- "Every reply must wrap its content:",
64
- " <template>…what you want to say…</template>",
65
- " <script>…code you want to run…</script>",
66
- "Text outside a block is discarded.",
67
- ...(protocol ? [`Protocol: ${protocol}.`] : []),
68
- excerpt ? `You replied: ${excerpt}` : "",
69
- "Send the same reply again, wrapped correctly.",
70
- ].filter(Boolean).join("\n")
71
- }
282
+ function describeEmptyResponse(
283
+ protocol: string | undefined,
284
+ raw: string | undefined,
285
+ attempt: number,
286
+ lastAttempt: boolean,
287
+ ): string {
288
+ const unknown = unknownTagIn(raw)
289
+ const suggested = raw && looksLikeCode(raw) ? "script" : "text"
290
+
291
+ // Written as MARKDOWN, because that is what it is rendered as: the
292
+ // correction lands in a `lang="md"` system block, so a heading is a
293
+ // heading and a fenced example is a fence. Bare tags are backticked —
294
+ // unquoted `<text>` in markdown is an HTML tag, which a model may
295
+ // read as structure rather than as the literal string it must type.
296
+ const fence = (body: string): string => ["```", body, "```"].join("\n")
297
+
298
+ // Tags are LITERAL here.
299
+ //
300
+ // This message reaches the model through steer(), which appends it to the
301
+ // request as-is — it does not pass through the <system> body renderer, so
302
+ // nothing escapes it downstream. The one message whose entire job is "emit
303
+ // exactly these characters" must therefore contain exactly those
304
+ // characters.
305
+ //
306
+ // The copy committed to the SESSION renders through that escaper and comes
307
+ // out as entities, which is correct for a transcript nobody has to retype.
308
+ // Two audiences, two paths, and only one of them is being instructed.
309
+ const tag = (name: string): string => `<${name}>`
310
+ const closeTag = (name: string): string => `</${name}>`
311
+
312
+ // Last chance: no explanation, just the shape. Everything the model needed
313
+ // to know it has already been told twice.
314
+ if (lastAttempt) {
315
+ return [
316
+ "## Final attempt",
317
+ "",
318
+ "Reply with exactly one block and nothing outside it:",
319
+ "",
320
+ fence(`${tag(suggested)}…${closeTag(suggested)}`),
321
+ "",
322
+ ...(unknown ? [`Do **not** use \`${tag(unknown)}\` — it is not a block in this protocol.`, ""] : []),
323
+ `Valid blocks: \`${tag("text")}\` for prose, \`${tag("script")}\` for code, \`<done/>\` when finished.`,
324
+ ].join("\n")
325
+ }
326
+
327
+ const lead = unknown
328
+ ? [
329
+ `## Wrong tag: \`${tag(unknown)}\``,
330
+ "",
331
+ `\`${tag(unknown)}\` is not a block in this protocol. The content itself looked right — only the tag was wrong.`,
332
+ "",
333
+ `Send the same content wrapped in \`${tag(suggested)}\` instead:`,
334
+ "",
335
+ fence(`${tag(suggested)}…your content…${closeTag(suggested)}`),
336
+ ]
337
+ : [
338
+ "## No block in your reply",
339
+ "",
340
+ `Your reply contained no \`${tag("text")}\` or \`${tag("script")}\` block, so none of it could be used. Text outside a block is discarded.`,
341
+ "",
342
+ "Every reply must wrap its content:",
343
+ "",
344
+ fence(`${tag("text")}…what you want to say…${closeTag("text")}\n${tag("script")}…code you want to run…${closeTag("script")}`),
345
+ ]
72
346
 
73
- /** The head of a raw reply, for quoting back to the model without flooding context. */
74
- function excerptOf(text: string | undefined): string {
75
- if (!text) return ""
76
- const flat = text.replace(/\s+/g, " ").trim()
77
- return flat.length > 200 ? `${flat.slice(0, 200)}…` : flat
347
+ return [
348
+ ...lead,
349
+ "",
350
+ `Valid blocks: \`${tag("text")}\`, \`${tag("script")}\`, \`<done/>\`. There are no others.`,
351
+ ...(protocol ? ["", `Protocol: \`${protocol}\`.`] : []),
352
+ // The reply itself is NOT quoted here.
353
+ //
354
+ // It is committed as its own entry and renders directly above this
355
+ // correction, as the blocks the model sent with `status="rejected"` on
356
+ // them. Quoting it again put the same text on screen twice — once as
357
+ // the model's own output and once as a fenced string inside the
358
+ // complaint about it — which is noise in the exact place attention
359
+ // matters most.
360
+ ...(attempt > 1 ? ["", `This is attempt ${attempt}. The previous attempt failed the same way.`] : []),
361
+ ].join("\n")
78
362
  }
79
363
 
80
364
  /**
@@ -122,7 +406,7 @@ export function Engine(opts: EngineOpts) {
122
406
  * streamed, and the durable accounting span. It knows the grammar only
123
407
  * well enough to parse it, and nothing about what the blocks MEAN.
124
408
  *
125
- * The response half (running scripts, rendering templates, enforcing an
409
+ * The response half (running scripts, rendering text, enforcing an
126
410
  * output shape) wraps this — see stream() below.
127
411
  */
128
412
  async function* blocks(
@@ -165,9 +449,34 @@ export function Engine(opts: EngineOpts) {
165
449
  bytes: new TextEncoder().encode(JSON.stringify(req.messages)).byteLength,
166
450
  }, span)
167
451
 
452
+ /**
453
+ * The request as the NEXT attempt will see it.
454
+ *
455
+ * Retries used to re-send `req` byte for byte. The diagnostic was
456
+ * committed to the session, and the session is rendered once per TICK
457
+ * — but all three attempts happen inside one tick, so the model was
458
+ * re-asked the identical question three times and told nothing about
459
+ * why the last answer failed. Three identical prompts get three
460
+ * similar replies; that is what a run looked like when it died here.
461
+ *
462
+ * Appended as a user turn rather than folded into the system message:
463
+ * it is feedback about the exchange in progress, and it must be the
464
+ * last thing the model reads.
465
+ */
168
466
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
169
467
  const parser = air.parser()
170
468
  let semanticOutputSeen = false
469
+ /**
470
+ * Whether anything reached the CONSUMER this attempt.
471
+ *
472
+ * Distinct from `semanticOutputSeen`, which is true the moment a
473
+ * non-blank delta arrives — including one that never completed a
474
+ * block and so never crossed to anyone. Retry has to be gated on
475
+ * what escaped, not on what was received: a stream that produced
476
+ * `<text>thinking` and then died emitted nothing usable, and
477
+ * refusing to retry it strands the caller on a partial reply.
478
+ */
479
+ let emitted = false
171
480
  let doneSeen = false
172
481
  const started = Date.now()
173
482
  let firstTokenAt: number | undefined
@@ -183,9 +492,31 @@ export function Engine(opts: EngineOpts) {
183
492
  let streamedText = ""
184
493
 
185
494
  try {
186
- for await (const raw of selected.driver.stream(req)) {
187
- if (raw.type !== "done") {
188
- firstTokenAt ??= Date.now()
495
+ const wire = withIdleTimeout(
496
+ selected.driver.stream(req),
497
+ streamIdleMs(),
498
+ () => new EngineFailure({
499
+ code: "TRANSPORT",
500
+ message: `engine stream produced nothing for ${streamIdleMs() / 1000}s — abandoning the call`,
501
+ retryable: true,
502
+ provider: selected.name,
503
+ ...(model ? { model } : {}),
504
+ }),
505
+ )
506
+
507
+ for await (const raw of wire) {
508
+ if (raw.type !== "done" && firstTokenAt === undefined) {
509
+ firstTokenAt = Date.now()
510
+ // Committed as it happens rather than folded into
511
+ // :complete's meta, so the latency/generation split is
512
+ // visible on a live bar and survives a call that never
513
+ // completes. Awaited like every other commit in this
514
+ // span — the writer serializes, and ordering before the
515
+ // first parsed block is what makes containment honest.
516
+ await opts.session.commit("kernel:engine:firstToken", {
517
+ attempt,
518
+ elapsedMs: firstTokenAt - started,
519
+ }, span)
189
520
  }
190
521
  if (raw.type === "text:delta" && raw.content.trim()) semanticOutputSeen = true
191
522
 
@@ -196,7 +527,21 @@ export function Engine(opts: EngineOpts) {
196
527
  // (extend) from a full re-feed (which would
197
528
  // double-fire every already-streamed block).
198
529
  streamedText += raw.content
199
- yield* parser.feed(raw.content)
530
+ for (const event of parser.feed(raw.content)) {
531
+ // What forfeits the retry is output the caller
532
+ // can KEEP — a block that closed.
533
+ //
534
+ // An `open` is a structural marker, and a
535
+ // `delta` is a fragment of a block that may
536
+ // never close: a stream that emitted
537
+ // `<text>thinking` and then went silent gave
538
+ // the caller nothing usable, but counted as
539
+ // escaped output and blocked the retry, so the
540
+ // whole call failed on a stall it was supposed
541
+ // to recover from.
542
+ if (event.type.endsWith(":done")) emitted = true
543
+ yield event
544
+ }
200
545
  break
201
546
 
202
547
  case "thinking:delta":
@@ -269,7 +614,11 @@ export function Engine(opts: EngineOpts) {
269
614
  if (req.signal?.aborted) throw abortError(req.signal)
270
615
 
271
616
  const fault = asEngineFault(error, correlation)
272
- const canRetry = fault.retryable && !semanticOutputSeen && !req.signal?.aborted && attempt < MAX_ATTEMPTS
617
+ // Gated on what ESCAPED, not on what arrived. A stall after a
618
+ // partial delta produced no usable output, and treating those
619
+ // bytes as "already emitted" left the caller with a truncated
620
+ // reply and no second attempt.
621
+ const canRetry = fault.retryable && !emitted && !req.signal?.aborted && attempt < MAX_ATTEMPTS
273
622
 
274
623
  if (canRetry) {
275
624
  const suggestedDelay = fault.retryAfterMs ?? RETRY_DELAYS_MS[attempt - 1] ?? RETRY_DELAYS_MS.at(-1)!
@@ -345,7 +694,7 @@ export function Engine(opts: EngineOpts) {
345
694
  // BLOCK AT ALL is another, and it does not depend on the caller having
346
695
  // asked for a shape — the protocol itself requires the reply to be
347
696
  // wrapped. Gating retries on `output` meant a model that forgot
348
- // `<template>` got exactly one attempt, its prose was discarded by the
697
+ // `<text>` got exactly one attempt, its prose was discarded by the
349
698
  // parser, and the run completed clean with an empty screen.
350
699
  const budget = call.retries ?? DEFAULT_OUTPUT_RETRIES
351
700
  let lastFault: string | undefined
@@ -354,12 +703,59 @@ export function Engine(opts: EngineOpts) {
354
703
 
355
704
  yield { type: "engine:start" }
356
705
 
706
+ /**
707
+ * The call as the NEXT attempt will make it.
708
+ *
709
+ * Retries used to re-send `call` byte for byte. The diagnostic was
710
+ * committed to the session, and the session is rendered once per TICK
711
+ * — but every retry happens inside one tick, so the model was re-asked
712
+ * the identical question and told nothing about why its last answer
713
+ * failed. Three identical prompts get three similar replies, which is
714
+ * precisely how a run died here: `<lemma?`, then prose, then prose.
715
+ *
716
+ * Always derived from the ORIGINAL call, never chained from the
717
+ * previous attempt's: stacking corrections would put three of them —
718
+ * each quoting a malformed reply — in front of the third try, which is
719
+ * the accumulation the render-side collapse exists to prevent.
720
+ */
721
+ let attemptCall = call
722
+
357
723
  for (let attempt = 0; attempt <= budget; attempt++) {
358
- const raw = blocks(call, context)
724
+ const raw = blocks(attemptCall, context)
359
725
  let violations: readonly OutputDiagnostic[] = []
726
+ let violatingScript: string | undefined
360
727
  let spoke = false
361
728
  let acted = false
362
729
  let yielded = false
730
+ /**
731
+ * How many of each block this reply carried.
732
+ *
733
+ * The grammar allows one of each, and models were emitting four
734
+ * and five scripts in a single message — which runs them as a
735
+ * concurrent batch, so a write in block three and a read in block
736
+ * four race, and one bad pattern discards the lot. Counted rather
737
+ * than silently truncated: a reply that broke the shape is
738
+ * returned for the model to correct, the same as any other
739
+ * contract violation.
740
+ */
741
+ /**
742
+ * A block whose closing tag never arrived.
743
+ *
744
+ * Dropped silently before, which produced the WRONG diagnostic: a
745
+ * truncated `<script>` reported as OUTPUT_EMPTY — "your reply
746
+ * contained no block" — while the correction quoted that very
747
+ * block back as proof. A model told a script block is not a script
748
+ * block has no move left, and a real run looped until it exhausted
749
+ * its retries.
750
+ *
751
+ * Naming it is the whole fix: "your block never closed" is
752
+ * actionable, and it is usually a provider truncation rather than
753
+ * anything the model chose.
754
+ */
755
+ let truncated: "text" | "script" | undefined
756
+
757
+ let texts = 0
758
+ let scripts = 0
363
759
  let lang: "md" | "json" = "md"
364
760
  let group: string | null = null
365
761
  let pending: string | null = null
@@ -375,12 +771,22 @@ export function Engine(opts: EngineOpts) {
375
771
  while (!step.done) {
376
772
  const block = step.value
377
773
  switch (block.type) {
378
- case "template:open":
774
+ case "text:open":
379
775
  lang = block.lang
380
776
  break
381
777
 
382
- case "template:delta":
383
- if (pending !== null) {
778
+ case "text:delta":
779
+ // A chunk with no VISIBLE content is not something the
780
+ // agent said.
781
+ //
782
+ // Guarded on `.trim()`, not on truthiness: a model that
783
+ // opens `<text>` and closes it after a newline emits a
784
+ // delta of `"\n"`, which is truthy, and that reached
785
+ // the UI as a bullet with nothing beside it. `text:done`
786
+ // already dropped the empty tail; this is the same rule
787
+ // one step earlier, and whitespace is the case that
788
+ // actually happens in a run.
789
+ if (pending?.trim()) {
384
790
  group ??= crypto.randomUUID()
385
791
  spoke = true
386
792
  events.push({ type: "engine:text", content: pending, lang, chunk: { of: group } })
@@ -388,12 +794,16 @@ export function Engine(opts: EngineOpts) {
388
794
  pending = block.content
389
795
  break
390
796
 
391
- case "template:done": {
392
- if (block.incomplete) break
797
+ case "text:done": {
798
+ if (block.incomplete) { truncated = "text"; break }
393
799
  const last = pending ?? block.content
394
800
  pending = null
395
- if (!last) break
801
+ // Same rule as the delta path: a block whose whole
802
+ // content is whitespace is a message the agent did not
803
+ // write, and forwarding it produces an empty bubble.
804
+ if (!last.trim()) break
396
805
  spoke = true
806
+ texts++
397
807
  events.push(group
398
808
  ? { type: "engine:text", content: last, lang, chunk: { of: group, final: true } }
399
809
  : { type: "engine:text", content: last, lang })
@@ -402,7 +812,7 @@ export function Engine(opts: EngineOpts) {
402
812
  }
403
813
 
404
814
  case "script:done": {
405
- if (block.incomplete) break
815
+ if (block.incomplete) { truncated = "script"; break }
406
816
  // Checked BEFORE it is reported, so a script that
407
817
  // cannot satisfy the contract is never handed to a
408
818
  // cognet that would run it.
@@ -410,10 +820,15 @@ export function Engine(opts: EngineOpts) {
410
820
  const problems = output.check(block.content)
411
821
  if (problems.length > 0) {
412
822
  violations = problems
823
+ // Kept so the diagnostic can quote it: a line
824
+ // number against code the model can no longer
825
+ // see points at nothing.
826
+ violatingScript = block.content
413
827
  break
414
828
  }
415
829
  }
416
830
  acted = true
831
+ scripts++
417
832
  events.push({ type: "engine:script", id: crypto.randomUUID(), content: block.content })
418
833
  break
419
834
  }
@@ -430,6 +845,27 @@ export function Engine(opts: EngineOpts) {
430
845
  step = await raw.next()
431
846
  }
432
847
 
848
+ // One block of each kind, at most.
849
+ //
850
+ // Several scripts in one message run as a CONCURRENT batch, which
851
+ // the model does not expect: a run was observed writing a file in
852
+ // one block and reading it in the next, and the read lost the
853
+ // race. Five blocks also means one bad pattern discards four good
854
+ // ones, and a message that long tends to end `</script><done/>`
855
+ // followed by another `<text>` — the model losing track of its
856
+ // own boundary.
857
+ //
858
+ // Reported as a violation rather than truncated: the extra blocks
859
+ // are work the model intended, and silently dropping them would
860
+ // leave it believing they ran.
861
+ if (violations.length === 0 && (texts > 1 || scripts > 1)) {
862
+ lastFault = describeTooManyBlocks(texts, scripts)
863
+ lastFailure = "shape"
864
+ await opts.fault({ code: "OUTPUT_TOO_MANY_BLOCKS", message: lastFault, rejected: step.value?.text, attempt: attempt + 1 })
865
+ attemptCall = await reframe(call, lastFault)
866
+ continue
867
+ }
868
+
433
869
  // A reply that parsed to no block is unusable, whatever it said.
434
870
  //
435
871
  // Checked separately from `violations` because it is a different
@@ -439,13 +875,54 @@ export function Engine(opts: EngineOpts) {
439
875
  // reply and the user saw a blank screen. Retrying with the excerpt
440
876
  // quoted back steers it in one attempt.
441
877
  //
442
- // `yielded` is deliberately not part of this test. A reply that
443
- // spoke or acted but forgot `<done/>` still produced something the
444
- // cognet can use, and the loop's own stop condition owns that.
445
- if (violations.length === 0 && !spoke && !acted) {
446
- lastFault = describeEmptyResponse(call.protocol, excerptOf(step.value?.text))
878
+ // A reply that is ONLY `<done/>` is not that failure. It is the
879
+ // model saying it has nothing further to add — the exact signal
880
+ // the loop's stop condition reads (`yielded && !acted`), and the
881
+ // natural reply after a turn that already spoke and then acted.
882
+ // Treating it as empty forced a model with nothing left to say to
883
+ // invent something, three times, and then failed the wake.
884
+ //
885
+ // ONLY when it is alone. `<done/>` riding alongside discarded
886
+ // prose is the original failure with a tag on the end — the model
887
+ // answered outside any block, the user saw nothing, and that must
888
+ // still retry. So this asks what the reply was APART from the
889
+ // marker, rather than trusting the marker's presence.
890
+ const spareText = (step.value?.text ?? "").replace(/<done\s*\/?>/g, "").trim()
891
+
892
+ // ...and only on a FIRST attempt. After a correction, a bare
893
+ // `<done/>` is not a model with nothing to add — it is a model
894
+ // that was told its reply had no block and answered by deleting
895
+ // the reply. A real run ended that way: prose + `<done/>` was
896
+ // discarded, the retry asked for it wrapped, and the model sent
897
+ // the marker alone, which silently became a finished turn and
898
+ // stopped the loop with the work untouched.
899
+ //
900
+ // Accepting that would make the correction a way OUT of the
901
+ // protocol rather than into it.
902
+ const doneOnly = yielded && spareText.length === 0 && attempt === 0
903
+
904
+ // A block that never closed is NOT an empty reply, and saying so is
905
+ // the difference between a diagnostic and a contradiction. The
906
+ // model sent a `<script>`; telling it that it sent no script —
907
+ // while quoting the script — leaves it nothing to correct.
908
+ if (violations.length === 0 && !spoke && !acted && truncated) {
909
+ lastFault = describeTruncatedBlock(truncated, step.value?.text)
910
+ lastFailure = "empty"
911
+ await opts.fault({ code: "OUTPUT_TRUNCATED", message: lastFault, rejected: step.value?.text, attempt: attempt + 1 })
912
+ attemptCall = await reframe(call, lastFault)
913
+ continue
914
+ }
915
+
916
+ if (violations.length === 0 && !spoke && !acted && !doneOnly) {
917
+ lastFault = describeEmptyResponse(
918
+ call.protocol,
919
+ step.value?.text,
920
+ attempt,
921
+ attempt >= budget,
922
+ )
447
923
  lastFailure = "empty"
448
- await opts.fault({ code: "OUTPUT_EMPTY", message: lastFault })
924
+ await opts.fault({ code: "OUTPUT_EMPTY", message: lastFault, rejected: step.value?.text, attempt: attempt + 1 })
925
+ attemptCall = await reframe(call, lastFault)
449
926
  continue
450
927
  }
451
928
 
@@ -459,9 +936,10 @@ export function Engine(opts: EngineOpts) {
459
936
  // failed its contract is not a partial answer, it is a discarded
460
937
  // one. The diagnostic is committed so the next attempt's context
461
938
  // carries it, and the model rewrites against its own error.
462
- lastFault = describeViolations(violations)
939
+ lastFault = describeViolations(violations, violatingScript)
463
940
  lastFailure = "shape"
464
- await opts.fault({ code: "OUTPUT_TYPE_ERROR", message: lastFault })
941
+ await opts.fault({ code: "OUTPUT_TYPE_ERROR", message: lastFault, rejected: step.value?.text, attempt: attempt + 1 })
942
+ attemptCall = await reframe(call, lastFault)
465
943
  }
466
944
 
467
945
  // Budget exhausted. Loud, never a degraded return: a caller that
@@ -479,7 +957,7 @@ export function Engine(opts: EngineOpts) {
479
957
  type: "engine:failure",
480
958
  error: lastFailure === "empty"
481
959
  ? err("OUTPUT_EMPTY", {
482
- detail: `the model produced no <template> or <script> block in ${budget + 1} attempts — `
960
+ detail: `the model produced no <text> or <script> block in ${budget + 1} attempts — `
483
961
  + `its replies could not be used. Last attempt: ${lastFault}`,
484
962
  context: { attempts: budget + 1, provider: current?.name, model: call.model },
485
963
  })
package/src/kernel.ts CHANGED
@@ -10,7 +10,7 @@ import { Scheduler } from "./scheduler"
10
10
  import type { KernelCognet } from "./contracts"
11
11
  import { Store } from "./store"
12
12
  import { Knowledge } from "./knowledge"
13
- import type { AxonHost } from "@arcforge/types"
13
+ import type { AxonEscalate, AxonHost } from "@arcforge/types"
14
14
 
15
15
  type KernelOpts = {
16
16
  blueprint: AxonBlueprint
@@ -47,11 +47,30 @@ type KernelOpts = {
47
47
  */
48
48
  onUpdate?: (blueprint: AxonBlueprint) => void
49
49
  host?: AxonHost
50
+ /**
51
+ * The platform's policy decider — consulted when a rule says "escalate".
52
+ *
53
+ * Host-side, never routed through AxonHost: that is the guest's channel,
54
+ * and a sandboxed program able to reach the decider could raise or answer
55
+ * its own escalations. Absent = no decider, which the capsule treats as
56
+ * deny — the honest state for a headless run.
57
+ */
58
+ escalate?: AxonEscalate
50
59
  }
51
60
 
52
61
  type KernelInput = {
53
62
  /** User message committed before the wake starts. */
54
63
  content?: string | string[]
64
+ /**
65
+ * The surface this message arrived on, and the address a reply goes back
66
+ * to — `terminal`, `axon-cli`, `telegram:8199237521`.
67
+ *
68
+ * Named by whoever emits it, not by the kernel: the runtime has no way to
69
+ * know which surface it is embedded in, and a hardcoded value made every
70
+ * host claim to be the same one. Defaults to `terminal` for a caller that
71
+ * says nothing, which is what a direct `request()` effectively is.
72
+ */
73
+ channel?: string
55
74
  /**
56
75
  * The structured shape this invocation must produce, already compiled by
57
76
  * the caller (Axon's handle) so a bad type throws at the call site,
@@ -66,11 +85,67 @@ type KernelInput = {
66
85
  const COGNET_EVENT_PREFIX = "cognet:"
67
86
 
68
87
  /** Render a run's completion value for the visible tool-call log. Strings pass through; everything else is JSON. */
88
+ /**
89
+ * How much of one action's output may reach the log, and so the context.
90
+ *
91
+ * A backstop, not a policy: tools are expected to bound their own results
92
+ * (fs.query has a line budget for exactly this reason), and this catches the
93
+ * ones that do not. A single call once returned 244k characters — ~61k tokens
94
+ * — which quadrupled the context in one tick and stalled the run that read it.
95
+ *
96
+ * Generous enough that ordinary output is untouched: a full file read, a long
97
+ * build log, a wide directory listing all fit well inside it. What does not
98
+ * fit is a result nobody could read anyway.
99
+ */
100
+ const MAX_RESULT_DEFAULT_CHARS = 40_000
101
+
102
+ /** Read per call, not captured at import — see streamIdleMs in engine.ts. */
103
+ const maxResultChars = (): number => Number(process.env.AXON_MAX_RESULT_CHARS) || MAX_RESULT_DEFAULT_CHARS
104
+
105
+ /**
106
+ * Truncate an oversized result, and SAY SO in the result itself.
107
+ *
108
+ * The marker is the point. A silently trimmed result teaches the model that
109
+ * its query was fine and the data was small, so it never narrows — whereas a
110
+ * result that names its own truncation, and by how much, is a fact the model
111
+ * can act on. Both ends are kept because the tail of a command's output is
112
+ * usually where the answer or the error is.
113
+ */
114
+ function capResult(content: string): string {
115
+ const max = maxResultChars()
116
+ if (content.length <= max) return content
117
+
118
+ const keep = Math.floor(max / 2)
119
+ const head = content.slice(0, keep)
120
+ const tail = content.slice(-keep)
121
+ const dropped = content.length - keep * 2
122
+ return `${head}\n\n[... ${dropped.toLocaleString()} characters truncated of ${content.length.toLocaleString()} total — `
123
+ + `narrow the query (fewer files, less context, a more specific pattern) to see the rest ...]\n\n${tail}`
124
+ }
125
+
126
+ /**
127
+ * A returned value, as the model reads it.
128
+ *
129
+ * COMPACT, not pretty-printed. `JSON.stringify(v, null, 2)` spends 46% of its
130
+ * output on indentation — measured on a real result, 58% of the whole payload
131
+ * was whitespace and structural punctuation — and none of it helps a reader
132
+ * that does not need the tree aligned to parse it. A 40k-char result becomes
133
+ * 24k with no information removed, which is 4k tokens of context back on every
134
+ * call that returns a structure.
135
+ *
136
+ * The saving compounds: results are the largest thing in a long run's context
137
+ * (174k of a 300k prompt, in the run that motivated this), so indentation was
138
+ * the single biggest avoidable cost in the loop.
139
+ *
140
+ * Strings pass through untouched — a file's contents are already the shape the
141
+ * model wants, and quoting them would be the same mistake in the other
142
+ * direction.
143
+ */
69
144
  function formatValue(value: unknown): string {
70
145
  if (value === undefined) return ""
71
146
  if (typeof value === "string") return value
72
147
  try {
73
- return JSON.stringify(value, null, 2) ?? ""
148
+ return JSON.stringify(value) ?? ""
74
149
  } catch {
75
150
  return String(value)
76
151
  }
@@ -203,6 +278,7 @@ export async function Kernel(opts: KernelOpts) {
203
278
  run: () => scheduler.current(),
204
279
  cwd: opts.cwd,
205
280
  ...(opts.host ? { host: opts.host } : {}),
281
+ ...(opts.escalate ? { escalate: opts.escalate } : {}),
206
282
  })
207
283
 
208
284
  const engine = Engine({
@@ -234,10 +310,17 @@ export async function Kernel(opts: KernelOpts) {
234
310
  *
235
311
  * Mutations commit through the kernel, never the cognet: same rule as
236
312
  * run()'s action/result pair — the brain requests, the kernel records.
237
- * Fire-and-forget with a swallowed rejection for the same reason emit()
238
- * swallows: the write already succeeded and resolved to the caller, so a
239
- * failed telemetry append has nowhere to surface, and must never take
240
- * down the runtime it is observing.
313
+ *
314
+ * Fire-and-forget, because the write already succeeded and resolved to the
315
+ * caller — there is no honest way to fail it after the fact, and telemetry
316
+ * must never take down the runtime it observes.
317
+ *
318
+ * But NOT silent. This is the audit record for "the agent rewrote its own
319
+ * long-term memory", which is exactly the fact you want when behaviour
320
+ * drifts weeks later; a bare catch would let the ledger disagree with the
321
+ * filesystem with nothing anywhere to say so. Routing the rejection
322
+ * through err() delivers it to the runtime's error sink — the record
323
+ * still shows something went wrong, without the append becoming fatal.
241
324
  */
242
325
  const knowledge = Knowledge({
243
326
  root: opts.blueprint.paths.root,
@@ -245,7 +328,13 @@ export async function Kernel(opts: KernelOpts) {
245
328
  onMutate: (event, name) => {
246
329
  void session
247
330
  .commit(`cognet:knowledge:${event}`, { name }, scheduler.current() ?? undefined)
248
- .catch(() => {})
331
+ .catch((cause) => {
332
+ err("KNOWLEDGE_RECORD_FAILED", {
333
+ detail: `knowledge ${event} of "${name}" succeeded but its record could not be committed`,
334
+ context: { event, name },
335
+ cause,
336
+ })
337
+ })
249
338
  },
250
339
  })
251
340
 
@@ -324,7 +413,9 @@ export async function Kernel(opts: KernelOpts) {
324
413
  await session.commitEntry("cognet:action:result", {
325
414
  for: id,
326
415
  ok: result.ok,
327
- content: [...result.stdout, result.ok ? formatValue(result.value) : ""].filter(s => s.length > 0).join("\n"),
416
+ content: capResult(
417
+ [...result.stdout, result.ok ? formatValue(result.value) : ""].filter(s => s.length > 0).join("\n"),
418
+ ),
328
419
  ...(result.error ? { error: result.error } : {}),
329
420
  }, run)
330
421
  return result
@@ -353,15 +444,35 @@ export async function Kernel(opts: KernelOpts) {
353
444
  * naming a binding that was never declared). One shape, one entry type,
354
445
  * one thing for a host to recognise and hide.
355
446
  */
356
- function recordFault(
357
- fault: { code: string; message: string; excerpt?: string },
447
+ async function recordFault(
448
+ fault: { code: string; message: string; excerpt?: string; rejected?: string; attempt?: number },
358
449
  run: { runId: string } | undefined,
359
450
  ): Promise<unknown> {
451
+ // The rejected reply first, so the timeline reads in the order it
452
+ // happened: the model spoke, then it was corrected. Committed as its
453
+ // own entry rather than folded into the message because it is the
454
+ // agent's own output, not the runtime's commentary on it — and a
455
+ // reader that hides system messages must still see what was said.
456
+ if (fault.rejected !== undefined && fault.rejected.trim().length > 0) {
457
+ await session.commitEntry("axon:system:malformed", {
458
+ content: fault.rejected,
459
+ code: fault.code,
460
+ attempt: fault.attempt ?? 1,
461
+ }, run)
462
+ }
463
+
464
+ // MARKDOWN, and the code as an attribute rather than a prefix.
465
+ //
466
+ // These messages are written as markdown — headings, fenced examples,
467
+ // backticked tags — and labelling them `txt` asks the model to read
468
+ // structure it was told not to expect. The code was also prepended
469
+ // inline, which put `OUTPUT_EMPTY: ` in front of a `##` heading and
470
+ // broke the first line of every one of them.
360
471
  return session.commitEntry("axon:system:message", {
361
472
  type: "format-violation",
362
- lang: "txt",
363
- content: `${fault.code}: ${fault.message}`,
364
- ...(fault.excerpt ? { attributes: { excerpt: fault.excerpt } } : {}),
473
+ lang: "md",
474
+ content: fault.message,
475
+ attributes: { code: fault.code, ...(fault.excerpt ? { excerpt: fault.excerpt } : {}) },
365
476
  }, run)
366
477
  }
367
478
 
@@ -394,6 +505,23 @@ export async function Kernel(opts: KernelOpts) {
394
505
  yield event
395
506
  throw event.error
396
507
  }
508
+
509
+ // The turn the model declared over, written down.
510
+ //
511
+ // `<done/>` was parsed as a signal and dropped, so it was the one
512
+ // block absent from the model's own record: it read the rule every
513
+ // call and never once saw itself having followed it. Committing it
514
+ // puts the turn boundary in the history the model reads back, which
515
+ // is where every other block already earns its reinforcement.
516
+ //
517
+ // Committed HERE rather than by the cognet: a cognet reads
518
+ // `yielded` to decide whether to keep looping, which is a
519
+ // cognition decision. Writing the fact down is the kernel's, the
520
+ // same as every other entry.
521
+ if (event.type === "engine:done" && event.yielded) {
522
+ await session.commitEntry("axon:agent:done", {}, run)
523
+ }
524
+
397
525
  yield event
398
526
  }
399
527
  }
@@ -689,6 +817,11 @@ export async function Kernel(opts: KernelOpts) {
689
817
  // stop claiming a brain that is gone, and a cognet whose unload
690
818
  // failed is no more wakeable than one whose unload worked.
691
819
  scheduler.detach()
820
+ // Drop the stimulus subscription too — detach() stops wakes, but
821
+ // the bus would otherwise hold this scheduler alive for the life
822
+ // of the process, and a host running several agents in sequence
823
+ // accumulates one dead listener per shutdown.
824
+ scheduler.dispose()
692
825
 
693
826
  await capsule.shutdown()
694
827
  if (failure) throw failure
@@ -20,6 +20,8 @@ const ABANDON_MS = 30_000
20
20
 
21
21
  type StreamInput = {
22
22
  content?: string | string[]
23
+ /** The surface the message arrived on — see the ingest below. */
24
+ channel?: string
23
25
  }
24
26
 
25
27
  /**
@@ -62,7 +64,22 @@ export function Invocation(opts: InvocationOpts) {
62
64
  : Array.isArray(input.content) ? input.content : [input.content]
63
65
  for (const content of contents) {
64
66
  const entry = await opts.session.stimuli.ingest("cognet:stimulus:text", {
65
- channel: "user",
67
+ // The SURFACE the message arrived on, which is also
68
+ // the address a reply goes back to.
69
+ //
70
+ // It was hardcoded `"user"`, which answered the wrong
71
+ // question: every other channel value (`telegram:8199`,
72
+ // `discord:…`) names a line, not a person, and the tag
73
+ // already says `from="user"`. So the rendered turn read
74
+ // `<text from="user" channel="user">` — the same fact
75
+ // twice, and no way for a second surface to identify
76
+ // itself.
77
+ //
78
+ // Named by the caller because the kernel cannot know
79
+ // which surface it is embedded in. `terminal` is the
80
+ // default for a caller that says nothing, which a
81
+ // direct `request()` effectively is.
82
+ channel: input.channel ?? "terminal",
66
83
  content,
67
84
  })
68
85
  yield entry
@@ -169,11 +169,87 @@ export function Scheduler(opts: SchedulerOpts) {
169
169
  const invocation = Invocation({ session: opts.session, reserve, release, runWake, interrupt })
170
170
  const continuous = Continuous({ session: opts.session, reserve, release, runWake })
171
171
 
172
+ /**
173
+ * Wake an invocation cognet when the WORLD reaches it — the trigger that
174
+ * makes `mode: "invocation"` mean what its docstring says ("invoked once
175
+ * per admitted stimulus arrival") for a stimulus nobody called in.
176
+ *
177
+ * Without this the only path to a wake was kernel.stream()/request(), so
178
+ * a stimulus from a sense organ (a channel module, a sensor) queued and
179
+ * waited for a caller that never came: the message landed in the log and
180
+ * the agent never thought about it. A body has no caller by definition.
181
+ *
182
+ * Three gates, and each rejects for its own reason:
183
+ *
184
+ * MODE — continuous cognets own their clock (a cognet plugin drives
185
+ * kernel.wake()); waking them here would be the runtime asserting a
186
+ * rhythm it cannot know, which continuous.ts exists to prevent.
187
+ *
188
+ * PROVENANCE — a stimulus committed BY a wake is that wake's own echo.
189
+ * Waking on it is an infinite loop: the brain hears itself and thinks
190
+ * again, forever. runStorage answers this exactly — anything ingested
191
+ * inside a wake carries that wake's async context.
192
+ *
193
+ * MASK — `wakeOn`, when the cognet declares one. Absent means wake on
194
+ * everything, which is the right default for a conversational brain
195
+ * and wrong for one that only cares about a single channel.
196
+ *
197
+ * Contention is NOT a gate: an invocation cognet is one conversation, so
198
+ * a stimulus arriving mid-wake is dropped by reserve() throwing
199
+ * RUN_IN_PROGRESS. That is correct — it stays on the queue and the
200
+ * running wake's own drain picks it up.
201
+ */
202
+ function onStimulus(entry: AxonStimulusEntry): void {
203
+ if (!cognet || cognet.mode.kind !== "invocation") return
204
+
205
+ // The brain's own echo — never wake on it.
206
+ if (runStorage.getStore()) return
207
+
208
+ const mask = cognet.wakeOn
209
+ if (mask && !mask.includes(entry.type)) return
210
+
211
+ let wire: ReturnType<typeof invocation.stream>
212
+ try {
213
+ wire = invocation.stream()
214
+ } catch {
215
+ // RUN_IN_PROGRESS: a wake is already running and will drain this
216
+ // stimulus itself. Nothing is lost, so nothing to report.
217
+ return
218
+ }
219
+
220
+ // The wire MUST be consumed to completion or its reservation leaks
221
+ // (runWake's finally lives inside the generator). Detached because
222
+ // no caller is waiting — a sensation is not a question. Entries
223
+ // commit as they are produced.
224
+ void (async () => {
225
+ for await (const _entry of wire.stream) {
226
+ // nothing to collect
227
+ }
228
+ })().catch(() => {
229
+ // Already durable as kernel:run:failed by the time it lands here.
230
+ })
231
+ }
232
+
233
+ // Stimuli reach the bus on every ingest (durable and transient alike —
234
+ // session.ts forwards both), so this is the arrival signal without
235
+ // threading a second callback through the session's queue. Subscribed
236
+ // for the scheduler's lifetime: onStimulus itself gates on whether a
237
+ // cognet is attached and what mode it is in.
238
+ const unsubscribe = opts.bus.onAny((event, payload) => {
239
+ if (!event.startsWith("cognet:stimulus:")) return
240
+ onStimulus(payload as AxonStimulusEntry)
241
+ })
242
+
172
243
  return {
173
244
  get loaded() {
174
245
  return cognet !== null
175
246
  },
176
247
 
248
+ /** Drop the bus subscription — run when the kernel shuts down. */
249
+ dispose() {
250
+ unsubscribe()
251
+ },
252
+
177
253
  /** register the loaded cognet — the kernel runs load(abi) first */
178
254
  attach(next: KernelCognet) {
179
255
  cognet = next