@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 +8 -8
- package/src/capsule.ts +111 -4
- package/src/contracts.ts +8 -0
- package/src/engine.ts +529 -51
- package/src/kernel.ts +146 -13
- package/src/scheduler/invocation.ts +18 -1
- package/src/scheduler/scheduler.ts +76 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
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.
|
|
19
|
-
"@arcforge/engines": "2.0.
|
|
20
|
-
"@arcforge/err": "2.0.
|
|
21
|
-
"@arcforge/session": "2.0.
|
|
22
|
-
"@arcforge/types": "2.0.
|
|
23
|
-
"@arclabs/cloud": "2.0.
|
|
24
|
-
"@axon/capsule": "2.0.
|
|
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
|
-
|
|
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
|
-
/**
|
|
22
|
-
|
|
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
|
|
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
|
|
46
|
-
|
|
47
|
-
|
|
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.
|
|
57
|
-
*
|
|
58
|
-
*
|
|
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(
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
|
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
|
-
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
// `<
|
|
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(
|
|
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 "
|
|
774
|
+
case "text:open":
|
|
379
775
|
lang = block.lang
|
|
380
776
|
break
|
|
381
777
|
|
|
382
|
-
case "
|
|
383
|
-
|
|
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 "
|
|
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
|
-
|
|
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
|
-
//
|
|
443
|
-
//
|
|
444
|
-
//
|
|
445
|
-
|
|
446
|
-
|
|
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 <
|
|
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
|
|
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
|
-
*
|
|
238
|
-
*
|
|
239
|
-
*
|
|
240
|
-
* down the runtime it
|
|
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:
|
|
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: "
|
|
363
|
-
content:
|
|
364
|
-
...(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
|
-
|
|
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
|