@falai/agent 3.4.4 → 4.0.0-alpha.1

package/dist/cjs/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

package/dist/cjs/core/Runner.d.ts.map

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