@arcforge/kernel 2.0.144 → 2.0.146

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.144",
3
+ "version": "2.0.146",
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.144",
19
- "@arcforge/engines": "2.0.144",
20
- "@arcforge/err": "2.0.144",
21
- "@arcforge/session": "2.0.144",
22
- "@arcforge/types": "2.0.144",
23
- "@arclabs/cloud": "2.0.144",
24
- "@axon/capsule": "2.0.144"
18
+ "@arcforge/air": "2.0.146",
19
+ "@arcforge/engines": "2.0.146",
20
+ "@arcforge/err": "2.0.146",
21
+ "@arcforge/session": "2.0.146",
22
+ "@arcforge/types": "2.0.146",
23
+ "@arclabs/cloud": "2.0.146",
24
+ "@axon/capsule": "2.0.146"
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/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,7 +492,19 @@ export function Engine(opts: EngineOpts) {
183
492
  let streamedText = ""
184
493
 
185
494
  try {
186
- for await (const raw of selected.driver.stream(req)) {
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) {
187
508
  if (raw.type !== "done" && firstTokenAt === undefined) {
188
509
  firstTokenAt = Date.now()
189
510
  // Committed as it happens rather than folded into
@@ -206,7 +527,21 @@ export function Engine(opts: EngineOpts) {
206
527
  // (extend) from a full re-feed (which would
207
528
  // double-fire every already-streamed block).
208
529
  streamedText += raw.content
209
- 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
+ }
210
545
  break
211
546
 
212
547
  case "thinking:delta":
@@ -279,7 +614,11 @@ export function Engine(opts: EngineOpts) {
279
614
  if (req.signal?.aborted) throw abortError(req.signal)
280
615
 
281
616
  const fault = asEngineFault(error, correlation)
282
- 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
283
622
 
284
623
  if (canRetry) {
285
624
  const suggestedDelay = fault.retryAfterMs ?? RETRY_DELAYS_MS[attempt - 1] ?? RETRY_DELAYS_MS.at(-1)!
@@ -355,7 +694,7 @@ export function Engine(opts: EngineOpts) {
355
694
  // BLOCK AT ALL is another, and it does not depend on the caller having
356
695
  // asked for a shape — the protocol itself requires the reply to be
357
696
  // wrapped. Gating retries on `output` meant a model that forgot
358
- // `<template>` got exactly one attempt, its prose was discarded by the
697
+ // `<text>` got exactly one attempt, its prose was discarded by the
359
698
  // parser, and the run completed clean with an empty screen.
360
699
  const budget = call.retries ?? DEFAULT_OUTPUT_RETRIES
361
700
  let lastFault: string | undefined
@@ -364,12 +703,59 @@ export function Engine(opts: EngineOpts) {
364
703
 
365
704
  yield { type: "engine:start" }
366
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
+
367
723
  for (let attempt = 0; attempt <= budget; attempt++) {
368
- const raw = blocks(call, context)
724
+ const raw = blocks(attemptCall, context)
369
725
  let violations: readonly OutputDiagnostic[] = []
726
+ let violatingScript: string | undefined
370
727
  let spoke = false
371
728
  let acted = false
372
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
373
759
  let lang: "md" | "json" = "md"
374
760
  let group: string | null = null
375
761
  let pending: string | null = null
@@ -385,12 +771,22 @@ export function Engine(opts: EngineOpts) {
385
771
  while (!step.done) {
386
772
  const block = step.value
387
773
  switch (block.type) {
388
- case "template:open":
774
+ case "text:open":
389
775
  lang = block.lang
390
776
  break
391
777
 
392
- case "template:delta":
393
- 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()) {
394
790
  group ??= crypto.randomUUID()
395
791
  spoke = true
396
792
  events.push({ type: "engine:text", content: pending, lang, chunk: { of: group } })
@@ -398,12 +794,16 @@ export function Engine(opts: EngineOpts) {
398
794
  pending = block.content
399
795
  break
400
796
 
401
- case "template:done": {
402
- if (block.incomplete) break
797
+ case "text:done": {
798
+ if (block.incomplete) { truncated = "text"; break }
403
799
  const last = pending ?? block.content
404
800
  pending = null
405
- 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
406
805
  spoke = true
806
+ texts++
407
807
  events.push(group
408
808
  ? { type: "engine:text", content: last, lang, chunk: { of: group, final: true } }
409
809
  : { type: "engine:text", content: last, lang })
@@ -412,7 +812,7 @@ export function Engine(opts: EngineOpts) {
412
812
  }
413
813
 
414
814
  case "script:done": {
415
- if (block.incomplete) break
815
+ if (block.incomplete) { truncated = "script"; break }
416
816
  // Checked BEFORE it is reported, so a script that
417
817
  // cannot satisfy the contract is never handed to a
418
818
  // cognet that would run it.
@@ -420,10 +820,15 @@ export function Engine(opts: EngineOpts) {
420
820
  const problems = output.check(block.content)
421
821
  if (problems.length > 0) {
422
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
423
827
  break
424
828
  }
425
829
  }
426
830
  acted = true
831
+ scripts++
427
832
  events.push({ type: "engine:script", id: crypto.randomUUID(), content: block.content })
428
833
  break
429
834
  }
@@ -440,6 +845,27 @@ export function Engine(opts: EngineOpts) {
440
845
  step = await raw.next()
441
846
  }
442
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
+
443
869
  // A reply that parsed to no block is unusable, whatever it said.
444
870
  //
445
871
  // Checked separately from `violations` because it is a different
@@ -449,13 +875,54 @@ export function Engine(opts: EngineOpts) {
449
875
  // reply and the user saw a blank screen. Retrying with the excerpt
450
876
  // quoted back steers it in one attempt.
451
877
  //
452
- // `yielded` is deliberately not part of this test. A reply that
453
- // spoke or acted but forgot `<done/>` still produced something the
454
- // cognet can use, and the loop's own stop condition owns that.
455
- if (violations.length === 0 && !spoke && !acted) {
456
- 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
+ )
457
923
  lastFailure = "empty"
458
- 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)
459
926
  continue
460
927
  }
461
928
 
@@ -469,9 +936,10 @@ export function Engine(opts: EngineOpts) {
469
936
  // failed its contract is not a partial answer, it is a discarded
470
937
  // one. The diagnostic is committed so the next attempt's context
471
938
  // carries it, and the model rewrites against its own error.
472
- lastFault = describeViolations(violations)
939
+ lastFault = describeViolations(violations, violatingScript)
473
940
  lastFailure = "shape"
474
- 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)
475
943
  }
476
944
 
477
945
  // Budget exhausted. Loud, never a degraded return: a caller that
@@ -489,7 +957,7 @@ export function Engine(opts: EngineOpts) {
489
957
  type: "engine:failure",
490
958
  error: lastFailure === "empty"
491
959
  ? err("OUTPUT_EMPTY", {
492
- 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 — `
493
961
  + `its replies could not be used. Last attempt: ${lastFault}`,
494
962
  context: { attempts: budget + 1, provider: current?.name, model: call.model },
495
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({
@@ -337,7 +413,9 @@ export async function Kernel(opts: KernelOpts) {
337
413
  await session.commitEntry("cognet:action:result", {
338
414
  for: id,
339
415
  ok: result.ok,
340
- 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
+ ),
341
419
  ...(result.error ? { error: result.error } : {}),
342
420
  }, run)
343
421
  return result
@@ -366,15 +444,35 @@ export async function Kernel(opts: KernelOpts) {
366
444
  * naming a binding that was never declared). One shape, one entry type,
367
445
  * one thing for a host to recognise and hide.
368
446
  */
369
- function recordFault(
370
- fault: { code: string; message: string; excerpt?: string },
447
+ async function recordFault(
448
+ fault: { code: string; message: string; excerpt?: string; rejected?: string; attempt?: number },
371
449
  run: { runId: string } | undefined,
372
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.
373
471
  return session.commitEntry("axon:system:message", {
374
472
  type: "format-violation",
375
- lang: "txt",
376
- content: `${fault.code}: ${fault.message}`,
377
- ...(fault.excerpt ? { attributes: { excerpt: fault.excerpt } } : {}),
473
+ lang: "md",
474
+ content: fault.message,
475
+ attributes: { code: fault.code, ...(fault.excerpt ? { excerpt: fault.excerpt } : {}) },
378
476
  }, run)
379
477
  }
380
478
 
@@ -407,6 +505,23 @@ export async function Kernel(opts: KernelOpts) {
407
505
  yield event
408
506
  throw event.error
409
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
+
410
525
  yield event
411
526
  }
412
527
  }
@@ -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