@ghostmind-dev/agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghostmind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @ghostmind-dev/agent
+
+The engine every app builds its own agent from. The loop, and everything it needs to run safely:
+
+- a worker model that calls tools, through OpenRouter;
+- **Jev**, a calibrated decision model, guiding the worker at checkpoints;
+- budgets, including a USD cap;
+- `go` / `pause` / `stop` hooks;
+- an append-only event log.
+
+It is a **library**: import it, give it tools, run it. No server, no service, no connection to call. Zero runtime dependencies, Node ≥ 22.18, one credential: `OPENROUTER_API_KEY`.
+
+```
+            @ghostmind-dev/agent   (engine: loop, model + Jev, guide, budget, hooks, events)
+             /            |              \
+      an app's agent   another app's   an ensemble work node
+```
+
+**Share the engine, not the agent.** What makes an agent *yours* is its tools, prompts, memory and approvals, and each app keeps those. What every app needs, and what is hard to get right, is the loop: the guards that stop a model looping, stalling, inventing tool calls or overspending. That lives here once.
+
+## Quick start
+
+```ts
+import { openrouter, runAgent, type AgentTool } from '@ghostmind-dev/agent';
+
+const weather: AgentTool = {
+  name: 'get_weather',
+  description: 'The forecast for a city today.',
+  parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+  run: async ({ city }) => ({ city, forecast: 'rain, 12°C' }),
+};
+
+const result = await runAgent({
+  provider: openrouter({ model: '<an OpenRouter model id>' }),
+  task: { goal: 'Will it rain in Montreal?', expectation: 'One sentence.' },
+  toolsets: [{ name: 'weather', description: 'Forecasts.', tools: [weather] }],
+  budget: { maxUsd: 0.05 },
+});
+// result: { status, reason, answer, steps, toolCalls, cost, messages }
+```
+
+`npm run example` runs [`examples/two-tools.mts`](examples/two-tools.mts): a read tool, a write tool that asks for approval, and the event log. By default it uses a scripted model and spends $0. Add `-- --live <model-id>` for a real run.
+
+## The loop
+
+Ported from a production agent's loop, where each guard answers a failure its evaluation found:
+
+| Guard | What it prevents |
+|---|---|
+| Every tool offered at every step | A router that offered only some tools made the model say "I have no tool for that" |
+| Step cap; the last step answers with tools visible but not callable (`toolChoice: 'none'`) | Running forever; removing the tools instead makes models write tool markup as text |
+| Tool-call cap | Endless lookups |
+| USD cap (`budget.maxUsd`) | Overspending. Ends with status `limit` and a reason naming the figure |
+| A transient reminder at the end of the context | Weak models losing the thread (sent once, never kept) |
+| Leaked tool-call markup read back into real calls | Models that write their calls as text (DSML, `<invoke>`, GLM `arg_key`) |
+| Empty reply sent back twice, then reported | Blank answers |
+| Identical reads run once (sorted-key JSON) | Doom loops |
+| A "you may have enough" note every few reads | Over-searching |
+| Long results capped | Context blow-up |
+| Guide reads (skills) spend no tool call and give the step back | Preparation eating the budget |
+| A declined change ends the run on the person's move | Retrying what the person refused |
+
+Statuses: `done`, `needs_person`, `unfinished`, `limit`, `stopped`, `paused`, `greeted`, `chatted`, with `reason` saying why whenever it isn't obvious.
+
+## Jev: the decider and the guide
+
+Two models, two jobs. The **worker** writes, plans and calls tools. **Jev** (TypeSafe's System One model, reached through OpenRouter's `/systemone`) never writes. It answers typed questions with calibrated probabilities (yes/no, one of N, a score), in well under a second, for about $0.00002. Probabilities, not prose, so the worker can't talk it into agreeing.
+
+Because it is that cheap, the loop asks Jev wherever a step is a judgement rather than a generation:
+
+- **Opening:** is there a task at all? A greeting gets the app's welcome and a thank-you gets one short reply, neither paying for the loop.
+- **Skills:** which guides, if any, the task needs. One choice question covers every skill.
+- **`ask_jev`:** offered to the worker at every step, for "which existing option fits", "is this a duplicate", "how relevant".
+- **The guide:** checkpoints the harness asks itself, so a weaker model gets through uncertainty. The model doesn't have to think of asking.
+
+### The guide
+
+| Checkpoint | Question (atomic; the state is the task and the latest step only) | Low probability → |
+|---|---|---|
+| `after_tool` | Does this result move toward the request? | A steer rides with the next call |
+| `before_write` | Is this change something the request asks for? | Held back **once**, with the doubt; made again, it goes on to approval |
+| `before_answer` | Does this answer respond to the request? | Sent back (a nudge) |
+| `hesitation` (empty reply, repeated call, leaked markup) | Which next step helps most? (choice over the tools + "answer now") | A steer naming the step |
+
+The guide **steers; it does not overrule.** Every question avoids Jev's documented weaknesses: counting, numbers, dates, long context and multi-hop reasoning. The verdict node this engine's source loop dropped judged a whole transcript and asked whether "every fact and number" was supported. That combination is Jev's weak spot, and the probable reason the node was dropped.
+
+**Guidance follows the model.** `guidance: 'auto'` is the default:
+
+1. **Start** from what the provider knows of the model (`provider.card()`, which reads OpenRouter's live catalogue: price, context size, tool support). Expensive models start `light`; cheap or small ones start `close`.
+2. **Adapt** within the run. Repeated low probabilities tighten the level; a streak of confident passes loosens it. Every change is a `guidance` event.
+3. **Learn** across runs: a per-model profile (`guide.profiles`, e.g. `memoryProfiles()` or `fileProfiles(path)`) records how often Jev corrected the model and whether corrected runs still succeeded. After three runs, the profile sets the next run's starting level.
+
+Levels: `off` · `light` (before writes and answers) · `normal` (+ every 3rd tool result, hesitation) · `close` (every tool result). A named level is fixed. A number `N` checks after every Nth result. Every checkpoint is a `checkpoint` event (question, probability, action, level), and its cost counts toward the budget. None run past the USD cap.
+
+`npm run bench` compares guidance `off` against `close` on the same scenarios. The default dry run proves the wiring for $0. `node bench/guidance.mts --live <model-id> --runs N` is the real measure, and it spends money.
+
+App-owned variants of the same idea: `jevStopCheck(provider, checks)` and `jevToolGate(provider, options)` put Jev behind the hooks.
+
+## Hooks
+
+```ts
+hooks: {
+  beforeStep(ctx)    // go · pause (→ 'paused') · stop (→ 'stopped')
+  toolGate(ctx)      // go · { verdict: 'go', args } · { verdict: 'go', result } · pause · stop
+  rewriteOutput(ctx) // the text the model sees instead (redact, trim, annotate)
+  stopCheck(ctx)     // nothing/stop = accept · { verdict: 'go', reason } = back to work · pause = needs_person
+}
+```
+
+The same `go | pause | stop` vocabulary as ensemble's `guard(step)`, so one supervisor speaks both. `combineHooks(...)` stacks several (the first objection wins; rewrites chain). A paused run resumes by running again with `result.messages` as `history`: every tool call in it has a result.
+
+## Events
+
+`onEvent` streams events; `log: eventLog()` keeps them. The rule: **if the model saw it, it is logged.** Every message added to the model's context (the system prompt, the task, each tool result as the model received it, and the transient reminders and steers that never stay in `messages`) is a `context` event. Entries are numbered, timestamped, deep-copied and frozen. `toJSONL()` and `since(seq)` are for tailing; `onAppend` writes them anywhere.
+
+## The seams: what an app provides
+
+| Seam | What it is |
+|---|---|
+| `provider: ModelProvider` | `chat` (the worker), optional `decide` (Jev), optional `card` (what's known of a model). `openrouter()` in an app, `scriptedModel()` in a test |
+| `toolsets`, `alwaysTools` | `AgentTool`s. A tool that changes something has `write.describe(args)`, the sentence the person approves. `foldTools()` folds many actions into one `{ action, args }` tool. `mcpToolset(session)` turns an MCP session (ensemble's `connect()` shape) into tools |
+| `prompts: Partial<PromptPack>` | Every word the engine says: system rules, reminder, answer-now, nudges, opening paths |
+| `memory: MemoryStore` | `recall()` facts into the system prompt (remembering is the app's own tool) |
+| `session: { store: SessionStore, id }` or `history` | Earlier turns |
+| `approve(request)` | Asks the person. Without it, every change is refused |
+| `skills: SkillSource` | `inlineSkills([...])` or `dirSkills(dir)` (Agent Skills format). Jev picks; `use_skill` and `read_skill_file` load |
+| `postProcessors` | Transform the final answer (an app's own link repair, redaction) |
+| `subagentTool(spec)` | A whole agent as one tool: isolated transcript, cost rolled up into the parent's cap |
+
+## The boundary rule
+
+`src/` never names an app: no app database, no app link format, no app wording in prompts. If a line of the engine would only make sense for one app, it belongs behind a seam. `test/boundary.test.mts` enforces it, along with zero runtime dependencies and no hardcoded model ids. Jev's `jev-latest` alias is the one default.
+
+## Development
+
+```
+npm test            # all suites, offline, $0 (builds first)
+npm run typecheck
+npm run example     # the two-tool agent, scripted
+npm run bench       # guidance off vs close, dry run
+```

package/dist/budget.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Budgets — every run is bounded, and says which bound it hit.
+ *
+ * Steps, tool calls and nudges came from Potion's Talk, each tuned against a failure seen in its
+ * evaluation. The USD cap is new: Talk had none, though it already summed what each call cost —
+ * OpenRouter bills `usage.cost` per call, worker and Jev alike, so a cap is a comparison, not an
+ * estimate. A run that hits it ends with status 'limit' and a reason naming the figure, never a
+ * silent truncation.
+ */
+export interface Budget {
+    /** Worker turns. Default 8. The last one always answers, with tools shown but not callable. */
+    maxSteps?: number;
+    /** Tool calls across the run. Default 12. Once spent, the next step answers with what it has. */
+    maxToolCalls?: number;
+    /** How many times a stopCheck may send the model back. Default 2. */
+    maxNudges?: number;
+    /** USD across the run (worker, decisions, and whatever tools report through `spend`). Default: none. */
+    maxUsd?: number;
+    /** Extra steps granted by guide tools (reading a skill is preparation, not work). Default 4. */
+    guideSteps?: number;
+    /** Every this many reads, a tool result carries a "you may have enough — answer" note. Default 4. */
+    readNudgeAt?: number;
+    /** A tool result longer than this is truncated before the model sees it. Default 12,000 chars. */
+    resultCap?: number;
+}
+export declare const DEFAULT_BUDGET: {
+    maxSteps: number;
+    maxToolCalls: number;
+    maxNudges: number;
+    maxUsd: number;
+    guideSteps: number;
+    readNudgeAt: number;
+    resultCap: number;
+};
+export type Limits = Required<Budget>;
+export declare function limits(budget?: Budget): Limits;
+/** The reason a run must stop for money, or null while there is budget left. */
+export declare function overBudget(spent: number, maxUsd: number): string | null;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,MAAM;IACrB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc;;;;;;;;CAQC,CAAC;AAE7B,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEtC,wBAAgB,MAAM,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM,CAIlD;AAKD,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvE"}

package/dist/budget.js

@@ -0,0 +1,34 @@
+/**
+ * Budgets — every run is bounded, and says which bound it hit.
+ *
+ * Steps, tool calls and nudges came from Potion's Talk, each tuned against a failure seen in its
+ * evaluation. The USD cap is new: Talk had none, though it already summed what each call cost —
+ * OpenRouter bills `usage.cost` per call, worker and Jev alike, so a cap is a comparison, not an
+ * estimate. A run that hits it ends with status 'limit' and a reason naming the figure, never a
+ * silent truncation.
+ */
+export const DEFAULT_BUDGET = {
+    maxSteps: 8,
+    maxToolCalls: 12,
+    maxNudges: 2,
+    maxUsd: Infinity,
+    guideSteps: 4,
+    readNudgeAt: 4,
+    resultCap: 12_000,
+};
+export function limits(budget = {}) {
+    const out = { ...DEFAULT_BUDGET };
+    for (const [k, v] of Object.entries(budget))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Money is compared in whole micro-dollars so float sums never stop a run a hair early or late. */
+const micro = (usd) => Math.round(usd * 1e6);
+/** The reason a run must stop for money, or null while there is budget left. */
+export function overBudget(spent, maxUsd) {
+    if (!Number.isFinite(maxUsd) || micro(spent) < micro(maxUsd))
+        return null;
+    return `Budget reached: spent $${spent.toFixed(6)} of the $${maxUsd.toFixed(6)} cap.`;
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,EAAE;IAChB,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,MAAM;CACS,CAAC;AAI7B,MAAM,UAAU,MAAM,CAAC,SAAiB,EAAE;IACxC,MAAM,GAAG,GAAG,EAAE,GAAG,cAAc,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAyC;QAAE,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACrH,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oGAAoG;AACpG,MAAM,KAAK,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;AAErD,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,MAAc;IACtD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,0BAA0B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AACxF,CAAC"}

package/dist/consult.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Two ways for the worker to ask for help mid-task.
+ *
+ *   ask_jev   — Jev, the decision model: a yes/no (probability), a pick from options (with every
+ *               option's probability), or a score on a scale. Fast, calibrated, a fraction of a
+ *               cent. Meant to be offered at EVERY step (`alwaysTools`): whenever an answer is a
+ *               judgement, not prose — which existing option fits, is this a duplicate, how relevant.
+ *   ask_model — another model, consulted in plain text with no tools. Only from an allowlist the app
+ *               gives, because which models a person may spend on is the app's decision.
+ *
+ * What each costs is reported through the tool context's `spend`, so it counts toward the run's
+ * total and its USD cap.
+ */
+import type { ModelProvider } from './model.ts';
+import { type AgentTool } from './tools.ts';
+export declare function askJevTool(model: ModelProvider): AgentTool;
+export interface AskModelOptions {
+    /** The models that may be consulted: id → label. */
+    models: Record<string, string>;
+    /** The consulted model's system line. */
+    system?: string;
+    maxTokens?: number;
+}
+export declare function askModelTool(model: ModelProvider, options: AskModelOptions): AgentTool;
+//# sourceMappingURL=consult.d.ts.map

package/dist/consult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consult.d.ts","sourceRoot":"","sources":["../src/consult.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CA6C1D;AAED,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,SAAS,CAsBtF"}

package/dist/consult.js

@@ -0,0 +1,80 @@
+import { forgivingArgs } from "./tools.js";
+export function askJevTool(model) {
+    if (!model.decide)
+        throw new Error('ask_jev needs a ModelProvider with decide().');
+    const decide = model.decide.bind(model);
+    return {
+        name: 'ask_jev',
+        description: 'Ask Jev, a fast decision model, one typed question about some state and get probabilities back (no prose). kind "yes_no": the probability of yes. kind "choice": pick one of `options` (an array of labels, or { label: description }), with every option\'s probability — use it to match a phrase to what EXISTS instead of guessing. kind "score": a position on `options` read as ordered levels, low to high. Use it freely whenever the answer is a judgement.',
+        parameters: {
+            type: 'object',
+            properties: {
+                question: { type: 'string', description: 'The question, referring to fields of `state` in backticks, e.g. "Which of `options` fits `item.title`?"' },
+                state: { description: 'What Jev judges: text or an object' },
+                kind: { type: 'string', enum: ['yes_no', 'choice', 'score'] },
+                options: { description: 'For choice / score: labels (array) or { label: description }' },
+            },
+            required: ['question', 'state', 'kind'],
+        },
+        run: async (args, ctx) => {
+            // Models often send `options` and `state` as JSON text; read them as what they mean.
+            const a = forgivingArgs(args);
+            const kind = String(a.kind);
+            const raw = a.options;
+            const labels = Array.isArray(raw)
+                ? Object.fromEntries(raw.map(o => [String(o), null]))
+                : raw && typeof raw === 'object'
+                    ? Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, v == null ? null : String(v)]))
+                    : {};
+            let q;
+            if (kind === 'yes_no')
+                q = { type: 'noul', instructions: String(a.question) };
+            else if (kind === 'choice') {
+                if (Object.keys(labels).length < 2)
+                    throw new Error('A choice needs at least two options');
+                q = { type: 'choice', instructions: String(a.question), criteria: labels };
+            }
+            else if (kind === 'score') {
+                const levels = Object.entries(labels).map(([k, v]) => (v ? `${k}: ${v}` : k));
+                if (levels.length < 2)
+                    throw new Error('A score needs at least two ordered levels in `options`');
+                q = { type: 'score', instructions: String(a.question), criteria: levels.slice(0, 10) };
+            }
+            else
+                throw new Error('kind must be yes_no, choice or score');
+            const { answers, cost } = await decide(a.state ?? '', { q }, ctx.signal);
+            ctx.spend(cost);
+            const ans = answers.q;
+            if (ans.type === 'noul')
+                return { yes: Number(ans.noul.toFixed(3)) };
+            if (ans.type === 'choice')
+                return { choice: ans.choice, confidence: Number(ans.confidence.toFixed(3)), probabilities: ans.probabilities };
+            return { score: Number(ans.score.toFixed(3)), confidence: Number(ans.confidence.toFixed(3)), levels: ans.legend, probabilities: ans.probabilities };
+        },
+    };
+}
+export function askModelTool(model, options) {
+    const ids = Object.keys(options.models);
+    return {
+        name: 'ask_model',
+        description: `Send one self-contained prompt to another model and get its text answer (it has no tools and sees nothing else). Only when the person asked for that model. Models: ${ids.map(id => `${id} (${options.models[id]})`).join(', ')}.`,
+        parameters: { type: 'object', properties: { model: { type: 'string', enum: ids }, prompt: { type: 'string' } }, required: ['model', 'prompt'] },
+        run: async (a, ctx) => {
+            const id = String(a.model ?? '');
+            if (!ids.includes(id))
+                throw new Error(`"${id}" is not offered. Models: ${ids.join(', ')}`);
+            const reply = await model.chat({
+                model: id,
+                maxTokens: options.maxTokens ?? 2000,
+                signal: ctx.signal,
+                messages: [
+                    { role: 'system', content: options.system ?? "You are consulted by another agent on a person's behalf. Answer the prompt directly and concisely." },
+                    { role: 'user', content: String(a.prompt ?? '') },
+                ],
+            });
+            ctx.spend(reply.cost);
+            return { model: id, answer: reply.message.content ?? '' };
+        },
+    };
+}
+//# sourceMappingURL=consult.js.map

package/dist/consult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consult.js","sourceRoot":"","sources":["../src/consult.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Events — what happened in a run, and the log that keeps it.
+ *
+ * The rule: IF THE MODEL SAW IT, IT IS LOGGED. Every message added to the model's context emits a
+ * `context` event — the system prompt, the task, each tool result as the model received it (after
+ * truncation and rewriting), and the transient lines (reminders, "answer now") that are sent once and
+ * never stay in the conversation. A run can therefore be replayed and audited from its log alone,
+ * which is not true of `messages`, where transient lines leave no trace.
+ *
+ * The log is append-only in the strict sense: an entry is a deep copy, frozen, numbered in order.
+ * Nothing that happens later in the run — a message mutated, a result rewritten — can change what
+ * was recorded.
+ */
+import type { ChatMessage } from './model.ts';
+import type { AgentResult, AgentTask } from './seams.ts';
+import type { Verdict } from './hooks.ts';
+import type { Checkpoint, GuidanceLevel } from './guide.ts';
+export type AgentEvent = {
+    type: 'run_start';
+    task: AgentTask;
+    model: string | null;
+} | {
+    type: 'context';
+    message: ChatMessage;
+    transient: boolean;
+} | {
+    type: 'opening';
+    path: 'task' | 'greeting' | 'small_talk';
+    confidence: number;
+} | {
+    type: 'skills';
+    names: string[];
+} | {
+    type: 'step';
+    step: number;
+    answerNow: boolean;
+} | {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'message';
+    text: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'approval';
+    id: string;
+    tool: string;
+    summary: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'approval_result';
+    id: string;
+    approved: boolean;
+} | {
+    type: 'tool_result';
+    id: string;
+    name: string;
+    ok: boolean;
+    result: string;
+} | {
+    type: 'hook';
+    hook: 'beforeStep' | 'toolGate' | 'stopCheck';
+    verdict: Verdict;
+    reason: string | null;
+} | {
+    type: 'nudge';
+    reason: string;
+} | {
+    type: 'spend';
+    usd: number;
+    total: number;
+    on: string;
+}
+/** A Jev checkpoint the guide asked: the question, the probability (or chosen step) and what the loop did. */
+ | {
+    type: 'checkpoint';
+    at: Checkpoint;
+    question: string;
+    p: number | null;
+    choice?: string;
+    action: 'pass' | 'steer' | 'hold' | 'send_back' | 'none';
+    level: GuidanceLevel;
+}
+/** The guidance level was set (from: null) or changed, and why. */
+ | {
+    type: 'guidance';
+    from: GuidanceLevel | null;
+    level: GuidanceLevel;
+    reason: string;
+} | {
+    type: 'finished';
+    result: AgentResult;
+};
+export interface LoggedEvent {
+    /** 1, 2, 3… in the order they happened. */
+    seq: number;
+    /** ISO time. */
+    at: string;
+    event: AgentEvent;
+}
+export interface EventLog {
+    append(event: AgentEvent): LoggedEvent;
+    entries(): readonly LoggedEvent[];
+    /** Entries after `seq` — for a reader that tails the log. */
+    since(seq: number): readonly LoggedEvent[];
+    /** One JSON object per line. */
+    toJSONL(): string;
+}
+export interface EventLogOptions {
+    /** Called with each entry as it is appended — write it to a file, a database, a socket. */
+    onAppend?: (entry: LoggedEvent) => void;
+    now?: () => Date;
+}
+export declare function eventLog(options?: EventLogOptions): EventLog;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -0,0 +1,24 @@
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+export function eventLog(options = {}) {
+    const list = [];
+    const now = options.now ?? (() => new Date());
+    return {
+        append(event) {
+            const entry = deepFreeze({ seq: list.length + 1, at: now().toISOString(), event: structuredClone(event) });
+            list.push(entry);
+            options.onAppend?.(entry);
+            return entry;
+        },
+        entries: () => list.slice(),
+        since: seq => list.filter(e => e.seq > seq),
+        toJSONL: () => list.map(e => JSON.stringify(e)).join('\n') + (list.length ? '\n' : ''),
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAwDA,SAAS,UAAU,CAAI,KAAQ;IAC7B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAQD,MAAM,UAAU,QAAQ,CAAC,UAA2B,EAAE;IACpD,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC9C,OAAO;QACL,MAAM,CAAC,KAAK;YACV,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC3G,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjB,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;YAC1B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;QAC3B,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;QAC3C,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;KACvF,CAAC;AACJ,CAAC"}

package/dist/guide.d.ts

@@ -0,0 +1,103 @@
+import type { AgentEvent } from './events.ts';
+import type { ModelCard, ModelProvider } from './model.ts';
+import type { AgentStatus, AgentTask } from './seams.ts';
+import type { AgentTool } from './tools.ts';
+export type GuidanceLevel = 'off' | 'light' | 'normal' | 'close';
+/** 'auto' starts from the model and adapts; a named level is fixed; a number N checks after every Nth tool result, fixed. */
+export type Guidance = 'auto' | GuidanceLevel | number;
+export type Checkpoint = 'after_tool' | 'before_write' | 'before_answer' | 'hesitation';
+export interface Thresholds {
+    /** after_tool: below this, steer. Default 0.35. */
+    onTrack: number;
+    /** before_write: below this, hold the change back once. Default 0.3. */
+    write: number;
+    /** before_answer: below this, send back. Default 0.35. */
+    answer: number;
+    /** At or above this a pass counts as confident (for loosening). Default 0.85. */
+    confident: number;
+    /** This many lows in a row tighten the level. Default 2. */
+    tightenAfter: number;
+    /** This many confident passes in a row loosen it. Default 4. */
+    loosenAfter: number;
+}
+export declare const DEFAULT_THRESHOLDS: Thresholds;
+/** What each level checks. `afterTool` is a period: every Nth tool result (0 = never). */
+export declare const LEVELS: Record<GuidanceLevel, {
+    afterTool: number;
+    beforeWrite: boolean;
+    beforeAnswer: boolean;
+    hesitation: boolean;
+}>;
+export interface GuideProfile {
+    model: string;
+    runs: number;
+    /** Runs that ended 'done'. */
+    successes: number;
+    checkpoints: number;
+    /** Checkpoints below their threshold. */
+    lows: number;
+    /** Runs where the guide steered at least once, and how many of those still ended 'done'. */
+    correctedRuns: number;
+    correctedSuccesses: number;
+    /** The level the last run ended at. */
+    lastLevel: GuidanceLevel;
+}
+export interface ProfileStore {
+    get(model: string): Promise<GuideProfile | null>;
+    put(profile: GuideProfile): Promise<void>;
+}
+export declare function memoryProfiles(): ProfileStore & {
+    profiles: Map<string, GuideProfile>;
+};
+/** Profiles in one JSON file (written atomically). Good for a CLI or a single server. */
+export declare function fileProfiles(path: string): ProfileStore;
+/**
+ * From what the catalogue says of a model. Price is the strongest cheap signal of capability a
+ * catalogue gives; a small context or no tool support tightens one more notch. Unknown → normal.
+ */
+export declare function levelFromCard(card: ModelCard | null): {
+    level: GuidanceLevel;
+    why: string;
+};
+/** From a model's history, once there is enough of it (3+ runs); null otherwise. */
+export declare function levelFromProfile(p: GuideProfile | null): {
+    level: GuidanceLevel;
+    why: string;
+} | null;
+export interface GuideOptions {
+    guidance?: Guidance;
+    thresholds?: Partial<Thresholds>;
+    profiles?: ProfileStore;
+}
+export interface GuideDeps {
+    provider: ModelProvider;
+    model: string | undefined;
+    task: AgentTask;
+    signal: AbortSignal;
+    emit(event: AgentEvent): void;
+    spend(usd: number, on: string): void;
+    /** False once the run is over its USD cap: checkpoints are skipped then. */
+    affordable(): boolean;
+}
+export interface Guide {
+    readonly level: GuidanceLevel;
+    readonly active: boolean;
+    start(): Promise<void>;
+    /** After a batch of tool results: a steer for the next call, or null. */
+    afterTools(results: {
+        tool: string;
+        args: Record<string, unknown>;
+        result: string;
+        ok: boolean;
+    }[]): Promise<string | null>;
+    /** Before a change: a held-back result to hand the model instead, or null to proceed. */
+    beforeWrite(tool: string, args: Record<string, unknown>, change: string, key: string): Promise<string | null>;
+    /** Before accepting the final answer: a reason to send it back, or null. */
+    beforeAnswer(answer: string | null): Promise<string | null>;
+    /** When the model hesitates: a steer naming the likeliest next step, or null. */
+    hesitation(why: 'empty_reply' | 'repeated_call' | 'leaked_call', last: string, tools: AgentTool[]): Promise<string | null>;
+    finish(status: AgentStatus): Promise<void>;
+}
+export declare const ANSWER_NOW = "answer_now";
+export declare function createGuide(options: GuideOptions, deps: GuideDeps): Guide;
+//# sourceMappingURL=guide.d.ts.map

package/dist/guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../src/guide.ts"],"names":[],"mappings":"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"}