@zq-silk/yui 0.2.0 → 0.4.2

package/dist/controller/sessionNotify.js

@@ -1,9 +1,46 @@
-import { callFileTaskController } from "./clientRuntime.js";
-const SESSION_BIND_METHOD = "runtime.session.bind";
-/** Hidden CLI entrypoint used by Codex's structured legacy notify hook. */
-export async function runSessionNotifyCommand(payloadArgument, environment = process.env, call = callFileTaskController) {
+import { callController } from "../core/controllerClient.js";
+import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
+import { yuiRunBodyFromInputMessage, yuiRunIdFromInputMessages } from "../run/runIdentity.js";
+import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
+import { setCodexThreadName } from "../execution/codexThreadNaming.js";
+import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
+const NO_FINAL_ASSISTANT_MESSAGE_SUMMARY = "Native Turn completed without a final assistant message.";
+/** Hidden CLI entrypoint used by Codex's structured notify hook. */
+export async function runSessionNotifyCommand(payloadArgument, environment = process.env, call, setThreadName = setCodexThreadName) {
     const params = parseCodexSessionNotification(payloadArgument, environment);
-    await call(requireText(environment.YUI_HOME, "YUI_HOME"), SESSION_BIND_METHOD, toJson(params));
+    const home = requireText(environment.YUI_HOME, "YUI_HOME");
+    const enqueued = new FileRuntimeEventInbox(home).enqueueTurnCompleted({
+        scope: params.scope,
+        ...(params.scope === "task" ? { taskId: params.taskId } : {}),
+        roleName: params.roleName,
+        agentId: params.agentId,
+        adapterId: params.adapterId,
+        launchId: params.launchId,
+        nativeSessionId: params.nativeSessionId,
+        turnId: params.turnId,
+        ...(params.runId === undefined ? {} : { runId: params.runId }),
+        ...(params.title === undefined ? {} : { title: params.title }),
+        summary: params.lastAssistantMessage
+    });
+    // The durable write is authoritative. This short socket call is only a
+    // wake-up hint and never starts or waits for a Controller process.
+    await (call ?? callController)(home, "scheduler.signal", {
+        key: runtimeLifecycleSignalKey(params.scope === "task"
+            ? {
+                scope: "task",
+                taskId: params.taskId,
+                roleName: params.roleName
+            }
+            : {
+                scope: "global",
+                roleName: params.roleName
+            })
+    }, { timeoutMs: 100 }).catch(() => { });
+    if (enqueued.created && shouldSetThreadName(home, params)) {
+        const request = threadNameRequest(params, environment);
+        if (request !== null)
+            await setThreadName(request).catch(() => { });
+    }
 }
 export function parseCodexSessionNotification(payloadArgument, environment) {
     const payload = parseObject(payloadArgument, "Codex notify payload");
@@ -11,6 +48,12 @@ export function parseCodexSessionNotification(payloadArgument, environment) {
         throw new Error("Codex notify payload type is invalid.");
     }
     const nativeSessionId = requireText(payload["thread-id"], "Codex thread-id");
+    const turnId = requireText(payload["turn-id"], "Codex turn-id");
+    const lastAssistantMessage = requireAssistantMessage(payload["last-assistant-message"]);
+    const runId = yuiRunIdFromInputMessages(payload["input-messages"]);
+    const title = environment.YUI_SESSION_TITLE === undefined
+        ? sessionTitleFromInputMessages(payload["input-messages"])
+        : requireText(environment.YUI_SESSION_TITLE, "YUI_SESSION_TITLE");
     const scope = environment.YUI_SESSION_SCOPE;
     if (scope !== "task" && scope !== "global") {
         throw new Error("YUI_SESSION_SCOPE must be task or global.");
@@ -20,7 +63,12 @@ export function parseCodexSessionNotification(payloadArgument, environment) {
         roleName: requireText(environment.YUI_ROLE, "YUI_ROLE"),
         agentId: requireText(environment.YUI_AGENT_ID, "YUI_AGENT_ID"),
         adapterId: requireCodexAdapter(environment.YUI_ADAPTER_ID),
-        nativeSessionId
+        launchId: requireText(environment.YUI_LAUNCH_ID, "YUI_LAUNCH_ID"),
+        nativeSessionId,
+        turnId,
+        ...(runId === undefined ? {} : { runId }),
+        ...(title === undefined ? {} : { title }),
+        lastAssistantMessage
     };
     return scope === "task"
         ? {
@@ -29,64 +77,6 @@ export function parseCodexSessionNotification(payloadArgument, environment) {
         }
         : common;
 }
-/** Controller-side handler; session identity never travels through an Agent prompt. */
-export function createSessionNotifyDispatcher(store, fallback) {
-    return async (method, params) => {
-        if (method !== SESSION_BIND_METHOD) {
-            if (fallback !== undefined)
-                return fallback(method, params);
-            throw applicationError("METHOD_NOT_FOUND", "Controller method was not found.");
-        }
-        const input = parseSessionBindParams(params);
-        const recorded = input.scope === "task"
-            ? store.recordRuntimeNativeSession({
-                taskId: input.taskId,
-                roleName: input.roleName,
-                agentId: input.agentId,
-                adapterId: input.adapterId,
-                nativeSessionId: input.nativeSessionId
-            })
-            : store.recordGlobalRuntimeNativeSession({
-                roleName: input.roleName,
-                agentId: input.agentId,
-                adapterId: input.adapterId,
-                nativeSessionId: input.nativeSessionId
-            });
-        return {
-            recorded: true,
-            scope: input.scope,
-            roleName: input.roleName,
-            nativeSessionId: recorded.nativeSessionId
-        };
-    };
-}
-function parseSessionBindParams(value) {
-    if (!isObject(value))
-        throw invalidParams();
-    const input = value;
-    const scope = input.scope;
-    const expected = scope === "task"
-        ? ["scope", "taskId", "roleName", "agentId", "adapterId", "nativeSessionId"]
-        : ["scope", "roleName", "agentId", "adapterId", "nativeSessionId"];
-    if ((scope !== "task" && scope !== "global") || !hasExactKeys(input, expected)) {
-        throw invalidParams();
-    }
-    try {
-        const common = {
-            scope,
-            roleName: requireText(input.roleName, "Role name"),
-            agentId: requireText(input.agentId, "Agent id"),
-            adapterId: requireCodexAdapter(input.adapterId),
-            nativeSessionId: requireText(input.nativeSessionId, "Native session id")
-        };
-        return scope === "task"
-            ? { ...common, taskId: requireText(input.taskId, "Task id") }
-            : common;
-    }
-    catch {
-        throw invalidParams();
-    }
-}
 function parseObject(value, label) {
     if (value === undefined || Buffer.byteLength(value) > 1_048_576) {
         throw new Error(`${label} is invalid.`);
@@ -115,22 +105,75 @@ function requireText(value, label) {
         throw new Error(`${label} is invalid.`);
     return text;
 }
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+function requireAssistantMessage(value) {
+    if (value === null)
+        return NO_FINAL_ASSISTANT_MESSAGE_SUMMARY;
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error("Codex last assistant message is required.");
+    }
+    const text = value.trim();
+    if (text.length === 0 || Buffer.byteLength(text) > 524_288) {
+        throw new Error("Codex last assistant message is invalid.");
+    }
+    return text;
+}
+function sessionTitleFromInputMessages(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            continue;
+        const body = yuiRunBodyFromInputMessage(entry);
+        const normalized = body.trim().replaceAll(/\s+/g, " ");
+        if (normalized.length > 0)
+            return truncateSessionText(normalized);
+    }
+    return undefined;
 }
-function hasExactKeys(value, expected) {
-    const actual = Object.keys(value).sort();
-    return actual.length === expected.length
-        && actual.every((key, index) => key === [...expected].sort()[index]);
+function shouldSetThreadName(home, params) {
+    if (params.scope !== "task"
+        || params.title === undefined
+        || params.runId === undefined)
+        return false;
+    try {
+        const store = openCompatibleFileTaskStore(home);
+        return store.getAgentRun(params.taskId, params.runId)?.mode === "new";
+    }
+    catch {
+        return false;
+    }
 }
-function invalidParams() {
-    return applicationError("INVALID_PARAMS", "Runtime session params are invalid.");
+function threadNameRequest(params, environment) {
+    if (params.title === undefined)
+        return null;
+    const command = environment.YUI_AGENT_COMMAND;
+    const encodedBaseArgs = environment.YUI_AGENT_BASE_ARGS;
+    if (command === undefined || encodedBaseArgs === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(encodedBaseArgs);
+        if (!Array.isArray(parsed)
+            || parsed.some((value) => typeof value !== "string" || value.includes("\0"))) {
+            return null;
+        }
+        return {
+            command: requireText(command, "YUI_AGENT_COMMAND"),
+            baseArgs: parsed,
+            environment,
+            threadId: params.nativeSessionId,
+            name: params.title
+        };
+    }
+    catch {
+        return null;
+    }
 }
-function applicationError(code, message) {
-    const error = Object.assign(new Error(message), { code });
-    error.name = "CoreApplicationError";
-    return error;
+function truncateSessionText(value) {
+    const truncated = value.slice(0, 1_024);
+    return /[\uD800-\uDBFF]$/.test(truncated)
+        ? truncated.slice(0, -1)
+        : truncated;
 }
-function toJson(value) {
-    return JSON.parse(JSON.stringify(value));
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/coordination/deadlineScheduler.js

@@ -0,0 +1,15 @@
+/**
+ * Pure nearest-deadline selection shared by business deadlines and runtime
+ * recovery deadlines. Invalid timestamps are ignored and equal deadlines are
+ * coalesced into one wake batch.
+ */
+export function nearestDeadlineBatch(deadlines) {
+    const valid = deadlines.filter((deadline) => Number.isFinite(deadline.at));
+    if (valid.length === 0)
+        return null;
+    const at = Math.min(...valid.map((deadline) => deadline.at));
+    return {
+        at,
+        keys: [...new Set(valid.filter((deadline) => deadline.at === at).map((deadline) => deadline.key))]
+    };
+}

package/dist/coordination/mailboxScheduler.js

@@ -0,0 +1,108 @@
+const DEFAULT_WINDOW_MS = 100;
+/**
+ * Coalesces dirty mailbox keys over a fixed window. The first signal starts
+ * the window; later signals never extend it. A signal received during a batch
+ * belongs to a later batch, and batches are never processed concurrently.
+ */
+export class MailboxScheduler {
+    processBatch;
+    #windowMs;
+    #setTimer;
+    #clearTimer;
+    #onError;
+    #pendingKeys = new Set();
+    #timer;
+    #current;
+    #drainRequested = false;
+    #stopped = false;
+    constructor(processBatch, options = {}) {
+        this.processBatch = processBatch;
+        this.#windowMs = nonNegativeFinite(options.windowMs ?? DEFAULT_WINDOW_MS);
+        this.#setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.#clearTimer = options.clearTimer ?? ((timer) => {
+            clearTimeout(timer);
+        });
+        this.#onError = options.onError ?? (() => { });
+    }
+    signal(key) {
+        if (this.#stopped)
+            return;
+        this.#pendingKeys.add(key);
+        this.schedule();
+    }
+    schedule() {
+        if (this.#stopped
+            || this.#pendingKeys.size === 0
+            || this.#timer !== undefined) {
+            return;
+        }
+        this.#timer = this.#setTimer(() => {
+            this.#timer = undefined;
+            if (this.#current !== undefined) {
+                this.#drainRequested = true;
+                return;
+            }
+            void this.drain().catch(this.#onError);
+        }, this.#windowMs);
+    }
+    drain() {
+        if (this.#stopped)
+            return Promise.resolve();
+        this.#cancelTimer();
+        if (this.#current !== undefined) {
+            this.#drainRequested = true;
+            return this.#current;
+        }
+        if (this.#pendingKeys.size === 0)
+            return Promise.resolve();
+        // Defer invoking the callback until #current is installed. This closes the
+        // small reentrancy window where a synchronous callback could call drain()
+        // before the scheduler knew a drain was already active.
+        const running = Promise.resolve().then(() => this.#drainDueBatches());
+        this.#current = running;
+        void running.finally(() => {
+            if (this.#current !== running)
+                return;
+            this.#current = undefined;
+            if (this.#stopped || this.#pendingKeys.size === 0)
+                return;
+            if (this.#drainRequested) {
+                this.#drainRequested = false;
+                void this.drain().catch(this.#onError);
+            }
+            else {
+                this.schedule();
+            }
+        }).catch(() => { });
+        return running;
+    }
+    stop() {
+        this.#stopped = true;
+        this.#cancelTimer();
+        this.#pendingKeys.clear();
+        this.#drainRequested = false;
+    }
+    async #drainDueBatches() {
+        do {
+            this.#drainRequested = false;
+            const keys = [...this.#pendingKeys];
+            this.#pendingKeys.clear();
+            if (keys.length > 0)
+                await this.processBatch(keys);
+        } while (!this.#stopped
+            && this.#drainRequested
+            && this.#pendingKeys.size > 0);
+    }
+    #cancelTimer() {
+        if (this.#timer === undefined)
+            return;
+        this.#clearTimer(this.#timer);
+        this.#timer = undefined;
+    }
+}
+function nonNegativeFinite(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error("Mailbox scheduler window must be a non-negative finite number.");
+    }
+    return value;
+}

package/dist/coordination/workMailbox.js

@@ -0,0 +1,329 @@
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+function requireText(value, label) {
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        throw new Error(`${label} must not be empty`);
+    }
+    return normalized;
+}
+function requireInteger(value, minimum, label) {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`${label} must be an integer greater than or equal to ${minimum}`);
+    }
+    return value;
+}
+function record(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return value;
+}
+function exact(value, keys, label) {
+    const expected = new Set(keys);
+    const unknown = Object.keys(value).find((key) => !expected.has(key));
+    if (unknown !== undefined)
+        throw new Error(`${label} has unknown field: ${unknown}`);
+    const missing = keys.find((key) => !Object.hasOwn(value, key));
+    if (missing !== undefined)
+        throw new Error(`${label} is missing field: ${missing}`);
+}
+function requireString(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    return requireText(value, label);
+}
+function requireTimestamp(value, label) {
+    const timestamp = requireString(value, label);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new Error(`${label} must be a timestamp`);
+    return timestamp;
+}
+function requireStringArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    const result = value.map((item, index) => requireString(item, `${label}[${index}]`));
+    if (new Set(result).size !== result.length)
+        throw new Error(`${label} must not contain duplicates`);
+    return result;
+}
+function copyTarget(target) {
+    switch (target.kind) {
+        case "task":
+            return { kind: "task", taskId: requireText(target.taskId, "taskId") };
+        case "role":
+            return {
+                kind: "role",
+                taskId: requireText(target.taskId, "taskId"),
+                roleName: requireText(target.roleName, "roleName")
+            };
+        case "role-runtime":
+            return {
+                kind: "role-runtime",
+                taskId: requireText(target.taskId, "taskId"),
+                roleName: requireText(target.roleName, "roleName")
+            };
+        case "global-role-runtime":
+            return {
+                kind: "global-role-runtime",
+                roleName: requireText(target.roleName, "roleName")
+            };
+        case "operator":
+            return { kind: "operator" };
+    }
+}
+export function mailboxTargetKey(target) {
+    const copied = copyTarget(target);
+    switch (copied.kind) {
+        case "operator": return "operator";
+        case "task": return `task/${encodeURIComponent(copied.taskId)}`;
+        case "role": return `role/${encodeURIComponent(copied.taskId)}/${encodeURIComponent(copied.roleName)}`;
+        case "role-runtime":
+            return `role-runtime/${encodeURIComponent(copied.taskId)}/${encodeURIComponent(copied.roleName)}`;
+        case "global-role-runtime":
+            return `global-role-runtime/${encodeURIComponent(copied.roleName)}`;
+    }
+}
+function copyRef(ref) {
+    if (!("taskId" in ref)) {
+        if (ref.type !== "task" && ref.type !== "session") {
+            throw new Error(`entity reference taskId is required for ${ref.type}`);
+        }
+        return {
+            type: ref.type,
+            id: requireText(ref.id, "entity reference id")
+        };
+    }
+    const validated = validateTaskRecordReference({
+        taskId: ref.taskId,
+        localId: ref.id
+    }, mailboxTaskRecordKind(ref.type));
+    return {
+        type: ref.type,
+        taskId: validated.taskId,
+        id: validated.localId
+    };
+}
+export function mailboxEntityRefKey(ref) {
+    return !("taskId" in ref)
+        ? `${ref.type}\u0000${ref.id}`
+        : `${ref.type}\u0000${ref.taskId}\u0000${ref.id}`;
+}
+function appendUnique(existing, incoming, keyOf) {
+    const result = [...existing];
+    const keys = new Set(existing.map(keyOf));
+    for (const value of incoming) {
+        const key = keyOf(value);
+        if (!keys.has(key)) {
+            keys.add(key);
+            result.push(value);
+        }
+    }
+    return result;
+}
+function mergeBatches(earlier, later) {
+    const merged = {
+        fromSequence: earlier.fromSequence,
+        toSequence: later.toSequence,
+        reasons: appendUnique(earlier.reasons, later.reasons, (reason) => reason),
+        refs: appendUnique(earlier.refs, later.refs, mailboxEntityRefKey),
+        requestCount: earlier.requestCount + later.requestCount,
+        firstQueuedAt: earlier.firstQueuedAt,
+        lastQueuedAt: later.lastQueuedAt
+    };
+    return merged;
+}
+function requireProcessing(mailbox, batchId) {
+    const normalizedBatchId = requireText(batchId, "batch id");
+    if (mailbox.processing === null) {
+        throw new Error("Mailbox has no processing batch");
+    }
+    if (mailbox.processing.batchId !== normalizedBatchId) {
+        throw new Error(`Mailbox processing batch id does not match ${normalizedBatchId}`);
+    }
+    return mailbox.processing;
+}
+export function createWorkMailbox(target) {
+    return {
+        schemaVersion: 1,
+        target: copyTarget(target),
+        nextSequence: 1,
+        processing: null,
+        pending: null
+    };
+}
+export function validateWorkMailbox(value) {
+    const mailbox = record(value, "WorkMailbox");
+    exact(mailbox, ["schemaVersion", "target", "nextSequence", "processing", "pending"], "WorkMailbox");
+    if (mailbox.schemaVersion !== 1)
+        throw new Error("WorkMailbox must use schemaVersion 1");
+    const target = parseTarget(mailbox.target);
+    const nextSequence = requireInteger(mailbox.nextSequence, 1, "WorkMailbox nextSequence");
+    const processing = mailbox.processing === null ? null : parseProcessing(mailbox.processing);
+    const pending = mailbox.pending === null ? null : parseBatch(mailbox.pending, "WorkMailbox pending");
+    const batches = [processing?.batch, pending].filter((batch) => batch !== null && batch !== undefined);
+    for (const batch of batches) {
+        if (batch.toSequence >= nextSequence) {
+            throw new Error("WorkMailbox batch sequence must be lower than nextSequence");
+        }
+    }
+    if (processing !== null && pending !== null && processing.batch.toSequence >= pending.fromSequence) {
+        throw new Error("WorkMailbox processing and pending sequences overlap");
+    }
+    return { schemaVersion: 1, target, nextSequence, processing, pending };
+}
+function parseTarget(value) {
+    const target = record(value, "WorkMailbox target");
+    switch (target.kind) {
+        case "operator":
+            exact(target, ["kind"], "WorkMailbox operator target");
+            return { kind: "operator" };
+        case "task":
+            exact(target, ["kind", "taskId"], "WorkMailbox task target");
+            return { kind: "task", taskId: requireString(target.taskId, "WorkMailbox target taskId") };
+        case "role":
+            exact(target, ["kind", "taskId", "roleName"], "WorkMailbox role target");
+            return {
+                kind: "role",
+                taskId: requireString(target.taskId, "WorkMailbox target taskId"),
+                roleName: requireString(target.roleName, "WorkMailbox target roleName")
+            };
+        case "role-runtime":
+            exact(target, ["kind", "taskId", "roleName"], "WorkMailbox role runtime target");
+            return {
+                kind: "role-runtime",
+                taskId: requireString(target.taskId, "WorkMailbox target taskId"),
+                roleName: requireString(target.roleName, "WorkMailbox target roleName")
+            };
+        case "global-role-runtime":
+            exact(target, ["kind", "roleName"], "WorkMailbox global role runtime target");
+            return {
+                kind: "global-role-runtime",
+                roleName: requireString(target.roleName, "WorkMailbox target roleName")
+            };
+        default:
+            throw new Error("WorkMailbox target kind is invalid");
+    }
+}
+function parseRef(value, label) {
+    const ref = record(value, label);
+    const types = ["task", "run", "work-item", "input", "session", "message"];
+    if (!types.includes(ref.type))
+        throw new Error(`${label} type is invalid`);
+    if (ref.type === "task" || ref.type === "session") {
+        exact(ref, ["type", "id"], label);
+        return { type: ref.type, id: requireString(ref.id, `${label} id`) };
+    }
+    exact(ref, ["type", "taskId", "id"], label);
+    return copyRef({
+        type: ref.type,
+        taskId: requireString(ref.taskId, `${label} taskId`),
+        id: requireString(ref.id, `${label} id`)
+    });
+}
+function parseBatch(value, label) {
+    const batch = record(value, label);
+    const required = ["fromSequence", "toSequence", "reasons", "refs", "requestCount", "firstQueuedAt", "lastQueuedAt"];
+    exact(batch, required, label);
+    const fromSequence = requireInteger(batch.fromSequence, 1, `${label} fromSequence`);
+    const toSequence = requireInteger(batch.toSequence, fromSequence, `${label} toSequence`);
+    const requestCount = requireInteger(batch.requestCount, 1, `${label} requestCount`);
+    if (requestCount !== toSequence - fromSequence + 1) {
+        throw new Error(`${label} requestCount does not match its sequence range`);
+    }
+    const reasons = requireStringArray(batch.reasons, `${label} reasons`);
+    if (reasons.length === 0)
+        throw new Error(`${label} reasons must not be empty`);
+    if (!Array.isArray(batch.refs))
+        throw new Error(`${label} refs must be an array`);
+    const refs = batch.refs.map((ref, index) => parseRef(ref, `${label} refs[${index}]`));
+    const refKeys = refs.map(mailboxEntityRefKey);
+    if (new Set(refKeys).size !== refKeys.length)
+        throw new Error(`${label} refs must not contain duplicates`);
+    const result = {
+        fromSequence,
+        toSequence,
+        reasons,
+        refs,
+        requestCount,
+        firstQueuedAt: requireTimestamp(batch.firstQueuedAt, `${label} firstQueuedAt`),
+        lastQueuedAt: requireTimestamp(batch.lastQueuedAt, `${label} lastQueuedAt`)
+    };
+    return result;
+}
+function parseProcessing(value) {
+    const processing = record(value, "WorkMailbox processing");
+    const required = ["batchId", "batch", "owner", "startedAt"];
+    exact(processing, processing.executionRef === undefined ? required : [...required, "executionRef"], "WorkMailbox processing");
+    const result = {
+        batchId: requireString(processing.batchId, "WorkMailbox processing batchId"),
+        batch: parseBatch(processing.batch, "WorkMailbox processing batch"),
+        owner: requireString(processing.owner, "WorkMailbox processing owner"),
+        startedAt: requireTimestamp(processing.startedAt, "WorkMailbox processing startedAt")
+    };
+    return processing.executionRef === undefined
+        ? result
+        : { ...result, executionRef: parseRef(processing.executionRef, "WorkMailbox processing executionRef") };
+}
+export function enqueueSignal(mailbox, signal) {
+    const reason = requireText(signal.reason, "signal reason");
+    const occurredAt = requireText(signal.occurredAt, "signal occurredAt");
+    const refs = signal.refs.map(copyRef);
+    const sequence = mailbox.nextSequence;
+    const incoming = {
+        fromSequence: sequence,
+        toSequence: sequence,
+        reasons: [reason],
+        refs: appendUnique([], refs, mailboxEntityRefKey),
+        requestCount: 1,
+        firstQueuedAt: occurredAt,
+        lastQueuedAt: occurredAt
+    };
+    return {
+        ...mailbox,
+        nextSequence: sequence + 1,
+        pending: mailbox.pending === null
+            ? incoming
+            : mergeBatches(mailbox.pending, incoming)
+    };
+}
+function mailboxTaskRecordKind(type) {
+    switch (type) {
+        case "run": return "agentRun";
+        case "work-item": return "workItem";
+        case "input": return "inputRequest";
+        case "message": return "message";
+    }
+}
+export function claimPending(mailbox, options) {
+    if (mailbox.processing !== null) {
+        throw new Error("Mailbox is already processing a batch");
+    }
+    if (mailbox.pending === null) {
+        throw new Error("Mailbox has no pending work to claim");
+    }
+    const processing = {
+        batchId: requireText(options.batchId, "batch id"),
+        batch: mailbox.pending,
+        owner: requireText(options.owner, "claim owner"),
+        startedAt: requireText(options.startedAt, "claim startedAt")
+    };
+    return { ...mailbox, processing, pending: null };
+}
+export function bindExecution(mailbox, batchId, executionRef) {
+    const processing = requireProcessing(mailbox, batchId);
+    return {
+        ...mailbox,
+        processing: { ...processing, executionRef: copyRef(executionRef) }
+    };
+}
+export function completeProcessing(mailbox, batchId) {
+    requireProcessing(mailbox, batchId);
+    return { ...mailbox, processing: null };
+}
+export function releaseProcessing(mailbox, batchId) {
+    const processing = requireProcessing(mailbox, batchId);
+    const released = mailbox.pending === null
+        ? processing.batch
+        : mergeBatches(processing.batch, mailbox.pending);
+    return { ...mailbox, processing: null, pending: released };
+}