@laserdata/laser-sdk 0.0.1-rc.2 → 0.0.1-rc.3

package/dist/agent/replies.js

@@ -0,0 +1,175 @@
+import { CancelledError, TimeoutError } from "../client/errors.js";
+import { decodeAgentMessage } from "./reliable-consumer.js";
+const REPLY_BATCH = 200;
+const REPLY_POLL_INTERVAL_MS = 20;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function raceWithTimeout(promise, timeoutMs, onDone, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            onDone();
+            reject(new CancelledError("reply wait aborted", { cause: signal?.reason }));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            onDone();
+            reject(new TimeoutError("reply"));
+        }, timeoutMs);
+        if (signal?.aborted === true) {
+            abort();
+            return;
+        }
+        signal?.addEventListener("abort", abort, { once: true });
+        promise
+            .then((value) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            resolve(value);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+export class ReplyHub {
+    transport;
+    stream;
+    topic;
+    waiters = new Map();
+    streamWaiters = new Map();
+    stopped = false;
+    constructor(transport, stream, topic) {
+        this.transport = transport;
+        this.stream = stream;
+        this.topic = topic;
+    }
+    static async create(transport, stream, topic) {
+        const hub = new ReplyHub(transport, stream, topic);
+        const offsets = await hub.seedTailOffsets();
+        void hub.runDispatchLoop(offsets);
+        return hub;
+    }
+    subscribe(correlation) {
+        let settle;
+        const reply = new Promise((resolve) => {
+            settle = resolve;
+        });
+        this.waiters.set(correlation, settle);
+        return {
+            wait: (timeoutMs, signal) => raceWithTimeout(reply, timeoutMs, () => this.waiters.delete(correlation), signal),
+            cancel: () => this.waiters.delete(correlation)
+        };
+    }
+    subscribeStream(correlation) {
+        const waiter = { queued: [], pending: [] };
+        this.streamWaiters.set(correlation, waiter);
+        return {
+            next: (timeoutMs, signal) => {
+                const queued = waiter.queued.shift();
+                if (queued !== undefined)
+                    return Promise.resolve(queued);
+                let settle;
+                const reply = new Promise((resolve) => {
+                    settle = resolve;
+                });
+                const pending = settle;
+                waiter.pending.push(pending);
+                return raceWithTimeout(reply, timeoutMs, () => {
+                    const index = waiter.pending.indexOf(pending);
+                    if (index !== -1)
+                        waiter.pending.splice(index, 1);
+                }, signal);
+            },
+            cancel: () => this.streamWaiters.delete(correlation)
+        };
+    }
+    stop() {
+        this.stopped = true;
+    }
+    async seedTailOffsets() {
+        const partitionCount = await this.transport.findTopicPartitionCount(this.stream, this.topic);
+        if (partitionCount === undefined)
+            return [];
+        const offsets = new Array(partitionCount).fill(0n);
+        for (let partitionId = 0; partitionId < partitionCount; partitionId += 1) {
+            const target = { kind: "single", partitionId };
+            const polled = await this.transport.pollMessages(this.stream, this.topic, target, { kind: "last" }, 1, false);
+            const last = polled[polled.length - 1];
+            if (last !== undefined)
+                offsets[partitionId] = last.offset + 1n;
+        }
+        return offsets;
+    }
+    async runDispatchLoop(initialOffsets) {
+        let offsets = [...initialOffsets];
+        while (!this.stopped) {
+            let partitionCount;
+            try {
+                partitionCount = await this.transport.findTopicPartitionCount(this.stream, this.topic);
+            }
+            catch {
+                await delay(REPLY_POLL_INTERVAL_MS);
+                continue;
+            }
+            if (partitionCount === undefined) {
+                await delay(REPLY_POLL_INTERVAL_MS);
+                continue;
+            }
+            if (offsets.length < partitionCount) {
+                offsets = [...offsets, ...new Array(partitionCount - offsets.length).fill(0n)];
+            }
+            let dispatched = false;
+            for (let partitionId = 0; partitionId < partitionCount; partitionId += 1) {
+                dispatched = (await this.dispatchPartition(partitionId, offsets)) || dispatched;
+            }
+            if (!dispatched)
+                await delay(REPLY_POLL_INTERVAL_MS);
+        }
+    }
+    async dispatchPartition(partitionId, offsets) {
+        const target = { kind: "single", partitionId };
+        const from = offsets[partitionId] ?? 0n;
+        let batch;
+        try {
+            batch = await this.transport.pollMessages(this.stream, this.topic, target, { kind: "offset", value: from }, REPLY_BATCH, false);
+        }
+        catch {
+            return false;
+        }
+        let dispatched = false;
+        for (const message of batch) {
+            offsets[partitionId] = message.offset + 1n;
+            if (this.dispatchMessage(partitionId, message))
+                dispatched = true;
+        }
+        return dispatched;
+    }
+    dispatchMessage(partitionId, message) {
+        const decoded = decodeAgentMessage({ ...message, partitionId });
+        if (decoded.kind === "error")
+            return false;
+        const reply = decoded.message;
+        const correlation = reply.provenance.correlationId;
+        if (correlation === undefined)
+            return false;
+        const waiter = this.waiters.get(correlation);
+        if (waiter !== undefined) {
+            this.waiters.delete(correlation);
+            waiter(reply);
+        }
+        const streamWaiter = this.streamWaiters.get(correlation);
+        if (streamWaiter !== undefined) {
+            const pending = streamWaiter.pending.shift();
+            if (pending === undefined)
+                streamWaiter.queued.push(reply);
+            else
+                pending(reply);
+        }
+        return waiter !== undefined || streamWaiter !== undefined;
+    }
+}
+//# sourceMappingURL=replies.js.map

package/dist/agent/replies.js.map

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

package/dist/agent/router.d.ts

@@ -0,0 +1,72 @@
+import type { Provenance } from "../provenance/provenance.js";
+import type { AgentId, PrincipalId } from "../types/ids.js";
+import type { CapabilityDescriptor } from "../wire/agent.js";
+import type { AgentRegistry, RegisteredCard } from "./registry.js";
+export type { RegisteredCard } from "./registry.js";
+export type RoutePolicy = {
+    readonly kind: "cheapest";
+} | {
+    readonly kind: "fastest";
+} | {
+    readonly kind: "leastLoaded";
+} | {
+    readonly kind: "sticky";
+    readonly agent: AgentId;
+} | {
+    readonly kind: "any";
+} | {
+    readonly kind: "custom";
+    readonly scorer: RouteScorer;
+};
+export declare const ANY_ROUTE_POLICY: RoutePolicy;
+export interface RouteCandidate {
+    readonly agent: AgentId;
+    readonly card: RegisteredCard;
+    readonly capability?: CapabilityDescriptor;
+}
+export interface RouteScorer {
+    select(skillId: string, candidates: readonly RouteCandidate[]): number | undefined;
+}
+export interface CapabilitySelector {
+    readonly skill: string;
+    readonly policy: RoutePolicy;
+    readonly principal?: PrincipalId;
+}
+export declare function capabilitySelector(skill: string, policy: RoutePolicy, principal?: PrincipalId): CapabilitySelector;
+export type Router = {
+    readonly kind: "to";
+    readonly agent: AgentId;
+} | {
+    readonly kind: "toPrincipal";
+    readonly agent: AgentId;
+    readonly principal: PrincipalId;
+} | {
+    readonly kind: "broadcast";
+} | {
+    readonly kind: "toCapable";
+    readonly selector: CapabilitySelector;
+} | {
+    readonly kind: "allCapable";
+    readonly selector: CapabilitySelector;
+};
+export declare function routeTo(agent: AgentId): Router;
+export declare function routeToPrincipal(agent: AgentId, principal: PrincipalId): Router;
+export declare function routeBroadcast(): Router;
+export declare function routeToCapable(skill: string, policy: RoutePolicy): Router;
+export declare function routeAllCapable(skill: string, policy: RoutePolicy): Router;
+export declare function applyRoute(router: Router, provenance: Provenance): Provenance;
+export declare function routeRequiresPresence(router: Router): boolean;
+export declare function requiredPrincipal(router: Router): PrincipalId | undefined;
+export declare function filterCandidatesByPrincipal(candidates: readonly RegisteredCard[], required: PrincipalId, principalFor: (agent: AgentId) => PrincipalId | undefined): readonly RegisteredCard[];
+export declare function selectRoute(skillId: string, candidates: readonly RegisteredCard[], policy: RoutePolicy): AgentId | undefined;
+type RegistryView = Pick<AgentRegistry, "principalFor" | "resolve">;
+export declare function resolveTargets(router: Router, registry: RegistryView, nowMicros: bigint): readonly AgentId[];
+export type InboxRoute = {
+    readonly kind: "advertised";
+} | {
+    readonly kind: "fixed";
+    readonly topic: string;
+};
+export declare const ADVERTISED_INBOX_ROUTE: InboxRoute;
+export declare function resolveInboxRoute(route: InboxRoute, agent: AgentId, advertised: string | undefined): string;
+//# sourceMappingURL=router.d.ts.map

package/dist/agent/router.d.ts.map

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

package/dist/agent/router.js

@@ -0,0 +1,172 @@
+import { RoutingError } from "../client/errors.js";
+export const ANY_ROUTE_POLICY = { kind: "any" };
+export function capabilitySelector(skill, policy, principal) {
+    return { skill, policy, ...(principal !== undefined ? { principal } : {}) };
+}
+export function routeTo(agent) {
+    return { kind: "to", agent };
+}
+export function routeToPrincipal(agent, principal) {
+    return { kind: "toPrincipal", agent, principal };
+}
+export function routeBroadcast() {
+    return { kind: "broadcast" };
+}
+export function routeToCapable(skill, policy) {
+    return { kind: "toCapable", selector: capabilitySelector(skill, policy) };
+}
+export function routeAllCapable(skill, policy) {
+    return { kind: "allCapable", selector: capabilitySelector(skill, policy) };
+}
+export function applyRoute(router, provenance) {
+    switch (router.kind) {
+        case "to":
+        case "toPrincipal":
+            return { ...provenance, targetAgentId: router.agent };
+        case "broadcast":
+        case "toCapable":
+        case "allCapable": {
+            const { targetAgentId, ...rest } = provenance;
+            void targetAgentId;
+            return rest;
+        }
+    }
+}
+export function routeRequiresPresence(router) {
+    if (router.kind === "toPrincipal")
+        return true;
+    if (router.kind === "toCapable" || router.kind === "allCapable") {
+        return router.selector.principal !== undefined;
+    }
+    return false;
+}
+export function requiredPrincipal(router) {
+    switch (router.kind) {
+        case "toPrincipal":
+            return router.principal;
+        case "toCapable":
+        case "allCapable":
+            return router.selector.principal;
+        case "to":
+        case "broadcast":
+            return undefined;
+    }
+}
+export function filterCandidatesByPrincipal(candidates, required, principalFor) {
+    return candidates.filter((card) => principalFor(card.agent)?.get() === required.get());
+}
+const DEFAULT_COST_CLASS = 255;
+const DEFAULT_LATENCY_CLASS = 255;
+const DEFAULT_LOAD = 65_535;
+function minBy(items, key) {
+    let best;
+    let bestKey = Number.POSITIVE_INFINITY;
+    for (const item of items) {
+        const candidateKey = key(item);
+        if (candidateKey < bestKey) {
+            bestKey = candidateKey;
+            best = item;
+        }
+    }
+    return best;
+}
+function candidateView(skillId, candidates) {
+    return candidates.map((card) => {
+        const capability = card.card.capabilities.find((entry) => entry.skillId === skillId);
+        return { agent: card.agent, card, ...(capability !== undefined ? { capability } : {}) };
+    });
+}
+export function selectRoute(skillId, candidates, policy) {
+    const view = candidateView(skillId, candidates);
+    let chosen;
+    switch (policy.kind) {
+        case "any":
+            chosen = view[0];
+            break;
+        case "sticky":
+            chosen = view.find((candidate) => candidate.agent.equals(policy.agent)) ?? view[0];
+            break;
+        case "cheapest":
+            chosen = minBy(view, (candidate) => candidate.capability?.costClass ?? DEFAULT_COST_CLASS);
+            break;
+        case "fastest":
+            chosen = minBy(view, (candidate) => candidate.capability?.latencyClass ?? DEFAULT_LATENCY_CLASS);
+            break;
+        case "leastLoaded":
+            chosen = minBy(view, (candidate) => candidate.capability?.load ?? DEFAULT_LOAD);
+            break;
+        case "custom": {
+            const index = policy.scorer.select(skillId, view);
+            chosen = index !== undefined ? view[index] : undefined;
+            break;
+        }
+    }
+    return chosen?.agent;
+}
+function principalMismatch(registry, agent, expected) {
+    const actual = registry.principalFor(agent)?.get();
+    return new RoutingError(`agent \`${agent.asString()}\` is not authenticated as principal ${expected.get().toString()}`, {
+        kind: "principalMismatch",
+        agent: agent.asString(),
+        expected: expected.get(),
+        ...(actual !== undefined ? { actual } : {})
+    });
+}
+function trustedCandidates(registry, selector, nowMicros) {
+    const candidates = registry.resolve(selector.skill, nowMicros);
+    if (selector.principal === undefined)
+        return candidates;
+    const trusted = filterCandidatesByPrincipal(candidates, selector.principal, (agent) => registry.principalFor(agent));
+    const first = candidates[0];
+    if (trusted.length === 0 && first !== undefined) {
+        throw principalMismatch(registry, first.agent, selector.principal);
+    }
+    return trusted;
+}
+export function resolveTargets(router, registry, nowMicros) {
+    switch (router.kind) {
+        case "to":
+            return [router.agent];
+        case "toPrincipal":
+            if (registry.principalFor(router.agent)?.get() !== router.principal.get()) {
+                throw principalMismatch(registry, router.agent, router.principal);
+            }
+            return [router.agent];
+        case "broadcast":
+            return [];
+        case "toCapable": {
+            const candidates = trustedCandidates(registry, router.selector, nowMicros);
+            const selected = selectRoute(router.selector.skill, candidates, router.selector.policy);
+            if (selected === undefined) {
+                throw new RoutingError(`no live agent advertises capability \`${router.selector.skill}\``, {
+                    kind: "noCapableAgent",
+                    skill: router.selector.skill
+                });
+            }
+            return [selected];
+        }
+        case "allCapable": {
+            const candidates = trustedCandidates(registry, router.selector, nowMicros);
+            if (candidates.length === 0) {
+                throw new RoutingError(`no live agent advertises capability \`${router.selector.skill}\``, {
+                    kind: "noCapableAgent",
+                    skill: router.selector.skill
+                });
+            }
+            return candidates.map((card) => card.agent);
+        }
+    }
+}
+export const ADVERTISED_INBOX_ROUTE = { kind: "advertised" };
+export function resolveInboxRoute(route, agent, advertised) {
+    if (route.kind === "fixed")
+        return route.topic;
+    if (advertised === undefined) {
+        throw new RoutingError(`no inbox advertised for agent \`${agent.asString()}\``, {
+            kind: "noInbox",
+            agent: agent.asString()
+        });
+    }
+    return advertised;
+}
+//# sourceMappingURL=router.js.map

package/dist/agent/router.js.map

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

package/dist/agent/scope.d.ts

@@ -0,0 +1,16 @@
+import type { BytesLike } from "../client/bytes.js";
+import type { Laser } from "../client/laser.js";
+import type { Provenance } from "../provenance/provenance.js";
+import type { AgentId } from "../types/ids.js";
+import type { AgentCard, CapabilityDescriptor } from "../wire/agent.js";
+import type { AgentMessage } from "./reliable-consumer.js";
+export declare class AgentScope {
+    private readonly laser;
+    readonly id: AgentId;
+    constructor(laser: Laser, id: AgentId);
+    send(topic: string, payload: BytesLike, provenance: Provenance): Promise<void>;
+    ask(requestTopic: string, replyTopic: string, payload: BytesLike, provenance: Provenance, timeoutMs: number, signal?: AbortSignal): Promise<AgentMessage>;
+    publishCard(card: AgentCard): Promise<void>;
+    advertise(listenOn: string, capabilities: readonly CapabilityDescriptor[]): Promise<void>;
+}
+//# sourceMappingURL=scope.d.ts.map

package/dist/agent/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/agent/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO;IAFtB,YACmB,KAAK,EAAE,KAAK,EACpB,EAAE,EAAE,OAAO,EAClB;IAEJ,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E;IAED,GAAG,CACD,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,EAClB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,CAAC,CASvB;IAED,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1C;IAEK,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAW9F;CACF"}

package/dist/agent/scope.js

@@ -0,0 +1,34 @@
+import { PresenceConflictError } from "../client/errors.js";
+export class AgentScope {
+    laser;
+    id;
+    constructor(laser, id) {
+        this.laser = laser;
+        this.id = id;
+    }
+    send(topic, payload, provenance) {
+        return this.laser.sendAgent(topic, payload, { ...provenance, agent: this.id });
+    }
+    ask(requestTopic, replyTopic, payload, provenance, timeoutMs, signal) {
+        return this.laser.request(requestTopic, replyTopic, payload, { ...provenance, agent: this.id }, timeoutMs, signal);
+    }
+    publishCard(card) {
+        return this.laser.publishCard(this.id, card);
+    }
+    async advertise(listenOn, capabilities) {
+        try {
+            await this.publishCard({ capabilities });
+        }
+        catch {
+            // Presence remains useful when card publication is unavailable.
+        }
+        try {
+            await this.laser.advertisePresence({ agent: this.id, inbox: listenOn });
+        }
+        catch (error) {
+            if (error instanceof PresenceConflictError)
+                throw error;
+        }
+    }
+}
+//# sourceMappingURL=scope.js.map

package/dist/agent/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/agent/scope.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAO3D,MAAM,OAAO,UAAU;IAEF,KAAK;IACb,EAAE;IAFb,YACmB,KAAY,EACpB,EAAW;qBADH,KAAK;kBACb,EAAE;IACV,CAAC;IAEJ,IAAI,CAAC,KAAa,EAAE,OAAkB,EAAE,UAAsB;QAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;IAChF,CAAC;IAED,GAAG,CACD,YAAoB,EACpB,UAAkB,EAClB,OAAkB,EAClB,UAAsB,EACtB,SAAiB,EACjB,MAAoB;QAEpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,YAAY,EACZ,UAAU,EACV,OAAO,EACP,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,EACjC,SAAS,EACT,MAAM,CACP,CAAA;IACH,CAAC;IAED,WAAW,CAAC,IAAe;QACzB,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC9C,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,YAA6C;QAC7E,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;QACzE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,qBAAqB;gBAAE,MAAM,KAAK,CAAA;QACzD,CAAC;IACH,CAAC;CACF"}

package/dist/agent/workflow.d.ts

@@ -0,0 +1,85 @@
+import { type BytesLike } from "../client/bytes.js";
+import type { Laser } from "../client/laser.js";
+import { ConversationId } from "../types/ids.js";
+import { type InboxRoute, type Router } from "./router.js";
+export declare class Budget {
+    readonly tokenLimit?: bigint | undefined;
+    readonly wallClockLimitMs?: number | undefined;
+    readonly invocationLimit?: number | undefined;
+    private constructor();
+    static unlimited(): Budget;
+    static tokens(tokens: bigint): Budget;
+    wallClock(milliseconds: number): Budget;
+    invocations(invocations: number): Budget;
+}
+export interface StepContext {
+    readonly outputs: ReadonlyMap<string, Uint8Array>;
+}
+export type StepFn = (context: StepContext) => BytesLike | Promise<BytesLike>;
+export type WorkflowVerifier = (output: Uint8Array) => boolean | Promise<boolean>;
+export type OnTimeout = "fail" | "reassign";
+interface Step {
+    readonly label: string;
+    readonly target: Router;
+    readonly build: StepFn;
+    readonly after: string[];
+    verifier?: WorkflowVerifier;
+    exclusive: boolean;
+    fenceNamespace?: string;
+    onTimeout: OnTimeout;
+    compensation?: StepFn;
+}
+export interface WorkflowOutcome {
+    readonly outputs: ReadonlyMap<string, Uint8Array>;
+    readonly runId: ConversationId;
+}
+export interface WorkflowRunOptions {
+    readonly signal?: AbortSignal;
+}
+export declare function topologicalOrder(steps: readonly Pick<Step, "label" | "after">[]): readonly number[];
+export declare class Workflow {
+    private readonly laser;
+    readonly name: string;
+    private budgetValue;
+    private route;
+    private resumeId;
+    private readonly steps;
+    private registerRun;
+    constructor(laser: Laser, name: string);
+    budget(budget: Budget): this;
+    inboxRoute(route: InboxRoute): this;
+    runId(runId: ConversationId): this;
+    registered(): this;
+    step(label: string, target: Router, build: StepFn): StepBuilder;
+    run(options?: WorkflowRunOptions): Promise<WorkflowOutcome>;
+    private execute;
+    private validateStep;
+    private checkDispatchFloor;
+    private dispatch;
+    private dispatchExclusive;
+    private replay;
+    private journal;
+    private compensate;
+    private stepDeadline;
+    private checkBudget;
+}
+export declare class StepBuilder {
+    private readonly owner;
+    private readonly current;
+    constructor(owner: Workflow, current: Step);
+    after(label: string): this;
+    verifyWith(verifier: WorkflowVerifier): this;
+    exclusive(): this;
+    exclusiveIn(namespace: string): this;
+    onTimeout(onTimeout: OnTimeout): this;
+    compensateWith(compensation: StepFn): this;
+    budget(budget: Budget): this;
+    inboxRoute(route: InboxRoute): this;
+    runId(runId: ConversationId): this;
+    registered(): this;
+    step(label: string, target: Router, build: StepFn): StepBuilder;
+    done(): Workflow;
+    run(options?: WorkflowRunOptions): Promise<WorkflowOutcome>;
+}
+export {};
+//# sourceMappingURL=workflow.d.ts.map

package/dist/agent/workflow.d.ts.map

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