@ghostmind-dev/agent 0.1.0

package/dist/guide.js

@@ -0,0 +1,268 @@
+/**
+ * The guide — Jev asking "is this going the right way?" so a weaker model gets through uncertainty.
+ *
+ * A strong worker rarely needs help; a cheap one often does, and a calibrated yes/no costs about
+ * $0.00002. So the HARNESS asks Jev at fixed checkpoints — not only when the model thinks to call
+ * `ask_jev` — and turns the probability into a move, in code:
+ *
+ *   after_tool    "does this result move toward the request?"       low → a transient steer
+ *   before_write  "is this change what the person asked for?"        low → the call is held back once,
+ *                                                                          with the doubt, before approval
+ *   before_answer "does this answer respond to the request?"         low → sent back (a nudge)
+ *   hesitation    (an empty reply, a repeated call, leaked markup)   a choice over the tools + "answer
+ *                 "which next step moves the request forward?"             now" → a transient steer naming it
+ *
+ * The guide STEERS; it does not overrule. A held-back change goes through if the model makes it
+ * again, and a person still approves it. That is the lesson of the verdict node Potion's Talk dropped
+ * before its first commit ("Pi — the model decides; no second judge"): it judged the WHOLE transcript
+ * and asked whether every fact and number was supported, which is exactly where Jev's documented
+ * jaggedness lies (counting and numbers, long context, multi-hop). Here every question is atomic,
+ * the state is the task and the latest step only, and nothing asks Jev to count or compare figures.
+ *
+ * How closely it watches follows the model (`guidance`, default 'auto'):
+ *   1. a starting level from what the provider knows of the model (`card()`: price, context, tools —
+ *      the live OpenRouter catalogue, never a list of ids);
+ *   2. adapted within the run from evidence: repeated low probabilities tighten it, a run of confident
+ *      passes loosens it — each change an event;
+ *   3. learned across runs: a per-model profile (how often Jev corrected it, and whether corrected runs
+ *      still succeeded) in a pluggable store, which seeds the next run's level.
+ * Every checkpoint is an event with its question, probability and action, and its cost is spent
+ * against the run's budget, so the value of guidance can be measured (see bench/).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const DEFAULT_THRESHOLDS = { onTrack: 0.35, write: 0.3, answer: 0.35, confident: 0.85, tightenAfter: 2, loosenAfter: 4 };
+const ORDER = ['off', 'light', 'normal', 'close'];
+/** What each level checks. `afterTool` is a period: every Nth tool result (0 = never). */
+export const LEVELS = {
+    off: { afterTool: 0, beforeWrite: false, beforeAnswer: false, hesitation: false },
+    light: { afterTool: 0, beforeWrite: true, beforeAnswer: true, hesitation: false },
+    normal: { afterTool: 3, beforeWrite: true, beforeAnswer: true, hesitation: true },
+    close: { afterTool: 1, beforeWrite: true, beforeAnswer: true, hesitation: true },
+};
+export function memoryProfiles() {
+    const profiles = new Map();
+    return { profiles, get: async (m) => (profiles.has(m) ? { ...profiles.get(m) } : null), put: async (p) => void profiles.set(p.model, { ...p }) };
+}
+/** Profiles in one JSON file (written atomically). Good for a CLI or a single server. */
+export function fileProfiles(path) {
+    const read = () => {
+        try {
+            return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {};
+        }
+        catch {
+            return {};
+        }
+    };
+    return {
+        get: async (m) => read()[m] ?? null,
+        put: async (p) => {
+            const all = read();
+            all[p.model] = p;
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(`${path}.tmp`, JSON.stringify(all, null, 2));
+            renameSync(`${path}.tmp`, path);
+        },
+    };
+}
+// ── the starting level ──────────────────────────────────────────────────────
+/**
+ * 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 function levelFromCard(card) {
+    if (!card)
+        return { level: 'normal', why: 'nothing known about the model' };
+    const perMillion = card.completion * 1e6;
+    let i = perMillion >= 10 ? 1 : perMillion >= 2 ? 2 : 3;
+    const weak = [];
+    if (!card.tools)
+        weak.push('no tool support');
+    if (card.context > 0 && card.context < 64_000)
+        weak.push(`${card.context} context`);
+    if (weak.length)
+        i = Math.min(3, i + 1);
+    const level = ORDER[i];
+    return { level, why: `$${perMillion.toFixed(2)}/M output${weak.length ? `, ${weak.join(', ')}` : ''}` };
+}
+/** From a model's history, once there is enough of it (3+ runs); null otherwise. */
+export function levelFromProfile(p) {
+    if (!p || p.runs < 3 || p.checkpoints === 0)
+        return null;
+    const lowRate = p.lows / p.checkpoints;
+    const success = p.successes / p.runs;
+    const why = `${p.runs} runs, ${Math.round(lowRate * 100)}% low checkpoints, ${Math.round(success * 100)}% done`;
+    if (lowRate > 0.3 || success < 0.6)
+        return { level: 'close', why };
+    if (lowRate > 0.12)
+        return { level: 'normal', why };
+    if (success >= 0.8)
+        return { level: 'light', why };
+    return { level: 'normal', why };
+}
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n)}…` : s);
+const firstSentence = (d) => clip(d.trim().split(/(?<=\.)\s/)[0] ?? d, 200);
+const callText = (tool, args) => clip(`${tool}(${JSON.stringify(args)})`, 400);
+export const ANSWER_NOW = 'answer_now';
+export function createGuide(options, deps) {
+    const T = { ...DEFAULT_THRESHOLDS, ...options.thresholds };
+    const setting = options.guidance ?? 'auto';
+    const decide = deps.provider.decide?.bind(deps.provider);
+    const adaptive = setting === 'auto';
+    const period = typeof setting === 'number' ? Math.max(1, Math.round(setting)) : null;
+    let level = typeof setting === 'number' ? 'close' : setting === 'auto' ? 'normal' : setting;
+    const active = () => !!decide && level !== 'off';
+    let results = 0;
+    let lowStreak = 0;
+    let confidentStreak = 0;
+    let checkpoints = 0;
+    let lows = 0;
+    let corrections = 0;
+    const heldBack = new Set();
+    const setLevel = (next, reason) => {
+        if (next === level)
+            return;
+        deps.emit({ type: 'guidance', from: level, level: next, reason });
+        level = next;
+    };
+    /** Record a probability: counts, streaks, and (auto) tightening or loosening. */
+    const observe = (p, threshold) => {
+        checkpoints++;
+        if (p < threshold) {
+            lows++;
+            lowStreak++;
+            confidentStreak = 0;
+            if (adaptive && lowStreak >= T.tightenAfter && level !== 'close') {
+                setLevel(ORDER[ORDER.indexOf(level) + 1], `${lowStreak} low checkpoints in a row`);
+                lowStreak = 0;
+            }
+        }
+        else {
+            lowStreak = 0;
+            confidentStreak = p >= T.confident ? confidentStreak + 1 : 0;
+            if (adaptive && confidentStreak >= T.loosenAfter && ORDER.indexOf(level) > 1) {
+                setLevel(ORDER[ORDER.indexOf(level) - 1], `${confidentStreak} confident checkpoints in a row`);
+                confidentStreak = 0;
+            }
+        }
+    };
+    const ask = async (state, questions) => {
+        if (!decide || !deps.affordable() || deps.signal.aborted)
+            return null;
+        try {
+            const reply = await decide(state, questions, deps.signal);
+            deps.spend(reply.cost, 'guide');
+            return reply.answers;
+        }
+        catch {
+            return null; // No answer is never read as a verdict.
+        }
+    };
+    const yesNo = async (at, question, state, threshold, lowAction) => {
+        const answers = await ask(state, { q: { type: 'noul', instructions: question } });
+        const a = answers?.q;
+        if (!a || a.type !== 'noul') {
+            deps.emit({ type: 'checkpoint', at, question, p: null, action: 'none', level });
+            return null;
+        }
+        const low = a.noul < threshold;
+        deps.emit({ type: 'checkpoint', at, question, p: a.noul, action: low ? lowAction : 'pass', level });
+        observe(a.noul, threshold);
+        if (low)
+            corrections++;
+        return { p: a.noul, low };
+    };
+    const pct = (p) => `${Math.round(p * 100)}%`;
+    return {
+        get level() {
+            return level;
+        },
+        get active() {
+            return active();
+        },
+        async start() {
+            if (!decide || !adaptive)
+                return;
+            const model = deps.model ?? '';
+            const learned = options.profiles && model ? levelFromProfile(await options.profiles.get(model).catch(() => null)) : null;
+            const from = learned ?? levelFromCard(model && deps.provider.card ? await deps.provider.card(model, deps.signal).catch(() => null) : null);
+            deps.emit({ type: 'guidance', from: null, level: from.level, reason: `${learned ? 'profile' : 'catalogue'}: ${from.why}` });
+            level = from.level;
+        },
+        async afterTools(batch) {
+            if (!active() || !batch.length)
+                return null;
+            const every = period ?? LEVELS[level].afterTool;
+            const due = batch.filter(() => every > 0 && ++results % every === 0);
+            if (!due.length)
+                return null;
+            // Judge the last result that fell due: the latest step, not the transcript.
+            const last = due.at(-1);
+            const question = 'Does `result` (what `call` returned) move the agent closer to doing what `goal` asks?';
+            const out = await yesNo('after_tool', question, { goal: clip(deps.task.goal, 600), call: callText(last.tool, last.args), result: clip(last.result, 1500) }, T.onTrack, 'steer');
+            if (!out?.low)
+                return null;
+            return `Guide (Jev, ${pct(out.p)} on track): the last result may not move toward the request "${clip(deps.task.goal, 200)}". Before the next call, reconsider: another tool, other arguments, or answering with what you have.`;
+        },
+        async beforeWrite(tool, args, change, key) {
+            if (!active() || !LEVELS[level].beforeWrite || heldBack.has(key))
+                return null;
+            const question = 'Is `change` something `goal` asks for?';
+            const out = await yesNo('before_write', question, { goal: clip(deps.task.goal, 600), change: clip(change, 400), call: callText(tool, args) }, T.write, 'hold');
+            if (!out?.low)
+                return null;
+            // Held back once: the same change made again goes on to approval.
+            heldBack.add(key);
+            return `Not run yet — Guide (Jev, ${pct(out.p)}): this change may not be what the person asked for ("${clip(deps.task.goal, 200)}"). If it is, make the same call again; otherwise choose another action or ask the person.`;
+        },
+        async beforeAnswer(answer) {
+            if (!active() || !LEVELS[level].beforeAnswer || !answer)
+                return null;
+            const question = 'Does `answer` respond to what `goal` asks for?';
+            const out = await yesNo('before_answer', question, { goal: clip(deps.task.goal, 600), expected: clip(deps.task.expectation, 400), answer: clip(answer, 2000) }, T.answer, 'send_back');
+            if (!out?.low)
+                return null;
+            return `Guide (Jev, ${pct(out.p)}): your answer may not respond to the request "${clip(deps.task.goal, 200)}". Check what was asked, fix what is missing, and reply with the corrected answer.`;
+        },
+        async hesitation(why, last, tools) {
+            if (!active() || !LEVELS[level].hesitation)
+                return null;
+            const criteria = { [ANSWER_NOW]: 'Enough is known: answer now with what the tools returned.' };
+            for (const t of tools.slice(0, 250))
+                criteria[t.name] = firstSentence(t.description);
+            const question = 'Which next step most helps do what `goal` asks, given `last`?';
+            const answers = await ask({ goal: clip(deps.task.goal, 600), last: clip(last, 1200), hesitation: why }, { q: { type: 'choice', instructions: question, criteria } });
+            const a = answers?.q;
+            if (!a || a.type !== 'choice' || !(a.choice in criteria)) {
+                deps.emit({ type: 'checkpoint', at: 'hesitation', question, p: null, action: 'none', level });
+                return null;
+            }
+            checkpoints++;
+            corrections++;
+            deps.emit({ type: 'checkpoint', at: 'hesitation', question, p: a.confidence, choice: a.choice, action: 'steer', level });
+            return a.choice === ANSWER_NOW
+                ? `Guide (Jev, ${pct(a.confidence)}): you likely have enough — answer now from what the tools returned.`
+                : `Guide (Jev, ${pct(a.confidence)}): the next step most likely to help is \`${a.choice}\`.`;
+        },
+        async finish(status) {
+            const model = deps.model;
+            if (!options.profiles || !model || !decide || checkpoints === 0)
+                return;
+            const p = (await options.profiles.get(model).catch(() => null)) ?? { model, runs: 0, successes: 0, checkpoints: 0, lows: 0, correctedRuns: 0, correctedSuccesses: 0, lastLevel: level };
+            const done = status === 'done';
+            await options.profiles
+                .put({
+                model,
+                runs: p.runs + 1,
+                successes: p.successes + (done ? 1 : 0),
+                checkpoints: p.checkpoints + checkpoints,
+                lows: p.lows + lows,
+                correctedRuns: p.correctedRuns + (corrections ? 1 : 0),
+                correctedSuccesses: p.correctedSuccesses + (corrections && done ? 1 : 0),
+                lastLevel: level,
+            })
+                .catch(() => { });
+        },
+    };
+}
+//# sourceMappingURL=guide.js.map

package/dist/guide.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hooks — where an app bends the loop without forking it.
+ *
+ * Frontier harnesses converged on the same design: a minimal kernel, with everything else as hooks
+ * at the loop's stages (Claude Code's PreToolUse / Stop, DeepSeek's pre-execute). Four stages here:
+ *
+ *   beforeStep    — before each model call        go · pause (end, 'paused') · stop (end, 'stopped')
+ *   toolGate      — before each tool call         go (optionally with rewritten args, or a result
+ *                                                 given instead of running) · pause · stop
+ *   rewriteOutput — each tool result, before the model sees it: redact, trim, annotate
+ *   stopCheck     — when the model stops          stop (accept: done) · go (send it back with the
+ *                                                 reason, counted as a nudge) · pause (needs_person)
+ *
+ * One vocabulary — go / pause / stop — on purpose: it is the same shape as ensemble's
+ * `guard(step) -> go | pause | stop`, so a supervisor that speaks one speaks both. "go" always means
+ * the run continues; "pause" means a person's move is next and the run can be resumed; "stop" ends.
+ * A hook returning nothing is "go" — except stopCheck, where nothing means no objection: the stop
+ * stands, exactly as if it had said "stop".
+ */
+import type { ChatMessage } from './model.ts';
+import type { AgentTask } from './seams.ts';
+export type Verdict = 'go' | 'pause' | 'stop';
+export interface HookDecision {
+    verdict: Verdict;
+    /** Why — logged, returned as the result's `reason`, and (for a stopCheck "go") told to the model. */
+    reason?: string;
+}
+export type HookReply = Verdict | HookDecision | void | undefined;
+type Maybe<T> = T | Promise<T>;
+export interface StepContext {
+    step: number;
+    /** USD so far. */
+    spent: number;
+    toolCalls: number;
+    nudges: number;
+    task: AgentTask;
+    /** The conversation as the model sees it. Read-only: change the run through verdicts. */
+    messages: readonly ChatMessage[];
+    /** Add USD a hook spent (a Jev decision) to the run's total and budget. */
+    spend(usd: number, on: string): void;
+}
+export interface ToolGateContext extends StepContext {
+    tool: string;
+    args: Record<string, unknown>;
+    callId: string;
+    /** The approval sentence when this call changes something, else null. */
+    change: string | null;
+}
+export interface ToolGateDecision extends HookDecision {
+    /** Run with these arguments instead. */
+    args?: Record<string, unknown>;
+    /** Do not run: hand the model this result instead (a refusal, a cached answer). */
+    result?: string;
+}
+export interface OutputContext extends StepContext {
+    tool: string;
+    args: Record<string, unknown>;
+    callId: string;
+    ok: boolean;
+    result: string;
+}
+export interface StopContext extends StepContext {
+    answer: string | null;
+}
+export interface Hooks {
+    beforeStep?(ctx: StepContext): Maybe<HookReply>;
+    toolGate?(ctx: ToolGateContext): Maybe<Verdict | ToolGateDecision | void | undefined>;
+    /** Return the text the model should see instead, or nothing to keep it. */
+    rewriteOutput?(ctx: OutputContext): Maybe<string | void | undefined>;
+    stopCheck?(ctx: StopContext): Maybe<HookReply>;
+}
+/** Any hook reply as a decision. Nothing is "go". */
+export declare function readVerdict<T extends HookDecision>(reply: Verdict | T | void | undefined): T | HookDecision;
+/**
+ * Several hook sets as one. Gates run in order and the first non-"go" wins (a rewrite of args by one
+ * gate is what the next one sees); output rewrites chain; for stopCheck the first objection wins.
+ */
+export declare function combineHooks(...sets: (Hooks | undefined)[]): Hooks;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC;AAClE,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,yFAAyF;IACzF,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,2EAA2E;IAC3E,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,KAAK;IACpB,UAAU,CAAC,CAAC,GAAG,EAAE,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IAChD,QAAQ,CAAC,CAAC,GAAG,EAAE,eAAe,GAAG,KAAK,CAAC,OAAO,GAAG,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtF,2EAA2E;IAC3E,aAAa,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrE,SAAS,CAAC,CAAC,GAAG,EAAE,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;CAChD;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,YAAY,CAI3G;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC,EAAE,GAAG,KAAK,CAsClE"}

package/dist/hooks.js

@@ -0,0 +1,56 @@
+/** Any hook reply as a decision. Nothing is "go". */
+export function readVerdict(reply) {
+    if (!reply)
+        return { verdict: 'go' };
+    if (typeof reply === 'string')
+        return { verdict: reply };
+    return reply;
+}
+/**
+ * Several hook sets as one. Gates run in order and the first non-"go" wins (a rewrite of args by one
+ * gate is what the next one sees); output rewrites chain; for stopCheck the first objection wins.
+ */
+export function combineHooks(...sets) {
+    const hooks = sets.filter((h) => !!h);
+    return {
+        async beforeStep(ctx) {
+            for (const h of hooks) {
+                const d = readVerdict(await h.beforeStep?.(ctx));
+                if (d.verdict !== 'go')
+                    return d;
+            }
+        },
+        async toolGate(ctx) {
+            let args = ctx.args;
+            let rewritten = false;
+            for (const h of hooks) {
+                const d = readVerdict(await h.toolGate?.({ ...ctx, args }));
+                if (d.verdict !== 'go' || d.result !== undefined)
+                    return { ...d, ...(rewritten && !d.args ? { args } : {}) };
+                if (d.args) {
+                    args = d.args;
+                    rewritten = true;
+                }
+            }
+            return rewritten ? { verdict: 'go', args } : undefined;
+        },
+        async rewriteOutput(ctx) {
+            let result = ctx.result;
+            for (const h of hooks) {
+                const next = await h.rewriteOutput?.({ ...ctx, result });
+                if (typeof next === 'string')
+                    result = next;
+            }
+            return result === ctx.result ? undefined : result;
+        },
+        async stopCheck(ctx) {
+            // Nothing or "stop" accepts the stop; the first objection ("go" back to work, or "pause") wins.
+            for (const h of hooks) {
+                const reply = await h.stopCheck?.(ctx);
+                if (reply && readVerdict(reply).verdict !== 'stop')
+                    return reply;
+            }
+        },
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAiFA,qDAAqD;AACrD,MAAM,UAAU,WAAW,CAAyB,KAAqC;IACvF,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAG,IAA2B;IACzD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO;QACL,KAAK,CAAC,UAAU,CAAC,GAAG;YAClB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;gBACjD,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI;oBAAE,OAAO,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,GAAG;YAChB,IAAI,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YACpB,IAAI,SAAS,GAAG,KAAK,CAAC;YACtB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,CAAqB,CAAC;gBAChF,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;oBAAE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC7G,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;oBACX,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;oBACd,SAAS,GAAG,IAAI,CAAC;gBACnB,CAAC;YACH,CAAC;YACD,OAAO,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,GAAG;YACrB,IAAI,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;gBACzD,IAAI,OAAO,IAAI,KAAK,QAAQ;oBAAE,MAAM,GAAG,IAAI,CAAC;YAC9C,CAAC;YACD,OAAO,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QACpD,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,GAAG;YACjB,gGAAgG;YAChG,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;gBACvC,IAAI,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,OAAO,KAAK,MAAM;oBAAE,OAAO,KAAK,CAAC;YACnE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @ghostmind-dev/agent — the engine every app builds its own agent from.
+ *
+ * The package is the loop and what it needs to run safely: the model seam (a worker through
+ * OpenRouter, Jev for decisions), budgets with a USD cap, go/pause/stop hooks, an append-only event
+ * log, and the seams an app fills in to make the agent its own. It is a library: import it, give it
+ * tools, run it. There is no server, no connection to call, and nothing here names an app.
+ */
+export { runAgent, subagentTool, passNode, parseLeakedCalls, leakFilter, LEAKED_CALL } from './loop.ts';
+export type { AgentOptions, SubagentSpec, DecisionNode, NodeOutcome } from './loop.ts';
+export { openrouter, modelCatalog, forgetCatalog, ModelError, OPENROUTER_URL, DEFAULT_DECISION_MODEL } from './model.ts';
+export type { ModelProvider, OpenRouterConfig, ChatMessage, AssistantMessage, ChatRequest, ChatReply, ToolCall, ToolSpec, Question, Answer, DecideReply, ModelCard, ModelErrorCode, } from './model.ts';
+export { foldTools, mcpToolset, forgivingArgs, readCall, stableJson } from './tools.ts';
+export type { AgentTool, Toolset, ToolContext, ApprovalRequest, FoldOptions, McpLike, McpToolsetOptions } from './tools.ts';
+export { readVerdict, combineHooks } from './hooks.ts';
+export type { Hooks, Verdict, HookDecision, HookReply, StepContext, ToolGateContext, ToolGateDecision, OutputContext, StopContext } from './hooks.ts';
+export { jevStopCheck, jevToolGate, ask, workLog, DEFAULT_CHECKS } from './jev.ts';
+export type { JevCheck, JevGateOptions } from './jev.ts';
+export { createGuide, levelFromCard, levelFromProfile, memoryProfiles, fileProfiles, DEFAULT_THRESHOLDS, LEVELS, ANSWER_NOW } from './guide.ts';
+export type { Guide, Guidance, GuidanceLevel, GuideOptions, GuideProfile, ProfileStore, Thresholds, Checkpoint } from './guide.ts';
+export { limits, overBudget, DEFAULT_BUDGET } from './budget.ts';
+export type { Budget, Limits } from './budget.ts';
+export { eventLog } from './events.ts';
+export type { AgentEvent, EventLog, LoggedEvent, EventLogOptions } from './events.ts';
+export { defaultPrompts, memorySessions } from './seams.ts';
+export type { AgentTask, AgentResult, AgentStatus, PromptPack, MemoryStore, SessionStore, Approve, PostProcessor, PostContext, SkillSource, SkillMeta } from './seams.ts';
+export { inlineSkills, dirSkills, pickSkills, skillsToolset, readFrontmatter, SKILL_TOOLS, NO_SKILL } from './skills.ts';
+export type { InlineSkill } from './skills.ts';
+export { askJevTool, askModelTool } from './consult.ts';
+export type { AskModelOptions } from './consult.ts';
+export { scriptedModel, firstOption } from './testing.ts';
+export type { ScriptedModel, ScriptStep, ScriptedDecide } from './testing.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxG,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzH,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,WAAW,EACX,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxF,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5H,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtJ,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACnF,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChJ,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnI,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1K,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACzH,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @ghostmind-dev/agent — the engine every app builds its own agent from.
+ *
+ * The package is the loop and what it needs to run safely: the model seam (a worker through
+ * OpenRouter, Jev for decisions), budgets with a USD cap, go/pause/stop hooks, an append-only event
+ * log, and the seams an app fills in to make the agent its own. It is a library: import it, give it
+ * tools, run it. There is no server, no connection to call, and nothing here names an app.
+ */
+export { runAgent, subagentTool, passNode, parseLeakedCalls, leakFilter, LEAKED_CALL } from "./loop.js";
+export { openrouter, modelCatalog, forgetCatalog, ModelError, OPENROUTER_URL, DEFAULT_DECISION_MODEL } from "./model.js";
+export { foldTools, mcpToolset, forgivingArgs, readCall, stableJson } from "./tools.js";
+export { readVerdict, combineHooks } from "./hooks.js";
+export { jevStopCheck, jevToolGate, ask, workLog, DEFAULT_CHECKS } from "./jev.js";
+export { createGuide, levelFromCard, levelFromProfile, memoryProfiles, fileProfiles, DEFAULT_THRESHOLDS, LEVELS, ANSWER_NOW } from "./guide.js";
+export { limits, overBudget, DEFAULT_BUDGET } from "./budget.js";
+export { eventLog } from "./events.js";
+export { defaultPrompts, memorySessions } from "./seams.js";
+export { inlineSkills, dirSkills, pickSkills, skillsToolset, readFrontmatter, SKILL_TOOLS, NO_SKILL } from "./skills.js";
+export { askJevTool, askModelTool } from "./consult.js";
+export { scriptedModel, firstOption } from "./testing.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxG,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAiBzH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGnF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGhJ,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGzH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/jev.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Jev behind the hooks — calibrated decisions an app can add to its own gates and checks.
+ *
+ * The built-in guidance lives in guide.ts (checkpoints the loop asks itself, sized to the model).
+ * This module is the explicit, app-owned variant.
+ *
+ * Jev is the engine's second model and its cheapest judge: it answers typed questions with
+ * probabilities, not prose, so it cannot be talked into agreeing, and at a fraction of a cent in
+ * well under a second it is affordable at every step. The loop already asks it whether there is a
+ * task at all and which skills a task needs, and offers `ask_jev` to the worker. This module puts it
+ * behind the hook vocabulary too, so an app can have Jev GATE a change or CHECK an answer, and a
+ * supervisor reads the same go / pause / stop it would from any other hook:
+ *
+ *   jevStopCheck — when the worker stops, Jev answers yes/no questions about the answer against the
+ *                  work (the defaults: every part answered, every fact backed by a tool result, the
+ *                  expected form). A failed check sends the worker back with that check's feedback.
+ *   jevToolGate  — before a change (or any call), Jev judges whether it serves the person's goal;
+ *                  below the bar the run pauses for the person, or the call is refused.
+ *
+ * Both are opt-in: they cost a decision per stop / per gated call, and Potion's evaluation found
+ * the code check (an app's own stopCheck) catches most of what a second judge would. What they spend
+ * goes through the hook context's `spend`, so it counts toward the run's total and USD cap.
+ */
+import type { Hooks } from './hooks.ts';
+import type { ChatMessage, ModelProvider, Question } from './model.ts';
+/** The work so far as a compact log for Jev — the last steps weigh most. */
+export declare function workLog(messages: readonly ChatMessage[]): ({
+    tool_result: string;
+    agent?: undefined;
+    calls?: undefined;
+} | {
+    agent: string | null;
+    calls: string[] | undefined;
+    tool_result?: undefined;
+} | {
+    [x: string]: string;
+    tool_result?: undefined;
+    agent?: undefined;
+    calls?: undefined;
+})[];
+export interface JevCheck {
+    /** A yes/no question about `task`, `final_answer` and `work`. */
+    question: string;
+    /** What the worker is told when the check fails. */
+    feedback: string;
+    /** Below this probability of yes, the check fails. Default 0.5. */
+    min?: number;
+}
+/**
+ * The answer checks from Potion's dropped verdict node, minus the one Jev is documented to be bad at:
+ * "is every fact and number supported by the work" asks it to compare figures across a long
+ * transcript (counting, numbers and long context are its jaggedness). Keep questions atomic.
+ */
+export declare const DEFAULT_CHECKS: Record<string, JevCheck>;
+/** A stopCheck that sends the worker back when Jev finds the answer falls short. */
+export declare function jevStopCheck(provider: ModelProvider, checks?: Record<string, JevCheck>): NonNullable<Hooks['stopCheck']>;
+export interface JevGateOptions {
+    /** The question about `goal`, `tool`, `args` and `change`. */
+    question?: string;
+    /** Below this probability of yes, the gate acts. Default 0.3. */
+    min?: number;
+    /** What happens below the bar: pause the run for the person (default), or refuse this call and go on. */
+    below?: 'pause' | 'refuse';
+    /** Gate every call, not only changes. Default false. */
+    everyCall?: boolean;
+}
+/** A toolGate where Jev judges whether a call serves the person's goal. */
+export declare function jevToolGate(provider: ModelProvider, options?: JevGateOptions): NonNullable<Hooks['toolGate']>;
+/** Ask Jev one question outside the loop — a convenience with the same cost accounting. */
+export declare function ask(provider: ModelProvider, state: unknown, question: Question, signal?: AbortSignal): Promise<{
+    answer: import("./model.ts").Answer;
+    cost: number;
+}>;
+//# sourceMappingURL=jev.d.ts.map

package/dist/jev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jev.d.ts","sourceRoot":"","sources":["../src/jev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvE,4EAA4E;AAC5E,wBAAgB,OAAO,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE;;;;;;;;;;;;;KAWvD;AAED,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAGnD,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAkB,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAqBxI;AAED,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC3B,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE,cAAmB,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAkBjH;AAED,2FAA2F;AAC3F,wBAAsB,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW;;;GAI1G"}