@looprun-ai/core 0.1.0

package/dist/runtime/ledger.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @looprun-ai/core runtime — the per-conversation observation LEDGER (framework-free).
+ *
+ * The ledger is what guards read (`ctx.observed`, `producedThisTurn`, …): the model's own verified
+ * tool activity — never the user text (magnet firewall). `observed` accumulates for the whole
+ * conversation; the other fields reset per turn via `beginTurn`.
+ */
+import type { ObservedCall } from '../rules.js';
+export interface TurnLedger {
+    observed: ObservedCall[];
+    turnIndex: number;
+    producedThisTurn: string[];
+    turnCorrections: string[];
+    attachments: string[];
+    terminalReply: string;
+}
+export declare function createLedger(): TurnLedger;
+/** Reset the per-turn fields (the conversation-scoped `observed` is kept). */
+export declare function beginTurn(ledger: TurnLedger, turnIndex: number): void;
+/** Structural success check on a tool result ({success:false} / {error} / {PREREQ_NOT_MET} ⇒ failed). */
+export declare function resultOk(r: unknown): boolean;
+/** Record a guard VETO of a tool call (the call did not run). */
+export declare function recordVeto(ledger: TurnLedger, name: string, args: Record<string, unknown>, correction: string): void;
+/** Record an EXECUTED tool call's outcome (afterToolCall): ok flag, confirmation flag, produced label. */
+export declare function recordToolResult(ledger: TurnLedger, name: string, args: Record<string, unknown>, output: unknown): void;
+/** Record a TERMINAL tool call (replyToUser/askUser): capture the user-facing text. */
+export declare function recordTerminal(ledger: TurnLedger, name: string, args: Record<string, unknown>): void;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/runtime/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/runtime/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,YAAY,IAAI,UAAU,CAEzC;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAMrE;AAED,yGAAyG;AACzG,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAM5C;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGpH;AAED,0GAA0G;AAC1G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAcvH;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIpG"}

package/dist/runtime/ledger.js

@@ -0,0 +1,50 @@
+export function createLedger() {
+    return { observed: [], turnIndex: 0, producedThisTurn: [], turnCorrections: [], attachments: [], terminalReply: '' };
+}
+/** Reset the per-turn fields (the conversation-scoped `observed` is kept). */
+export function beginTurn(ledger, turnIndex) {
+    ledger.turnIndex = turnIndex;
+    ledger.producedThisTurn = [];
+    ledger.turnCorrections = [];
+    ledger.attachments = [];
+    ledger.terminalReply = '';
+}
+/** Structural success check on a tool result ({success:false} / {error} / {PREREQ_NOT_MET} ⇒ failed). */
+export function resultOk(r) {
+    if (r && typeof r === 'object') {
+        const o = r;
+        if (o.success === false || o.PREREQ_NOT_MET === true || typeof o.error === 'string')
+            return false;
+    }
+    return true;
+}
+/** Record a guard VETO of a tool call (the call did not run). */
+export function recordVeto(ledger, name, args, correction) {
+    ledger.observed.push({ name, args, ok: false, turnIndex: ledger.turnIndex });
+    ledger.turnCorrections.push(correction);
+}
+/** Record an EXECUTED tool call's outcome (afterToolCall): ok flag, confirmation flag, produced label. */
+export function recordToolResult(ledger, name, args, output) {
+    const ok = output !== undefined && resultOk(output);
+    const requiresConfirmation = output?.requiresConfirmation === true;
+    ledger.observed.push({
+        name,
+        args,
+        ok,
+        turnIndex: ledger.turnIndex,
+        ...(requiresConfirmation ? { resultFlags: { requiresConfirmation: true } } : {}),
+    });
+    if (ok) {
+        const lbl = output?.label;
+        if (typeof lbl === 'string')
+            ledger.producedThisTurn.push(lbl);
+    }
+}
+/** Record a TERMINAL tool call (replyToUser/askUser): capture the user-facing text. */
+export function recordTerminal(ledger, name, args) {
+    const text = typeof args.text === 'string' ? args.text : '';
+    if (text.trim())
+        ledger.terminalReply = text;
+    ledger.observed.push({ name, args, ok: true, turnIndex: ledger.turnIndex });
+}
+//# sourceMappingURL=ledger.js.map

package/dist/runtime/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/runtime/ledger.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,gBAAgB,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;AACvH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,MAAkB,EAAE,SAAiB;IAC7D,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,gBAAgB,GAAG,EAAE,CAAC;IAC7B,MAAM,CAAC,eAAe,GAAG,EAAE,CAAC;IAC5B,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;IACxB,MAAM,CAAC,aAAa,GAAG,EAAE,CAAC;AAC5B,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,cAAc,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACpG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,UAAU,CAAC,MAAkB,EAAE,IAAY,EAAE,IAA6B,EAAE,UAAkB;IAC5G,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7E,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,gBAAgB,CAAC,MAAkB,EAAE,IAAY,EAAE,IAA6B,EAAE,MAAe;IAC/G,MAAM,EAAE,GAAG,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,oBAAoB,GAAI,MAAgE,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC9H,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QACnB,IAAI;QACJ,IAAI;QACJ,EAAE;QACF,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjF,CAAC,CAAC;IACH,IAAI,EAAE,EAAE,CAAC;QACP,MAAM,GAAG,GAAI,MAAiD,EAAE,KAAK,CAAC;QACtE,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,MAAkB,EAAE,IAAY,EAAE,IAA6B;IAC5F,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,IAAI,IAAI,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC;IAC7C,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;AAC9E,CAAC"}

package/dist/runtime/terminal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @looprun-ai/core runtime — the TERMINAL protocol (framework-free).
+ *
+ * The certified turn shape: the model speaks to the user ONLY through the runtime-owned terminal
+ * tools (`replyToUser` / `askUser`) — combined with `toolChoice:'required'` this forces action
+ * before speech and makes the user-facing text a verifiable tool argument instead of free text.
+ */
+import type { ToolDef } from './types.js';
+export declare const TERMINAL_TOOLS: readonly ["replyToUser", "askUser"];
+export declare function isTerminal(name: string): boolean;
+export declare const TERMINAL_PROTOCOL: string;
+export declare const TERMINAL_PROTOCOL_REPLY_ONLY: string;
+export declare function terminalProtocol(replyOnly: boolean): string;
+/** The forced-terminal fallback prompt (pushes a weak model past the action wall). */
+export declare function forcedTerminalPrompt(replyOnly: boolean): string;
+/** Default JSON-schema defs for the terminal tools (used when the host's toolDefs omit them). */
+export declare function terminalToolDefs(): ToolDef[];
+//# sourceMappingURL=terminal.d.ts.map

package/dist/runtime/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/runtime/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,cAAc,qCAAsC,CAAC;AAGlE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,eAAO,MAAM,iBAAiB,QAMqD,CAAC;AAEpF,eAAO,MAAM,4BAA4B,QAMgB,CAAC;AAE1D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAI/D;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,IAAI,OAAO,EAAE,CAqB5C"}

package/dist/runtime/terminal.js

@@ -0,0 +1,50 @@
+export const TERMINAL_TOOLS = ['replyToUser', 'askUser'];
+const TERMINAL_SET = new Set(TERMINAL_TOOLS);
+export function isTerminal(name) {
+    return TERMINAL_SET.has(name);
+}
+export const TERMINAL_PROTOCOL = '\n\n## Turn protocol (ABSOLUTE)\n' +
+    '- You speak to the user ONLY by calling **replyToUser** (to answer or summarize what you did) or **askUser** ' +
+    '(to ask ONE clarifying question). NEVER write a free-text reply — text outside these tools is not delivered.\n' +
+    '- Every turn MUST call at least one tool, and MUST END by calling exactly one replyToUser or askUser whose ' +
+    '`text` carries the COMPLETE user-facing message in the user\'s language.\n' +
+    '- Do the domain tools first; then close the turn with the single terminal call.';
+export const TERMINAL_PROTOCOL_REPLY_ONLY = '\n\n## Turn protocol (ABSOLUTE)\n' +
+    '- You speak to the user ONLY by calling **replyToUser**. NEVER write a free-text reply and NEVER ask the ' +
+    'user a question — there is no ask tool.\n' +
+    '- If something is ambiguous, make the MOST REASONABLE assumption and PROCEED — never stop to ask.\n' +
+    '- Every turn MUST first DO the requested action with the domain tools, then END by calling replyToUser whose ' +
+    '`text` reports what you did, in the user\'s language.';
+export function terminalProtocol(replyOnly) {
+    return replyOnly ? TERMINAL_PROTOCOL_REPLY_ONLY : TERMINAL_PROTOCOL;
+}
+/** The forced-terminal fallback prompt (pushes a weak model past the action wall). */
+export function forcedTerminalPrompt(replyOnly) {
+    return replyOnly
+        ? 'Close the turn now by calling replyToUser. Do NOT ask a question — state what you did in `text`.'
+        : 'Close the turn now: call replyToUser to answer / summarize what you did, or askUser to ask ONE clarifying question. Put the COMPLETE user-facing message in `text`.';
+}
+/** Default JSON-schema defs for the terminal tools (used when the host's toolDefs omit them). */
+export function terminalToolDefs() {
+    return [
+        {
+            name: 'replyToUser',
+            description: 'Deliver the COMPLETE user-facing reply for this turn. Call exactly once, at the end of the turn.',
+            inputSchema: {
+                type: 'object',
+                properties: { text: { type: 'string', description: "The complete user-facing message, in the user's language." } },
+                required: ['text'],
+            },
+        },
+        {
+            name: 'askUser',
+            description: 'Ask the user ONE clarifying question and end the turn. Use only when you cannot proceed.',
+            inputSchema: {
+                type: 'object',
+                properties: { text: { type: 'string', description: "The single clarifying question, in the user's language." } },
+                required: ['text'],
+            },
+        },
+    ];
+}
+//# sourceMappingURL=terminal.js.map

package/dist/runtime/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../../src/runtime/terminal.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,SAAS,CAAU,CAAC;AAClE,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;AAElE,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAC5B,mCAAmC;IACnC,+GAA+G;IAC/G,gHAAgH;IAChH,6GAA6G;IAC7G,4EAA4E;IAC5E,iFAAiF,CAAC;AAEpF,MAAM,CAAC,MAAM,4BAA4B,GACvC,mCAAmC;IACnC,2GAA2G;IAC3G,2CAA2C;IAC3C,qGAAqG;IACrG,+GAA+G;IAC/G,uDAAuD,CAAC;AAE1D,MAAM,UAAU,gBAAgB,CAAC,SAAkB;IACjD,OAAO,SAAS,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,iBAAiB,CAAC;AACtE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,oBAAoB,CAAC,SAAkB;IACrD,OAAO,SAAS;QACd,CAAC,CAAC,kGAAkG;QACpG,CAAC,CAAC,qKAAqK,CAAC;AAC5K,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,kGAAkG;YAC/G,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2DAA2D,EAAE,EAAE;gBAClH,QAAQ,EAAE,CAAC,MAAM,CAAC;aACnB;SACF;QACD;YACE,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,0FAA0F;YACvG,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,yDAAyD,EAAE,EAAE;gBAChH,QAAQ,EAAE,CAAC,MAAM,CAAC;aACnB;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/turn.d.ts

@@ -0,0 +1,38 @@
+import type { AgentSpec } from '../spec.js';
+import type { TrunkTheme } from '../trunk.js';
+import type { AgentWorld, Guard } from '../rules.js';
+import { type TurnLedger } from './ledger.js';
+export interface ReplyViolation {
+    guard: Guard;
+    reason: string;
+}
+export type PreToolVerdict = {
+    verdict: 'allow';
+} | {
+    verdict: 'deny';
+    reason: string;
+    guard: Guard;
+};
+/** Run the preTool guards for one candidate call. On deny, the veto is recorded in the ledger. */
+export declare function evaluatePreTool(spec: AgentSpec, ledger: TurnLedger, world: AgentWorld, tool: string, args: Record<string, unknown>): Promise<PreToolVerdict>;
+/** Run the onInput guards (before any LLM call). Returns the refusal reason, or null to proceed. */
+export declare function evaluateOnInput(spec: AgentSpec, ledger: TurnLedger, world: AgentWorld): Promise<string | null>;
+/** Apply the deterministic egress mutators (e.g. jargonScrub) to the reply text. */
+export declare function applyMutators(spec: AgentSpec, ledger: TurnLedger, world: AgentWorld, text: string): string;
+/** Run the onReply guard checks against a candidate reply. */
+export declare function checkReply(spec: AgentSpec, ledger: TurnLedger, world: AgentWorld, text: string): Promise<ReplyViolation[]>;
+/** The redrive user message a backend sends for a bounded NO-TOOLS re-generation. */
+export declare function redriveMessage(violations: ReplyViolation[]): string;
+/** The built-in honest-abstain closure: a pure function of verified observations. */
+export declare function defaultExhaustionReply(theme: TrunkTheme | undefined, world: AgentWorld, okTools: string[], produced: string[], violations: string[]): string;
+export interface FinalizedReply {
+    text: string;
+    exhausted: boolean;
+    violations: string[];
+}
+/**
+ * The whole reply pipeline: mutators → onReply checks → up to `maxRedrives` NO-TOOLS re-generations
+ * (via the backend-supplied `redrive` callback) → deterministic exhaustion closure if still violating.
+ */
+export declare function finalizeReply(spec: AgentSpec, theme: TrunkTheme | undefined, world: AgentWorld, ledger: TurnLedger, initialText: string, redrive: (message: string) => Promise<string>, maxRedrives: number): Promise<FinalizedReply>;
+//# sourceMappingURL=turn.d.ts.map

package/dist/runtime/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../src/runtime/turn.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAY,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACpB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEtD,kGAAkG;AAClG,wBAAsB,eAAe,CACnC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CAkBzB;AAED,oGAAoG;AACpG,wBAAsB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWpH;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB1G;AAED,8DAA8D;AAC9D,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,EAAE,CAAC,CAiB3B;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,CAGnE;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,CAKR;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CAsBzB"}

package/dist/runtime/turn.js

@@ -0,0 +1,127 @@
+/**
+ * @looprun-ai/core runtime — the governed-TURN state machine (framework-free).
+ *
+ * Everything deterministic about one turn lives here; a backend (e.g. @looprun-ai/mastra) supplies only
+ * the framework glue: how tools are wired, how the LLM is called, and ONE async `redrive` callback
+ * that re-generates text with tools disabled.
+ *
+ * The reply pipeline (finalizeReply): mutators → onReply checks → bounded NO-TOOLS redrive →
+ * deterministic honest-abstain closure. The redrive is a plain text re-generation with the
+ * correction appended — NEVER a framework retry that re-runs the whole generation (that re-executes
+ * side-effecting tools; measured ~100× slower).
+ */
+import { resolveGuards, resolveMutators } from '../spec.js';
+import { recordVeto } from './ledger.js';
+/** Run the preTool guards for one candidate call. On deny, the veto is recorded in the ledger. */
+export async function evaluatePreTool(spec, ledger, world, tool, args) {
+    const guards = resolveGuards(spec.guards.preTool, tool);
+    const gctx = {
+        args,
+        tool,
+        world,
+        observed: ledger.observed,
+        turnIndex: ledger.turnIndex,
+        attachmentsThisTurn: ledger.attachments,
+    };
+    for (const g of guards) {
+        const reason = await g.check(gctx);
+        if (reason) {
+            recordVeto(ledger, tool, args, `${g.dim}:${g.kind}:${tool}`);
+            return { verdict: 'deny', reason, guard: g };
+        }
+    }
+    return { verdict: 'allow' };
+}
+/** Run the onInput guards (before any LLM call). Returns the refusal reason, or null to proceed. */
+export async function evaluateOnInput(spec, ledger, world) {
+    const guards = resolveGuards(spec.guards.onInput);
+    const gctx = { args: {}, world, observed: ledger.observed, turnIndex: ledger.turnIndex };
+    for (const g of guards) {
+        const reason = await g.check(gctx);
+        if (reason) {
+            ledger.turnCorrections.push(`onInput:${g.kind}`);
+            return reason;
+        }
+    }
+    return null;
+}
+/** Apply the deterministic egress mutators (e.g. jargonScrub) to the reply text. */
+export function applyMutators(spec, ledger, world, text) {
+    let out = text;
+    for (const m of resolveMutators(spec.guards.onReplyMutate)) {
+        const mctx = {
+            args: {},
+            world,
+            observed: ledger.observed,
+            turnIndex: ledger.turnIndex,
+            reply: out,
+            producedThisTurn: ledger.producedThisTurn,
+        };
+        const next = m.apply(out, mctx);
+        if (next !== out) {
+            ledger.turnCorrections.push(`mutate:${m.kind}`);
+            out = next;
+        }
+    }
+    return out;
+}
+/** Run the onReply guard checks against a candidate reply. */
+export async function checkReply(spec, ledger, world, text) {
+    const rctx = {
+        args: {},
+        world,
+        observed: ledger.observed,
+        turnIndex: ledger.turnIndex,
+        reply: text,
+        producedThisTurn: ledger.producedThisTurn,
+        attachmentsThisTurn: ledger.attachments,
+        notes: ledger.turnCorrections,
+    };
+    const out = [];
+    for (const g of resolveGuards(spec.guards.onReply)) {
+        const r = await g.check(rctx);
+        if (r)
+            out.push({ guard: g, reason: r });
+    }
+    return out;
+}
+/** The redrive user message a backend sends for a bounded NO-TOOLS re-generation. */
+export function redriveMessage(violations) {
+    const correction = violations.map((v) => `- ${v.reason}`).join('\n');
+    return `Revise your last reply to the user:\n${correction}\nReply now in the user's language. Do NOT call a tool.`;
+}
+/** The built-in honest-abstain closure: a pure function of verified observations. */
+export function defaultExhaustionReply(theme, world, okTools, produced, violations) {
+    if (theme?.exhaustionReply)
+        return theme.exhaustionReply(world, okTools, produced, violations);
+    return okTools.length
+        ? `Done this step: ${[...new Set(okTools)].join(', ')}${produced.length ? ` (${produced.join(', ')})` : ''}. I could not safely finish the rest — how would you like to proceed?`
+        : 'I could not complete this safely — nothing was changed. Could you rephrase or add detail?';
+}
+/**
+ * The whole reply pipeline: mutators → onReply checks → up to `maxRedrives` NO-TOOLS re-generations
+ * (via the backend-supplied `redrive` callback) → deterministic exhaustion closure if still violating.
+ */
+export async function finalizeReply(spec, theme, world, ledger, initialText, redrive, maxRedrives) {
+    let text = applyMutators(spec, ledger, world, initialText);
+    let violations = await checkReply(spec, ledger, world, text);
+    for (let r = 0; r < maxRedrives && violations.length; r++) {
+        const next = await redrive(redriveMessage(violations));
+        for (const v of violations)
+            ledger.turnCorrections.push(`redrive:${v.guard.kind}`);
+        if (next)
+            text = next;
+        violations = await checkReply(spec, ledger, world, text);
+    }
+    const finalViolations = violations.map((v) => v.guard.kind);
+    if (finalViolations.length) {
+        const okTools = ledger.observed.filter((o) => o.turnIndex === ledger.turnIndex && o.ok).map((o) => o.name);
+        const closure = spec.controls.exhaustionReply
+            ? spec.controls.exhaustionReply(world, okTools, ledger.producedThisTurn, finalViolations)
+            : defaultExhaustionReply(theme, world, okTools, ledger.producedThisTurn, finalViolations);
+        ledger.turnCorrections.push('exhaustion-terminal');
+        return { text: closure, exhausted: true, violations: finalViolations };
+    }
+    return { text, exhausted: false, violations: [] };
+}
+//# sourceMappingURL=turn.js.map

package/dist/runtime/turn.js.map

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

package/dist/runtime/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @looprun-ai/core runtime — shared types of the governed-turn machine (framework-free).
+ */
+/** A tool definition (name / description / JSON schema) executed through the world seam. */
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface TokenUsage {
+    input: number | null;
+    output: number | null;
+    reasoning: number | null;
+    cacheRead: number | null;
+    cacheWrite: number | null;
+    total: number | null;
+}
+/** One conversation turn's input (channel-agnostic). */
+export interface TurnInput {
+    userText: string;
+    attachments?: string[];
+}
+/** A per-turn record emitted by a backend's conversation runner. */
+export interface TurnRecord {
+    userText: string;
+    assistantFinalText: string;
+    finalMode: string;
+    assistantMsgCount: number;
+    iters: number;
+    llmCalls: number;
+    toolCalls: Array<{
+        name: string;
+        args: unknown;
+        resultSummary: string;
+        tookEffect?: boolean;
+        latencyMs: number;
+    }>;
+    thoughts: string | null;
+    tokens: TokenUsage;
+    llmCallLatenciesMs: number[];
+    durationMs: number;
+    maxIterHit: boolean;
+    recoveryEvents: string[];
+    sseActions?: unknown[];
+    attachments?: string[];
+}
+export interface RunResult {
+    turnRecords: TurnRecord[];
+    messages: any[];
+    errorMsg?: string;
+}
+/** Continuity aliases (the pre-extraction runtime names). */
+export type RuntimeTurnInput = TurnInput;
+export type RuntimeTurnRecord = TurnRecord;
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,UAAU,EAAE,CAAC;IAE1B,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC;AACzC,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC"}

package/dist/runtime/types.js

@@ -0,0 +1,5 @@
+/**
+ * @looprun-ai/core runtime — shared types of the governed-turn machine (framework-free).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/spec.d.ts

@@ -0,0 +1,147 @@
+import type { AgentWorld, Guard, ReplyMutator, SpatialEdge } from './rules.js';
+import type { TrunkTheme } from './trunk.js';
+export type Hook = 'onInput' | 'preTool' | 'postTool' | 'onReply';
+export type ToolTarget = 'any' | string[];
+export type Layer = 'minimal' | 'base' | 'full' | 'agent';
+/** true ⇒ force reply()-only this turn (drop askUser). State-driven, per turn. */
+export type TerminalPolicy = (world: AgentWorld) => boolean;
+/** State-keyed positive guidance rendered statically as "IF <cond> → <directive>" (cache-stable). */
+export interface StateDirective {
+    id: string;
+    cond: string;
+    directive: string;
+    when?: (world: AgentWorld) => boolean;
+}
+export interface AgentModelRef {
+    provider?: string;
+    model?: string;
+    id?: string;
+}
+export interface MutatorBinding {
+    id: string;
+    mutator: ReplyMutator;
+    layer: Layer;
+    disabled: boolean;
+}
+export interface GuardBinding {
+    id: string;
+    target: ToolTarget;
+    guard: Guard;
+    layer: Layer;
+    disabled: boolean;
+}
+export interface AgentControls {
+    maxSteps?: number;
+    redrives?: number;
+    terminal?: TerminalPolicy;
+    directives?: StateDirective[];
+    escalate?: {
+        model: AgentModelRef;
+        maxAttempts?: number;
+    };
+    /** Committed when the reply still violates its checks after all redrives — MUST be a pure function
+     *  of verified observations (structurally unable to fabricate). Omitted ⇒ the theme/default closure. */
+    exhaustionReply?: (world: AgentWorld, okTools: string[], produced: string[], violations: string[]) => string;
+}
+export interface AgentSpec {
+    id: string;
+    mode: string;
+    /** THIS agent's persona/role line (persona-on-spec law: per-agent, owned by the spec — never a
+     *  shared/global persona; the domain-common VOICE lives on the theme). Rendered as the FIRST
+     *  `## Behavior` bullet — per-agent divergence as late as possible so the domain's agents share a
+     *  maximal static trunk prefix (trunk-static law). MUST be case-invariant (state-in-tail law). */
+    persona: string;
+    surface: {
+        tools: string[];
+        systemPrompt?: (world: AgentWorld, recentUploads?: readonly string[]) => string;
+    };
+    flow: SpatialEdge[];
+    guards: {
+        onInput?: GuardBinding[];
+        preTool: GuardBinding[];
+        postTool?: GuardBinding[];
+        onReply: GuardBinding[];
+        onReplyMutate?: MutatorBinding[];
+    };
+    controls: AgentControls;
+    behavior: string[];
+    /** Optional reference to the DOMAIN theme this spec belongs to. Themes stay domain-level objects
+     *  (1 theme : N agents, byte-identical shared trunk head — trunk-static law); this field lets a
+     *  generated bundle point every spec at the SAME theme object so a host can construct an agent
+     *  from the spec alone. A host-provided theme always overrides it. */
+    theme?: TrunkTheme;
+}
+export declare function resolveBindings(bindings: GuardBinding[] | undefined, tool?: string): GuardBinding[];
+export declare function resolveGuards(bindings: GuardBinding[] | undefined, tool?: string): Guard[];
+export declare function resolveMutators(bindings: MutatorBinding[] | undefined): ReplyMutator[];
+export interface ToolSchemaLike {
+    required?: string[];
+    properties?: Record<string, {
+        pattern?: string;
+        type?: string;
+    }>;
+}
+export interface AgentSpecConfig {
+    id: string;
+    mode: string;
+    /** Required per-agent persona/role line (persona-on-spec law) — case-invariant; rendered as the
+     *  first Behavior bullet. */
+    persona: string;
+    tools: string[];
+    systemPrompt?: (world: AgentWorld, recentUploads?: readonly string[]) => string;
+    flow?: SpatialEdge[];
+    behavior?: string[];
+    terminal?: TerminalPolicy;
+    directives?: StateDirective[];
+    maxSteps?: number;
+    redrives?: number;
+    escalate?: {
+        model: AgentModelRef;
+        maxAttempts?: number;
+    };
+    exhaustionReply?: (world: AgentWorld, okTools: string[], produced: string[], violations: string[]) => string;
+    destructiveTools?: string[];
+    toolSchemas?: Record<string, ToolSchemaLike>;
+    /** Optional domain-theme reference (see {@link AgentSpec.theme}). */
+    theme?: TrunkTheme;
+}
+export declare class AgentSpecMinimal implements AgentSpec {
+    readonly id: string;
+    readonly mode: string;
+    readonly persona: string;
+    readonly surface: AgentSpec['surface'];
+    readonly flow: SpatialEdge[];
+    readonly guards: Required<AgentSpec['guards']>;
+    readonly controls: AgentControls;
+    readonly behavior: string[];
+    readonly theme?: TrunkTheme;
+    protected readonly destructiveTools: string[];
+    protected readonly toolSchemas: Record<string, ToolSchemaLike>;
+    private seq;
+    constructor(cfg: AgentSpecConfig);
+    protected installMinimal(): void;
+    addGuard(hook: Hook, target: ToolTarget, guard: Guard, opts?: {
+        id?: string;
+        layer?: Layer;
+    }): string;
+    addReplyCheck(guard: Guard, opts?: {
+        id?: string;
+        layer?: Layer;
+    }): string;
+    addMutator(mutator: ReplyMutator, opts?: {
+        id?: string;
+        layer?: Layer;
+    }): string;
+    get isPureGuardSet(): boolean;
+    addBehavior(line: string): this;
+    addFlow(edge: SpatialEdge): this;
+}
+export declare class AgentSpecBase extends AgentSpecMinimal {
+    constructor(cfg: AgentSpecConfig);
+    protected installBase(): void;
+}
+export declare class AgentSpecFull extends AgentSpecBase {
+    constructor(cfg: AgentSpecConfig);
+    protected installFull(): void;
+}
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

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