@nexalab/agent-sdk 0.1.6 → 0.1.8

package/dist/guided-flows/runtime.d.ts

@@ -6,6 +6,7 @@ import type { EventBus } from "../event-bus.js";
 import type { SkillDefinition } from "../skills.js";
 import { type TenantContext } from "../tenancy.js";
 import type { JsonObject } from "../types.js";
+import { type PublishFlowEventInput } from "./events.js";
 import type { GuidedFlowStateStore } from "./persistence.js";
 import type { FlowStatePatch, GuidedFlow, GuidedFlowRunMeta, GuidedFlowRunState } from "./types.js";
 export type GuidedFlowRuntimeOptions = {
@@ -30,6 +31,33 @@ export type GuidedFlowTurnInput = {
     sessionId: string;
     tenant?: TenantContext;
     explicitFlow?: string;
+    /**
+     * Known facts to seed into `state` before this flow run's first turn —
+     * e.g. a `customerId` a WhatsApp gateway already resolved from the phone
+     * number, or a `locale` carried over from session context. Applied once,
+     * only while creating a brand-new flow run (`!existing` — an already
+     * in-progress flow ignores it; use `flows.patchState()` to update a
+     * running flow instead). Goes through the exact same
+     * `applyStatePatch`/`protectedFields` path as any other patch, with
+     * `source: "system"` — unknown keys are dropped, but (unlike a
+     * model-sourced patch) tool-reserved fields may be set, since this is the
+     * caller vouching for the value, not the model guessing it. Applied
+     * before step resolution and the extraction call, so both the active
+     * step and "Known so far" in the model's instructions already reflect it.
+     */
+    initialState?: JsonObject;
+    /** Propagated to the extraction call and the tool-scoped reply pass so a caller (e.g. the Gateway) can cancel an in-flight turn. Additive — omitting it is byte-identical to previous behavior. */
+    signal?: AbortSignal;
+    /**
+     * Turn-scoped event sink, called synchronously alongside every existing
+     * `publishFlowEvent` call in this turn — same events, same payloads,
+     * just also delivered directly to this caller instead of only through
+     * the shared `EventBus`. This is what lets a caller stream a single
+     * turn's events without subscribing to (and filtering) the agent-wide
+     * bus. Purely additive: omitting it changes nothing about how this
+     * turn executes or what it returns.
+     */
+    onEvent?: (event: PublishFlowEventInput) => void;
 };
 export type GuidedFlowTurnOutcome = {
     handled: false;
@@ -54,6 +82,8 @@ export declare class GuidedFlowRuntime {
     private requireFlow;
     private soleFlow;
     private key;
+    /** Publishes onto the shared EventBus (unchanged behavior) and, if this turn supplied one, also delivers the same event directly to the turn-scoped sink. */
+    private announce;
     selectFlow(input: {
         text: string;
         sessionId: string;
@@ -62,6 +92,31 @@ export declare class GuidedFlowRuntime {
     }): Promise<GuidedFlow | undefined>;
     runTurn(input: GuidedFlowTurnInput): Promise<GuidedFlowTurnOutcome>;
     private driveFlow;
+    /** The model-driven reply pass: composes text and may call the active step's tools. Only reached when a step has no `prompt`, or does but still has tools available (e.g. a validation step, which needs the model to react to a tool result/error dynamically). */
+    private runReplyPass;
+    /**
+     * Deterministically calls a step's single applicable tool when its arguments are fully
+     * resolvable without asking a model to decide anything. Covers two shapes:
+     *
+     * 1. A silent tool-only step (no `collect`, exactly one required tool) where every input
+     *    property already resolves to a known value in `state` (matched by property name,
+     *    case-insensitively — the generator's convention of lowercase-flattened field names makes
+     *    this a reliable match in practice).
+     * 2. A `collect` step whose only useful action is resolving the user's free text against a
+     *    dynamic list (an address, a product, a time slot): exactly one tool in `tools.allowed`
+     *    has a `verbatimTextArg` mapping configured. Which tool to call isn't ambiguous and the
+     *    argument that matters most — the user's own words — is already pinned to the raw turn
+     *    text, so there's nothing left for a model to compose either. (Caught live: asked to do
+     *    the exact same thing, a model sometimes narrates — "voy a consultar..." — instead of
+     *    actually emitting the tool call, leaving the user with a blank reply.)
+     *
+     * Returns `undefined` — never partially constructed input — the moment any other required
+     * property can't be confidently resolved, so the caller falls back to the model-driven
+     * `runReplyPass` exactly as before. Bypasses the harness too: this never asks a model
+     * anything, so a custom `ModelHarness` has nothing to intercept here (same reasoning as the
+     * `step.prompt` verbatim path).
+     */
+    private tryAutoInvokeRequiredTool;
     private applyPatch;
     private announceStepChange;
     private forwardNativeEvent;

package/dist/guided-flows/runtime.d.ts.map

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