@falai/agent 3.4.5 → 4.0.0-alpha.1

package/dist/core/Migrate.js

@@ -0,0 +1,264 @@
+/**
+ * Reading stored session blobs.
+ *
+ * `assertSession` is the v4 shape check every store runs on load.
+ * `migrateSession` lifts a 3.x `SessionState` into a v4 `Session` once, at
+ * the host's choke point (design §10). Both fail loudly: a row that is
+ * neither a v4 session nor a recognisable 3.x blob throws
+ * `InvalidSessionError` and never comes back as a fresh conversation, which
+ * would silently re-ask every field and re-fire every once-flow.
+ */
+import { isRecord } from "../utils/json.js";
+/** A stored row that cannot be read as a session. */
+export class InvalidSessionError extends Error {
+    constructor(sessionId, why) {
+        super(`[InvalidSessionError] stored session "${sessionId}" is unreadable: ${why}. ` +
+            `Repair or delete the row; it is never replaced by a fresh conversation.`);
+        this.sessionId = sessionId;
+        this.name = "InvalidSessionError";
+    }
+}
+const isWhole = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+/** Short description of a value for error messages. */
+function describe(value) {
+    if (value === undefined)
+        return "missing";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "a list";
+    if (typeof value === "string")
+        return `"${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
+// ── v4 ──────────────────────────────────────────────────────────────────
+const RUN_STATUS = new Set(["running", "asking", "waiting", "suspended"]);
+/**
+ * A v4 blob back to a `Session`, holding only the session keys (a store's
+ * own `createdAt`/`updatedAt` are dropped). Throws `InvalidSessionError`
+ * when the shape is off.
+ */
+export function assertSession(blob, sessionId) {
+    const bad = (why) => new InvalidSessionError(sessionId, why);
+    if (!isRecord(blob))
+        throw bad(`expected an object, got ${describe(blob)}`);
+    if (blob.v !== 4)
+        throw bad(`v is ${describe(blob.v)}, expected 4`);
+    if (blob.id !== sessionId)
+        throw bad(`id is ${describe(blob.id)}, expected "${sessionId}"`);
+    const { version, data, runs, claims, inputs, metadata, history, lastUserAt, lastAssistantAt } = blob;
+    if (!isWhole(version))
+        throw bad(`version is ${describe(version)}, expected a whole number`);
+    if (!isRecord(data))
+        throw bad(`data is ${describe(data)}, expected an object`);
+    if (!Array.isArray(runs))
+        throw bad(`runs is ${describe(runs)}, expected a list`);
+    if (!isRecord(claims) || !Object.values(claims).every((c) => isRecord(c) && typeof c.at === "string")) {
+        throw bad("claims is not a map of { at }");
+    }
+    if (!Array.isArray(inputs) || !inputs.every((i) => typeof i === "string"))
+        throw bad("inputs is not a list of ids");
+    if (!isRecord(metadata))
+        throw bad(`metadata is ${describe(metadata)}, expected an object`);
+    if (history !== undefined && !Array.isArray(history))
+        throw bad(`history is ${describe(history)}, expected a list`);
+    if (lastUserAt !== undefined && typeof lastUserAt !== "string")
+        throw bad("lastUserAt is not text");
+    if (lastAssistantAt !== undefined && typeof lastAssistantAt !== "string")
+        throw bad("lastAssistantAt is not text");
+    const session = {
+        id: sessionId,
+        v: 4,
+        version,
+        data: data,
+        runs: runs.map((run, i) => checkRun(run, i, bad)),
+        claims: claims,
+        inputs,
+        metadata,
+    };
+    if (lastUserAt !== undefined)
+        session.lastUserAt = lastUserAt;
+    if (lastAssistantAt !== undefined)
+        session.lastAssistantAt = lastAssistantAt;
+    if (history !== undefined)
+        session.history = history;
+    return session;
+}
+function checkRun(raw, index, bad) {
+    const at = `runs[${index}]`;
+    if (!isRecord(raw))
+        throw bad(`${at} is ${describe(raw)}, expected an object`);
+    const text = (key) => {
+        const value = raw[key];
+        if (typeof value !== "string")
+            throw bad(`${at}.${key} is ${describe(value)}, expected text`);
+        return value;
+    };
+    const record = (key) => {
+        const value = raw[key];
+        if (!isRecord(value))
+            throw bad(`${at}.${key} is ${describe(value)}, expected an object`);
+        return value;
+    };
+    const status = text("status");
+    if (!RUN_STATUS.has(status))
+        throw bad(`${at}.status is "${status}"`);
+    const { stepId, hop, outcomes, input, waiting, suspendedAt } = raw;
+    if (stepId !== null && typeof stepId !== "string")
+        throw bad(`${at}.stepId is ${describe(stepId)}, expected text or null`);
+    if (!isWhole(hop))
+        throw bad(`${at}.hop is ${describe(hop)}, expected a whole number`);
+    if (!Array.isArray(outcomes))
+        throw bad(`${at}.outcomes is ${describe(outcomes)}, expected a list`);
+    const trigger = record("trigger");
+    if (typeof trigger.kind !== "string" || typeof trigger.key !== "string")
+        throw bad(`${at}.trigger needs kind and key`);
+    if (waiting !== undefined && !isRecord(waiting))
+        throw bad(`${at}.waiting is ${describe(waiting)}, expected an object`);
+    // ponytail: outcomes, waiting and the asked/visits counters are trusted below
+    // the keys checked here; every writer is this package. Upgrade: a full schema check.
+    const run = {
+        id: text("id"),
+        flowId: text("flowId"),
+        anchor: text("anchor"),
+        dedupeKey: text("dedupeKey"),
+        stepId,
+        status: status,
+        trigger: trigger,
+        hop,
+        startedAt: text("startedAt"),
+        asked: record("asked"),
+        visits: record("visits"),
+        outcomes: outcomes,
+    };
+    if (input !== undefined)
+        run.input = input;
+    if (waiting !== undefined)
+        run.waiting = waiting;
+    if (typeof suspendedAt === "string")
+        run.suspendedAt = suspendedAt;
+    return run;
+}
+// ── 3.x → 4 ─────────────────────────────────────────────────────────────
+/**
+ * A stored blob to a v4 `Session`. A v4 blob passes through `assertSession`.
+ * A 3.x `SessionState` becomes: `data` verbatim; `currentFlow`/`currentStep`
+ * one run at the same step; every fired signal and every completed flow a
+ * `once` claim, so nothing re-fires; `pendingDirective` dropped; `metadata`
+ * kept with its dates as ISO text. Anything else throws `InvalidSessionError`.
+ */
+export function migrateSession(blob, options) {
+    const { sessionId } = options;
+    const bad = (why) => new InvalidSessionError(sessionId, why);
+    if (!isRecord(blob))
+        throw bad(`expected an object, got ${describe(blob)}`);
+    if ("v" in blob)
+        return assertSession(blob, sessionId);
+    return fromLegacy(blob, options, bad);
+}
+function fromLegacy(blob, options, bad) {
+    const { sessionId, flowIdOf } = options;
+    const { data, metadata, history, flowHistory, signals } = blob;
+    if (!isRecord(data))
+        throw bad(`data is ${describe(data)}, expected an object; not a 3.x session either`);
+    if (metadata !== undefined && !isRecord(metadata))
+        throw bad(`metadata is ${describe(metadata)}, expected an object`);
+    if (history !== undefined && !Array.isArray(history))
+        throw bad(`history is ${describe(history)}, expected a list`);
+    if (flowHistory !== undefined && !Array.isArray(flowHistory))
+        throw bad(`flowHistory is ${describe(flowHistory)}, expected a list`);
+    if (signals !== undefined && !isRecord(signals))
+        throw bad(`signals is ${describe(signals)}, expected an object`);
+    const triggers = signals?.triggers ?? {};
+    if (!isRecord(triggers))
+        throw bad(`signals.triggers is ${describe(triggers)}, expected an object`);
+    const fallback = (options.now ?? new Date()).toISOString();
+    const claimKey = (key) => `${flowIdOf(key)}:${sessionId}:`;
+    const claims = {};
+    for (const [i, entry] of (flowHistory ?? []).entries()) {
+        if (!isRecord(entry) || typeof entry.flowId !== "string")
+            throw bad(`flowHistory[${i}] is not a flow entry`);
+        if (entry.completed === true) {
+            claims[claimKey(entry.flowId)] = { at: toIso(entry.exitedAt) ?? toIso(entry.enteredAt) ?? fallback };
+        }
+    }
+    for (const [key, state] of Object.entries(triggers)) {
+        if (!isRecord(state))
+            throw bad(`signals.triggers.${key} is not a trigger state`);
+        claims[claimKey(key)] = { at: toIso(state.lastTriggeredAt) ?? toIso(state.firstTriggeredAt) ?? fallback };
+    }
+    const runs = [];
+    const flowRef = legacyRef(blob.currentFlow, "currentFlow", bad);
+    const stepRef = legacyRef(blob.currentStep, "currentStep", bad);
+    if (flowRef) {
+        const flowId = flowIdOf(flowRef.id);
+        const startedAt = toIso(flowRef.enteredAt) ?? fallback;
+        const stepId = stepRef?.id ?? null;
+        runs.push({
+            id: `${flowId}#legacy`,
+            flowId,
+            anchor: sessionId,
+            dedupeKey: `${flowId}:${sessionId}:`,
+            stepId,
+            // A flow entered before its first step is a fresh run; at a step it is asking there.
+            status: stepId === null ? "running" : "asking",
+            trigger: { kind: "message", key: "legacy" },
+            hop: 0,
+            startedAt,
+            asked: {},
+            visits: {},
+            outcomes: [],
+        });
+        // Invariant I5: a run never exists without its claim.
+        claims[`${flowId}:${sessionId}:`] = { at: startedAt };
+    }
+    const session = {
+        id: sessionId,
+        v: 4,
+        // A migrated session has no v4 row yet: 0 makes the host's first save an insert.
+        version: 0,
+        data: data,
+        runs,
+        claims,
+        inputs: [],
+        metadata: recordDatesToIso(metadata ?? {}),
+    };
+    if (history !== undefined)
+        session.history = history;
+    return session;
+}
+/** `currentFlow`/`currentStep` as 3.x wrote them: `{ id, enteredAt? }` in the blob, a bare id in a row. */
+function legacyRef(value, name, bad) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return value ? { id: value } : undefined;
+    if (isRecord(value) && typeof value.id === "string")
+        return { id: value.id, enteredAt: value.enteredAt };
+    throw bad(`${name} is ${describe(value)}, expected { id } or text`);
+}
+/** A Date, ISO text or epoch number as ISO text; anything else is nothing. */
+function toIso(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value.toISOString();
+    if (typeof value === "number" || (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value))) {
+        const ms = new Date(value).getTime();
+        return Number.isNaN(ms) ? undefined : new Date(ms).toISOString();
+    }
+    return undefined;
+}
+function recordDatesToIso(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, value]) => [key, datesToIso(value)]));
+}
+function datesToIso(value) {
+    if (value instanceof Date)
+        return toIso(value) ?? null;
+    if (Array.isArray(value))
+        return value.map(datesToIso);
+    if (isRecord(value))
+        return recordDatesToIso(value);
+    return value;
+}
+//# sourceMappingURL=Migrate.js.map

package/dist/core/Migrate.js.map

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

package/dist/core/Prompt.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Prompt sections shared by the understand and speak calls.
+ *
+ * Each function returns one markdown section or `null` when there is nothing
+ * to say; `joinSections` drops the nulls. Templates are rendered against the
+ * turn's scope. Instruction `if` predicates are judged by the caller (they
+ * need the runtime); only `when` reaches the prompt, as text for the model.
+ */
+import type { AgentOptions } from "../types/agent.js";
+import type { FieldDef, Instruction } from "../types/flow.js";
+import { type TemplateScope } from "../utils/template.js";
+export declare function joinSections(...parts: Array<string | null | undefined>): string;
+/** Who the agent is: name, persona, goal. */
+export declare function identitySection(options: Pick<AgentOptions, "name" | "persona" | "goal">, scope: TemplateScope): string;
+/**
+ * Split the prompt's opening into the half that repeats every turn and the
+ * half that does not.
+ *
+ * The stable half goes out as a system message so a provider can cache it: on
+ * Anthropic that block is the one thing carrying a `cache_control` marker, and
+ * a cache read is a tenth the price of the tokens it replaces. Sent as part of
+ * the trailing user turn — which is where the whole prompt used to go — it sat
+ * behind text that changes every turn, so nothing was ever cached and both
+ * calls of every turn re-billed the identity and the knowledge base in full.
+ *
+ * The line is drawn at "does this text interpolate", not at "is this identity".
+ * `persona` and `goal` render through the turn's scope, so a persona that
+ * mentions a collected field changes the moment that field lands: cached, it
+ * would pay the write every turn and never read. Those go back inline.
+ */
+export declare function stablePrefix(options: Pick<AgentOptions, "name" | "persona" | "goal" | "knowledgeBase">, scope: TemplateScope): {
+    system: string | null;
+    inline: string | null;
+};
+/** Any JSON the agent should know, as nested bullets. */
+export declare function knowledgeSection(knowledge: Record<string, unknown> | undefined): string | null;
+export interface InstructionGroup<C = unknown, D = unknown> {
+    /** `[Always]`, `[In: Triagem]`, `[Step: quem]`. */
+    caption: string;
+    /** Already filtered by their `if`. */
+    items: Instruction<C, D>[];
+}
+/** Behavioural statements with their kind and AI-judged `when`. */
+export declare function instructionsSection<C, D>(groups: InstructionGroup<C, D>[], scope: TemplateScope): string | null;
+/** Collected fields the model must treat as settled. */
+export declare function factsSection(fields: Record<string, FieldDef>, data: Record<string, unknown>): string | null;
+/** One line describing a field for the model: slug, type, options, description. */
+export declare function describeField(slug: string, def: FieldDef): string;
+/**
+ * The fields a talk step still needs, each with how to ask for it. `asks`
+ * holds the step's own wording; the field's `ask` is the fallback.
+ */
+export declare function pendingSection(pending: string[], fields: Record<string, FieldDef>, asks: Partial<Record<string, string>>, scope: TemplateScope): string | null;
+//# sourceMappingURL=Prompt.d.ts.map

package/dist/core/Prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Prompt.d.ts","sourceRoot":"","sources":["../../src/core/Prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAElE,wBAAgB,YAAY,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAE/E;AAED,6CAA6C;AAC7C,wBAAgB,eAAe,CAC7B,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,EACxD,KAAK,EAAE,aAAa,GACnB,MAAM,CAKR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,eAAe,CAAC,EAC1E,KAAK,EAAE,aAAa,GACnB;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAMlD;AAMD,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG9F;AA6BD,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACxD,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;CAC5B;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAY/G;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAQ3G;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,MAAM,CAIjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAChC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACrC,KAAK,EAAE,aAAa,GACnB,MAAM,GAAG,IAAI,CAaf"}

package/dist/core/Prompt.js

@@ -0,0 +1,133 @@
+/**
+ * Prompt sections shared by the understand and speak calls.
+ *
+ * Each function returns one markdown section or `null` when there is nothing
+ * to say; `joinSections` drops the nulls. Templates are rendered against the
+ * turn's scope. Instruction `if` predicates are judged by the caller (they
+ * need the runtime); only `when` reaches the prompt, as text for the model.
+ */
+import { isKnown } from "../utils/schema.js";
+import { render } from "../utils/template.js";
+export function joinSections(...parts) {
+    return parts.filter((p) => typeof p === "string" && p.trim() !== "").join("\n\n").trim();
+}
+/** Who the agent is: name, persona, goal. */
+export function identitySection(options, scope) {
+    const lines = ["## Identity", `You are "${options.name}". Always refer to yourself by this name.`];
+    if (options.persona)
+        lines.push(render(options.persona, scope));
+    if (options.goal)
+        lines.push(`Your goal: ${render(options.goal, scope)}`);
+    return lines.join("\n");
+}
+/**
+ * Split the prompt's opening into the half that repeats every turn and the
+ * half that does not.
+ *
+ * The stable half goes out as a system message so a provider can cache it: on
+ * Anthropic that block is the one thing carrying a `cache_control` marker, and
+ * a cache read is a tenth the price of the tokens it replaces. Sent as part of
+ * the trailing user turn — which is where the whole prompt used to go — it sat
+ * behind text that changes every turn, so nothing was ever cached and both
+ * calls of every turn re-billed the identity and the knowledge base in full.
+ *
+ * The line is drawn at "does this text interpolate", not at "is this identity".
+ * `persona` and `goal` render through the turn's scope, so a persona that
+ * mentions a collected field changes the moment that field lands: cached, it
+ * would pay the write every turn and never read. Those go back inline.
+ */
+export function stablePrefix(options, scope) {
+    const identity = identitySection(options, scope);
+    const knowledge = knowledgeSection(options.knowledgeBase);
+    const varies = isTemplated(options.persona) || isTemplated(options.goal);
+    if (varies)
+        return { system: knowledge, inline: identity };
+    return { system: joinSections(identity, knowledge) || null, inline: null };
+}
+function isTemplated(text) {
+    return typeof text === "string" && text.includes("{{");
+}
+/** Any JSON the agent should know, as nested bullets. */
+export function knowledgeSection(knowledge) {
+    if (!knowledge || Object.keys(knowledge).length === 0)
+        return null;
+    return ["## Knowledge base", ...formatObject(knowledge, 0)].join("\n");
+}
+function formatObject(value, depth) {
+    const pad = "  ".repeat(depth);
+    const lines = [];
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+            lines.push(`${pad}- ${key}:`);
+            lines.push(...formatObject(item, depth + 1));
+        }
+        else if (Array.isArray(item) && item.some((i) => i !== null && typeof i === "object")) {
+            lines.push(`${pad}- ${key}:`);
+            for (const i of item) {
+                lines.push(...(i !== null && typeof i === "object"
+                    ? formatObject(i, depth + 1)
+                    : [`${pad}  - ${scalar(i)}`]));
+            }
+        }
+        else {
+            lines.push(`${pad}- ${key}: ${Array.isArray(item) ? item.map(scalar).join(", ") : scalar(item)}`);
+        }
+    }
+    return lines;
+}
+function scalar(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/** Behavioural statements with their kind and AI-judged `when`. */
+export function instructionsSection(groups, scope) {
+    const lines = [];
+    for (const group of groups) {
+        for (const item of group.items) {
+            const text = render(item.prompt, scope).trim();
+            if (!text)
+                continue;
+            const when = item.when === undefined ? [] : Array.isArray(item.when) ? item.when : [item.when];
+            const condition = when.length ? ` (apply only when: ${when.join(" OR ")})` : "";
+            lines.push(`- [${item.kind ?? "should"}] ${group.caption} ${text}${condition}`);
+        }
+    }
+    return lines.length ? ["## Instructions", ...lines].join("\n") : null;
+}
+/** Collected fields the model must treat as settled. */
+export function factsSection(fields, data) {
+    const known = Object.keys(fields).filter((slug) => isKnown(data[slug]));
+    if (known.length === 0)
+        return null;
+    return [
+        "## Already known",
+        "These are settled. Never ask for them again; acknowledge and move on.",
+        ...known.map((slug) => `- ${slug}: ${JSON.stringify(data[slug])}`),
+    ].join("\n");
+}
+/** One line describing a field for the model: slug, type, options, description. */
+export function describeField(slug, def) {
+    const options = def.enum ? ` [${def.enum.map(String).join(" | ")}]` : "";
+    const description = def.description ? `: ${def.description}` : "";
+    return `${slug} (${def.type})${options}${description}`;
+}
+/**
+ * The fields a talk step still needs, each with how to ask for it. `asks`
+ * holds the step's own wording; the field's `ask` is the fallback.
+ */
+export function pendingSection(pending, fields, asks, scope) {
+    if (pending.length === 0)
+        return null;
+    const lines = pending.map((slug) => {
+        const def = fields[slug];
+        if (!def)
+            return `- ${slug}`;
+        const ask = asks[slug] ?? def.ask;
+        return `- ${describeField(slug, def)}${ask ? `\n  How to ask: ${render(ask, scope)}` : ""}`;
+    });
+    return [
+        "## Still to collect",
+        "Ask for these, in this order, at the pace the step prompt sets. When the customer's message already answers one, take the value and do not ask again.",
+        ...lines,
+    ].join("\n");
+}
+//# sourceMappingURL=Prompt.js.map

package/dist/core/Prompt.js.map

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

package/dist/core/Runner.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Runner: the code half of a turn. Load, Ingest, Decide, Run, Settle and
+ * Return (design §4) with one applier, `advance`. Zero provider calls live
+ * here: the Agent asks `understandRequest` and `advance` what to judge and
+ * what to speak, spends the calls, and hands the plain results back to
+ * `decide` and `settle`.
+ *
+ *   begin ─▶ understandRequest ─(Understand)─▶ decide ─▶ advance ─(Speak)─▶ settle ─▶ finish
+ */
+import type { AgentOptions, TurnInput, TurnResult } from "../types/agent.js";
+import type { TokenUsage } from "../types/ai.js";
+import type { Run, Session, StepOutcome } from "../types/session.js";
+import type { IdleRequest, InputKind, SpeakOutcome, SpeakRequest, TalkRequest, UnderstandRequest, Understanding } from "./contracts.js";
+/** What started the turn, already narrowed. */
+export type What = {
+    kind: "message";
+    text: string;
+    id?: string;
+    at: string;
+} | {
+    kind: "wake";
+    key: string;
+} | {
+    kind: "event";
+    name: string;
+    payload: unknown;
+    key: string;
+    hop: number;
+} | {
+    kind: "start";
+    flow: string;
+    input: unknown;
+    key: string;
+    hop: number;
+};
+/** The mutable per-turn state. `session` is a deep copy; the input is never touched. */
+export interface Turn<C = unknown, D = unknown> {
+    readonly input: TurnInput<C, D>;
+    readonly what: What;
+    readonly kind: InputKind;
+    /** Message id, wake key, event key or start key: the trigger key of runs started this turn. */
+    readonly triggerKey: string;
+    readonly session: Session<D>;
+    readonly original?: Session<D>;
+    readonly now: Date;
+    readonly nowIso: string;
+    readonly context: C;
+    readonly silenced?: string;
+    /** The host gate allows the understand call even though the assistant cannot speak. */
+    readonly understandAllowed: boolean;
+    /** Set by a short-circuit: the input is a no-op and nothing is saved. */
+    ignored: boolean;
+    messages: TurnResult<D>["messages"];
+    schedule: TurnResult<D>["schedule"];
+    outcomes: StepOutcome[];
+    started: TurnResult<D>["started"];
+    ended: TurnResult<D>["ended"];
+    skipped: TurnResult<D>["skipped"];
+    llmCalls: number;
+    usage?: TokenUsage;
+    /** The run holding the floor this turn: resolved in Ingest, routed in Decide, or the asker. */
+    floorRunId?: string;
+    /** A run took or resumed the floor in Ingest: routing is skipped. */
+    floorFromIngest: boolean;
+    /** True while Ingest runs, so a child chained there counts as taking the floor in Ingest. */
+    ingesting: boolean;
+    /** Runs that emitted a `say` or an action `spoke: true` this turn. */
+    spokeBy: Set<string>;
+    /** The assistant produced output this turn (say, spoke, ai message). */
+    spoke: boolean;
+    /** A short `wait` waiting to ride on the next message. */
+    afterMs: number;
+    talk?: TalkRequest<C, D>;
+    /** Speak already happened (or was skipped): a talk step reached now waits for the next message. */
+    speakDone: boolean;
+    /** Runs still to move this phase; `follow` appends children. */
+    queue: Run[];
+}
+export declare class Runner<C = unknown, D = unknown> {
+    private readonly options;
+    private readonly flows;
+    constructor(options: AgentOptions<C, D>);
+    begin(input: TurnInput<C, D>): Turn<C, D>;
+    private ingest;
+    /** The lead wrote: every run parked on a timer `wait` with `else` takes `else`, oldest first. */
+    private resolveReplyWaits;
+    /** Honoured only by the run whose `waiting.key` equals it (I3). */
+    private runWake;
+    /** `silence:<flowId>:<sessionId>:<lastAssistantAtMs>`, honoured only while the blob still shows that silence. */
+    private silenceWake;
+    private ignore;
+    private takeFloor;
+    private startRun;
+    /** Always-claims keep the last 50 per flow and anchor; once/cooldown keys (empty nonce) are never pruned. */
+    private pruneAlwaysClaims;
+    private anchorOf;
+    private claimAt;
+    private repeatAllows;
+    /** A run as it would be if started now, for trigger-level predicates. */
+    private draftRun;
+    private holds;
+    private leadWroteSince;
+    private snap;
+    private stepOf;
+    private stepKey;
+    private scope;
+    private asker;
+    private outcome;
+    understandRequest(turn: Turn<C, D>): UnderstandRequest<C, D> | null;
+    /** The host's history for this turn; the session's own (playground) is the fallback. */
+    private historyOf;
+    /** The asker, or the run that took the floor in Ingest. */
+    private floorRun;
+    /** `message` flows with a non-empty list passing `if` and `repeat`, in flow order. */
+    private eligibleMessageFlows;
+    private messageFlows;
+    /** Every `mention` flow with its trigger, in flow order. `if` and `repeat` are judged at start, when `extract` is in hand. */
+    private mentionFlows;
+    decide(turn: Turn<C, D>, understanding: Understanding | null): void;
+    private fireBranch;
+    /** Validate a raw extracted value and write it; unknown or invalid values leave an outcome line instead. */
+    private writeField;
+    advance(turn: Turn<C, D>): Promise<TalkRequest<C, D> | IdleRequest<C, D> | null>;
+    /**
+     * Everything Speak needs for this turn's one speaker. Instructions are agent,
+     * then flow, then step (idle: agent, then idle), each already judged by its
+     * `if`; tools are the step's list, else the flow's, else every agent tool.
+     */
+    speakRequest(turn: Turn<C, D>, talk: TalkRequest<C, D> | IdleRequest<C, D>): SpeakRequest<C, D>;
+    private speaker;
+    private drain;
+    private move;
+    /** `while` (default: the trigger's `if`) with fresh context; silence runs add "no lead message since the run started". */
+    private premiseHolds;
+    private execute;
+    /** The step `then` leads to, when it is a step of this flow. */
+    private peek;
+    private reportMaxAsks;
+    private follow;
+    /** Start a child flow that holds the floor and moves in this same phase. */
+    private chain;
+    private jump;
+    /** Entering a step is what mints a new visit, and with it new action and message keys (I4). */
+    private enter;
+    private finishFlow;
+    private endRun;
+    private park;
+    /** When nobody asks, the most recently suspended run returns to asking. */
+    private resumeSuspended;
+    settle(turn: Turn<C, D>, outcome: SpeakOutcome | null): Promise<void>;
+    private applySpoken;
+    /** The provider failed: park the talk step under a retry wake, or stop trying. */
+    private deferTalk;
+    /** When to try again, or `null` when trying again cannot help. */
+    private retryAt;
+    /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+    private armSilence;
+    finish(turn: Turn<C, D>): TurnResult<D>;
+}
+//# sourceMappingURL=Runner.d.ts.map