botmux 2.33.0 → 2.34.0

package/dist/workflows/hostExecutors/protocol.js

@@ -0,0 +1,181 @@
+import { writeJsonBlob } from '../blob.js';
+import { computeInputHash, deriveIdempotencyKey } from '../events/idempotency.js';
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Drive the side-effecting protocol for one attempt (events doc v0.1.2
+ * §2.3, §4.3).  Writes three events in order:
+ *
+ *   1. `effectAttempted` — written **before** invoking the provider so a
+ *      crash mid-call leaves a dangling intent that resume can reconcile.
+ *   2. provider invocation (via `executor.invoke`).
+ *   3. `activitySucceeded` OR `activityFailed` — terminal event for this
+ *      attempt; carries `externalRefs` on success or classified error on
+ *      failure.
+ *
+ * The protocol does NOT write `attemptCreated/leaseSigned/activityRunning`
+ * — those are the scheduler/worker layer's responsibility.  This function
+ * assumes the caller has already advanced the activity to `running`.
+ *
+ * The protocol does NOT do retry/backoff — that's the scheduler's job
+ * (Step 7+).  A failed invocation is reported via `ok: false` and the
+ * caller decides whether to spawn a new `attemptCreated`.
+ *
+ * Idempotency contract:
+ *   - `idempotencyKey` is deterministic per attempt (5-tuple hash), so
+ *     re-running the same attempt with the same input produces the same
+ *     uuid → Feishu/schedule provider returns the original ref.
+ *   - `inputHash` is recorded for the resume path to detect attempt
+ *     mutability violations (Step 7).  This function doesn't enforce
+ *     immutability across calls — Step 7 reads recorded inputHash and
+ *     fails if a future attempt re-derives a different one.
+ */
+export async function executeSideEffect(ctx, input, executor) {
+    const idempotencyKey = deriveIdempotencyKey({
+        workflowId: ctx.workflowId,
+        revisionId: ctx.revisionId,
+        runId: ctx.runId,
+        nodeId: ctx.nodeId,
+        attemptId: ctx.attemptId,
+    });
+    const inputHash = computeInputHash(executor.canonicalInput(input));
+    // 1. effectAttempted — written BEFORE invoking the provider so a crash
+    //    mid-call leaves a dangling effectAttempted for resume to reconcile.
+    await ctx.log.append({
+        runId: ctx.runId,
+        type: 'effectAttempted',
+        actor: 'hostExecutor',
+        payload: {
+            activityId: ctx.activityId,
+            attemptId: ctx.attemptId,
+            idempotencyKey,
+            inputHash,
+            idempotencyTtlMs: executor.idempotencyTtlMs,
+            provider: executor.provider,
+        },
+    });
+    // 2. provider invocation
+    try {
+        const { output, externalRefs } = await executor.invoke(input, idempotencyKey);
+        // 3a. activitySucceeded.  outputRef points at a real JSON blob
+        //     `{ output, externalRefs }` so dashboard / CLI show / reconcile
+        //     evidence can inspect the full provider response without
+        //     replaying events.  We keep `externalRefs` on the event payload
+        //     too — replay/reconciler reads it without touching disk.
+        //
+        //     Non-plain-JSON outputs (Date, Map, Set, Buffer, BigInt,
+        //     function) are rejected here so they fall through the same
+        //     classifier path as a provider crash.  Executors must return
+        //     plain JSON-serializable values; silently coercing a Date to
+        //     `{}` would corrupt the audit trail.
+        assertJsonPlain(output, 'output');
+        assertJsonPlain(externalRefs, 'externalRefs');
+        const outputRef = await writeJsonBlob(ctx.log, { output, externalRefs });
+        const successEvent = (await ctx.log.append({
+            runId: ctx.runId,
+            type: 'activitySucceeded',
+            actor: 'hostExecutor',
+            payload: {
+                activityId: ctx.activityId,
+                attemptId: ctx.attemptId,
+                outputRef,
+                externalRefs,
+            },
+        }));
+        return { ok: true, event: successEvent, output, externalRefs };
+    }
+    catch (err) {
+        // 3b. activityFailed.  Map via the executor's classifier when
+        //     present; default to UnknownProviderError/manual (codex round 2
+        //     — TTL/unknown failures need human resolution, not silent retry).
+        const classification = executor.classifyError?.(err) ?? defaultClassification(err);
+        // Truncate uniformly — protects against custom classifiers that
+        // return long messages (e.g. dumping a full provider response).
+        const safeMessage = truncateMessage(classification.errorMessage);
+        const failedEvent = (await ctx.log.append({
+            runId: ctx.runId,
+            type: 'activityFailed',
+            actor: 'hostExecutor',
+            payload: {
+                activityId: ctx.activityId,
+                attemptId: ctx.attemptId,
+                error: {
+                    errorCode: classification.errorCode,
+                    errorClass: classification.errorClass,
+                    errorMessage: safeMessage,
+                },
+            },
+        }));
+        return {
+            ok: false,
+            event: failedEvent,
+            error: { ...classification, errorMessage: safeMessage },
+        };
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Error-message truncation budget.  The schema bound is 4096 (events doc
+ * §3.3), but the envelope payload also has to fit `INLINE_PAYLOAD_MAX_BYTES`
+ * (4096) total — so a 4096-char message alone would overflow the event
+ * envelope cap after JSON encoding + other fields.  Truncate to leave
+ * headroom; large error bodies should be written to a stackRef blob.
+ */
+const ERROR_MESSAGE_MAX_CHARS = 2048;
+function truncateMessage(msg) {
+    return msg.length > ERROR_MESSAGE_MAX_CHARS
+        ? msg.slice(0, ERROR_MESSAGE_MAX_CHARS - 3) + '...'
+        : msg;
+}
+function defaultClassification(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+        errorCode: 'UnknownProviderError',
+        errorClass: 'manual',
+        errorMessage: truncateMessage(msg),
+    };
+}
+/**
+ * Reject non-plain-JSON values before they reach `writeJsonBlob`, where
+ * `canonicalJsonStringify` would silently coerce a Date / Map / Set into
+ * `{}`.  Path-prefixed error messages so the classifier can surface
+ * which field tripped it.
+ */
+function assertJsonPlain(value, path) {
+    if (value === null)
+        return;
+    const t = typeof value;
+    if (t === 'string' || t === 'number' || t === 'boolean' || t === 'undefined') {
+        // `undefined` is JSON-omitted, not a serialization failure — only
+        // reject the explicitly hostile types below.
+        return;
+    }
+    if (t === 'bigint') {
+        throw new Error(`hostExecutor output not JSON-serializable at ${path}: BigInt`);
+    }
+    if (t === 'function' || t === 'symbol') {
+        throw new Error(`hostExecutor output not JSON-serializable at ${path}: ${t}`);
+    }
+    if (value instanceof Date) {
+        throw new Error(`hostExecutor output not JSON-serializable at ${path}: Date (use .toISOString() string)`);
+    }
+    if (value instanceof Map || value instanceof Set) {
+        throw new Error(`hostExecutor output not JSON-serializable at ${path}: ${value.constructor.name}`);
+    }
+    if (Buffer.isBuffer(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+        throw new Error(`hostExecutor output not JSON-serializable at ${path}: binary buffer`);
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => assertJsonPlain(v, `${path}[${i}]`));
+        return;
+    }
+    const obj = value;
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) {
+        const ctorName = obj.constructor?.name ?? 'unknown';
+        throw new Error(`hostExecutor output not JSON-serializable at ${path}: non-plain object (${ctorName})`);
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        assertJsonPlain(v, `${path}.${k}`);
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/workflows/hostExecutors/protocol.js.map

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

package/dist/workflows/hostExecutors/registry.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderReconciler } from '../resume.js';
+import type { SideEffectingExecutor } from './types.js';
+export type RegisteredHostExecutor<Input = unknown, Output = unknown> = {
+    executor: SideEffectingExecutor<Input, Output>;
+    parseInput(input: unknown): Input;
+};
+export type HostExecutorRegistry = Map<string, RegisteredHostExecutor>;
+export declare function createDefaultHostExecutorRegistry(): HostExecutorRegistry;
+export declare function createDefaultProviderReconcilers(): Map<string, ProviderReconciler>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/workflows/hostExecutors/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/workflows/hostExecutors/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAevD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI;IACtE,QAAQ,EAAE,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/C,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAEvE,wBAAgB,iCAAiC,IAAI,oBAAoB,CAwBxE;AAED,wBAAgB,gCAAgC,IAAI,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAKlF"}

package/dist/workflows/hostExecutors/registry.js

@@ -0,0 +1,36 @@
+import { botmuxScheduleExecutor, botmuxScheduleReconciler, parseScheduleInput, } from './botmux-schedule.js';
+import { feishuSendExecutor, parseFeishuSendInput, } from './feishu-send.js';
+import { feishuReplyExecutor, parseFeishuReplyInput, } from './feishu-reply.js';
+import { feishuImReconciler } from './feishu-im.js';
+export function createDefaultHostExecutorRegistry() {
+    return new Map([
+        [
+            'botmux-schedule',
+            {
+                executor: botmuxScheduleExecutor,
+                parseInput: parseScheduleInput,
+            },
+        ],
+        [
+            'feishu-send',
+            {
+                executor: feishuSendExecutor,
+                parseInput: parseFeishuSendInput,
+            },
+        ],
+        [
+            'feishu-reply',
+            {
+                executor: feishuReplyExecutor,
+                parseInput: parseFeishuReplyInput,
+            },
+        ],
+    ]);
+}
+export function createDefaultProviderReconcilers() {
+    return new Map([
+        [botmuxScheduleReconciler.provider, botmuxScheduleReconciler],
+        [feishuImReconciler.provider, feishuImReconciler],
+    ]);
+}
+//# sourceMappingURL=registry.js.map

package/dist/workflows/hostExecutors/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/workflows/hostExecutors/registry.ts"],"names":[],"mappings":"AACA,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAUpD,MAAM,UAAU,iCAAiC;IAC/C,OAAO,IAAI,GAAG,CAAC;QACb;YACE,iBAAiB;YACjB;gBACE,QAAQ,EAAE,sBAAsB;gBAChC,UAAU,EAAE,kBAAkB;aACE;SACnC;QACD;YACE,aAAa;YACb;gBACE,QAAQ,EAAE,kBAAkB;gBAC5B,UAAU,EAAE,oBAAoB;aACA;SACnC;QACD;YACE,cAAc;YACd;gBACE,QAAQ,EAAE,mBAAmB;gBAC7B,UAAU,EAAE,qBAAqB;aACD;SACnC;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gCAAgC;IAC9C,OAAO,IAAI,GAAG,CAAC;QACb,CAAC,wBAAwB,CAAC,QAAQ,EAAE,wBAAwB,CAAC;QAC7D,CAAC,kBAAkB,CAAC,QAAQ,EAAE,kBAAkB,CAAC;KAClD,CAAC,CAAC;AACL,CAAC"}

package/dist/workflows/hostExecutors/types.d.ts

@@ -0,0 +1,78 @@
+import type { EventLog } from '../events/append.js';
+import type { ErrorClass, ErrorCode } from '../events/payloads.js';
+/**
+ * Runtime context handed to every hostExecutor invocation.  The caller
+ * (workflow scheduler/worker) is responsible for already having written:
+ *   - `attemptCreated` (with this `nodeId/activityId/attemptId`)
+ *   - `leaseSigned`
+ *   - `activityRunning`
+ * before invoking the side-effect protocol.  This context only needs the
+ * tuple required to derive `idempotencyKey` plus the event log handle so
+ * the protocol can record its 3 events (`effectAttempted`,
+ * `activitySucceeded`/`activityFailed`).
+ */
+export type HostExecutorContext = {
+    log: EventLog;
+    runId: string;
+    workflowId: string;
+    revisionId: string;
+    nodeId: string;
+    activityId: string;
+    attemptId: string;
+};
+/**
+ * Classified executor error.  Executors that can give precise error codes
+ * (Feishu 230011 etc.) return a typed result; everything else falls back
+ * to `UnknownProviderError` / `manual` (events doc v0.1.2 §3.3).
+ */
+export type ExecutorErrorClassification = {
+    errorCode: ErrorCode;
+    errorClass: ErrorClass;
+    /** Human-readable detail; truncated to 4KB upstream. */
+    errorMessage: string;
+};
+/**
+ * A side-effecting hostExecutor (send / reply / schedule in v0).  Pure
+ * executors (transform / bots / history / quoted / sub-agent) have a
+ * separate interface in `pure.ts` because they skip `effectAttempted`.
+ */
+export interface SideEffectingExecutor<Input, Output> {
+    /** Identifier embedded in `effectAttempted.provider`. */
+    readonly provider: string;
+    /**
+     * Provider TTL.  Feeds `effectAttempted.idempotencyTtlMs` and the
+     * resume reconciler's TTL-vs-manual decision (events doc §4.3.1).
+     */
+    readonly idempotencyTtlMs: number;
+    /**
+     * Convert the typed `Input` into the canonical shape that's hashed
+     * into `effectAttempted.inputHash`.  Codex round 2 / 4 invariant: this
+     * MUST include every field that participates in the external effect
+     * (e.g. for Feishu reply: `receive_id`, `root_message_id`, `msg_type`,
+     * `content`) so that retries can detect input drift.
+     */
+    canonicalInput(input: Input): unknown;
+    /**
+     * Invoke the provider.  `idempotencyKey` is the runtime-derived
+     * dedupe token (≤ 50 chars) that callers should forward to the
+     * provider's idempotency knob (Feishu uuid / schedule task id).
+     */
+    invoke(input: Input, idempotencyKey: string): Promise<{
+        output: Output;
+        /**
+         * Provider-returned identifiers stored in
+         * `activitySucceeded.externalRefs`.  Type-specific (send/reply →
+         * `{ messageId }`, schedule → `{ taskId }`).
+         */
+        externalRefs: Record<string, unknown>;
+    }>;
+    /**
+     * Map an `invoke` error to an event-typed error.  Returning `null`
+     * (or omitting the method) falls back to the protocol default:
+     *   `{ UnknownProviderError, manual }`.
+     * Codex round 2: TTL-class errors are `manual` (need human resolution),
+     * lease/worker/network errors stay `retryable`.
+     */
+    classifyError?(err: unknown): ExecutorErrorClassification | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/workflows/hostExecutors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/workflows/hostExecutors/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,KAAK,EAAE,MAAM;IAClD,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAEtC;;;;OAIG;IACH,MAAM,CACJ,KAAK,EAAE,KAAK,EACZ,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;QACT,MAAM,EAAE,MAAM,CAAC;QACf;;;;WAIG;QACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvC,CAAC,CAAC;IAEH;;;;;;OAMG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,2BAA2B,GAAG,IAAI,CAAC;CAClE"}

package/dist/workflows/hostExecutors/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/workflows/hostExecutors/types.js.map

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

package/dist/workflows/loader.d.ts

@@ -0,0 +1,16 @@
+import { type WorkflowDefinition } from './definition.js';
+export type RunChatBinding = {
+    chatId: string;
+    larkAppId: string;
+};
+type RunFileOptions = {
+    runDir?: string;
+    runsDir?: string;
+};
+export declare function workflowDefinitionSearchPaths(workflowId: string): string[];
+export declare function loadWorkflowDefinition(workflowId: string): Promise<WorkflowDefinition>;
+export declare function snapshotWorkflowDefinition(runId: string, def: WorkflowDefinition, opts?: RunFileOptions): Promise<string>;
+export declare function writeRunChatBinding(runId: string, binding: RunChatBinding, opts?: RunFileOptions): Promise<string>;
+export declare function readRunChatBinding(runId: string, opts?: RunFileOptions): Promise<RunChatBinding>;
+export {};
+//# sourceMappingURL=loader.d.ts.map

package/dist/workflows/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/workflows/loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAM1E;AAED,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkB5F;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,kBAAkB,EACvB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,cAAc,CAAC,CASzB"}

package/dist/workflows/loader.js

@@ -0,0 +1,56 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { canonicalJsonStringify, parseWorkflowDefinition, } from './definition.js';
+import { ensureRunDir } from './runs-dir.js';
+export function workflowDefinitionSearchPaths(workflowId) {
+    const home = process.env.HOME;
+    return [
+        join(process.cwd(), 'workflows', `${workflowId}.workflow.json`),
+        join(home ?? '', '.botmux', 'workflows', `${workflowId}.workflow.json`),
+    ];
+}
+export async function loadWorkflowDefinition(workflowId) {
+    const paths = workflowDefinitionSearchPaths(workflowId);
+    for (const path of paths) {
+        try {
+            const raw = await fs.readFile(path, 'utf-8');
+            return parseWorkflowDefinition(JSON.parse(raw));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue;
+            throw new Error(`Failed to load workflow '${workflowId}' from ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    throw new Error(`Workflow '${workflowId}' not found. Looked in:\n${paths.map((p) => `- ${p}`).join('\n')}`);
+}
+export async function snapshotWorkflowDefinition(runId, def, opts = {}) {
+    const dir = await getOrEnsureRunDir(runId, opts);
+    const path = join(dir, 'workflow.json');
+    await fs.writeFile(path, canonicalJsonStringify(def), 'utf-8');
+    return path;
+}
+export async function writeRunChatBinding(runId, binding, opts = {}) {
+    const dir = await getOrEnsureRunDir(runId, opts);
+    const path = join(dir, 'chat-binding.json');
+    await fs.writeFile(path, JSON.stringify(binding, null, 2), 'utf-8');
+    return path;
+}
+export async function readRunChatBinding(runId, opts = {}) {
+    const dir = await getOrEnsureRunDir(runId, opts);
+    const path = join(dir, 'chat-binding.json');
+    const raw = await fs.readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed.chatId || !parsed.larkAppId) {
+        throw new Error(`Invalid workflow chat binding at ${path}`);
+    }
+    return { chatId: parsed.chatId, larkAppId: parsed.larkAppId };
+}
+async function getOrEnsureRunDir(runId, opts) {
+    if (opts.runDir) {
+        await fs.mkdir(opts.runDir, { recursive: true });
+        return opts.runDir;
+    }
+    return ensureRunDir(runId, opts.runsDir);
+}
+//# sourceMappingURL=loader.js.map

package/dist/workflows/loader.js.map

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

package/dist/workflows/loop.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Orchestrator loop runner.
+ *
+ * Drives `decideNextActions → dispatch* → replay → repeat` until either
+ * the run reaches a terminal status or the orchestrator returns no
+ * actions (which on a non-terminal run means we're paused on an open
+ * `waitCreated`).
+ *
+ * Per-tick dispatch model (v0.1.3+):
+ *   1. Split ready actions into `dispatch*` (gate / work) and `complete*`
+ *      (settle node / run).  The two phases have different concurrency
+ *      semantics — dispatch can race, settles must not.
+ *   2. Within the dispatch phase: cap concurrency by `defaults.maxConcurrency`
+ *      (default 4) and enforce per-bot serialization (one in-flight subagent
+ *      per bot within a tick).  Deferred dispatches just stay in the next
+ *      tick's ready set; no separate scheduling state needed.
+ *   3. Run dispatches via `Promise.allSettled` so a sibling throwing doesn't
+ *      starve the rest.  After settle, replay fresh and patch any non-terminal
+ *      activity with an `activityFailed` (errorClass=fatal, errorCode=
+ *      WorkerCrashed; closest fit in the existing enum — see payloads.ts) —
+ *      but NEVER write a second terminal if the dispatch already wrote one
+ *      before throwing.  If a dispatch throws BEFORE writing `attemptCreated`,
+ *      we have no attempt to attach the failure to; the tick returns
+ *      `no-progress` rather than re-dispatching the same action forever.
+ *   4. Settle actions (`completeNode*` / `completeRun*`) run sequentially so
+ *      event log order stays readable and `completeRun*` is never racy.
+ *
+ * Re-entry: external events (e.g. `waitResolved` written by the lark
+ * card handler) don't drive this loop — the caller is responsible for
+ * invoking `runLoop` again when it knows new events have landed.  See
+ * `src/workflows/fanout.ts` (Slice D-4) for the daemon-side trigger.
+ */
+import { type Snapshot } from './events/replay.js';
+import { type WorkflowRuntimeContext } from './runtime.js';
+export type RunLoopStopReason = 'terminal' | 'awaiting-wait' | 'no-progress' | 'max-ticks';
+export type RunLoopResult = {
+    reason: RunLoopStopReason;
+    ticks: number;
+    lastSnapshot: Snapshot;
+};
+export type RunLoopOptions = {
+    /**
+     * Defensive cap on tick count.  A correctly modeled workflow with N
+     * nodes terminates in O(N) ticks; the cap exists to keep buggy
+     * orchestrator output from spinning forever.  Default 1000.
+     */
+    maxTicks?: number;
+};
+export declare function runLoop(ctx: WorkflowRuntimeContext, options?: RunLoopOptions): Promise<RunLoopResult>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/workflows/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/workflows/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAQH,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAQL,KAAK,sBAAsB,EAC5B,MAAM,cAAc,CAAC;AAStB,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,eAAe,GACf,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,QAAQ,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAsB,OAAO,CAC3B,GAAG,EAAE,sBAAsB,EAC3B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA4KxB"}