@myagentroam/agent 0.9.62 → 0.9.64

package/dist/subagent/session-controller.js

@@ -0,0 +1,675 @@
+import { randomUUID } from 'node:crypto';
+import { MarAgentError, describeMarAgentError } from '../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
+export class SubagentSessionController {
+    parentSessionId;
+    rootSessionId;
+    backend;
+    limits;
+    #agents = new Map();
+    #queue = [];
+    #running = 0;
+    #disposed = false;
+    #createdInExecution = 0;
+    #execution;
+    constructor(parentSessionId, rootSessionId, backend, limits = { maxTasks: 8, maxConcurrent: 4 }) {
+        this.parentSessionId = parentSessionId;
+        this.rootSessionId = rootSessionId;
+        this.backend = backend;
+        this.limits = limits;
+    }
+    static async open(input) {
+        const controller = new SubagentSessionController(input.parentSessionId, input.rootSessionId, input.backend, input.limits);
+        for (const session of await input.backend.listChildren(input.parentSessionId))
+            controller.#agents.set(session.id, restoreAgentState(session));
+        return controller;
+    }
+    async beginParentExecution(execution) {
+        if (this.#disposed)
+            throw new MarAgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent controller is disposed.');
+        this.#execution = execution;
+        this.#createdInExecution = 0;
+        for (const state of this.#agents.values())
+            await this.#publishTerminal(state);
+    }
+    endParentExecution(executionId) {
+        if (this.#execution?.executionId === executionId)
+            this.#execution = undefined;
+    }
+    async run(input, options = {}) {
+        options.signal?.throwIfAborted();
+        const execution = this.#requireExecution();
+        validateTaskInput(input);
+        if (this.#createdInExecution >= this.limits.maxTasks)
+            throw new MarAgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent task limit was reached.');
+        const source = {
+            type: 'subagent',
+            parentSessionId: this.parentSessionId,
+            rootSessionId: this.rootSessionId,
+            parentExecutionId: execution.executionId,
+            role: input.role,
+            description: input.description.trim()
+        };
+        const created = await this.backend.createSession({
+            title: input.description.trim(),
+            source
+        });
+        try {
+            if (this.#disposed)
+                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
+            options.signal?.throwIfAborted();
+        }
+        catch (error) {
+            await this.#deleteUnstartedSession(created.id, error);
+        }
+        const state = {
+            agentId: created.id,
+            description: source.description,
+            role: input.role,
+            status: 'queued',
+            changedFiles: [],
+            verification: [],
+            evidence: [],
+            terminalPending: false
+        };
+        this.#createdInExecution++;
+        this.#agents.set(state.agentId, state);
+        const knownModel = execution.models.get(input.modelId ?? execution.modelId);
+        if (knownModel) {
+            state.modelId = knownModel.id;
+            state.modelName = knownModel.name;
+        }
+        try {
+            const selected = resolveModel(execution, input);
+            state.modelId = selected.id;
+            state.modelName = selected.name;
+            state.reasoningEffort = selected.reasoningEffort;
+        }
+        catch (error) {
+            this.#setFailure(state, error);
+        }
+        try {
+            await options.onCreated?.(this.#snapshot(state));
+            if (this.#disposed)
+                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
+            options.signal?.throwIfAborted();
+        }
+        catch (error) {
+            await this.#deleteUnstartedSession(state.agentId, error);
+        }
+        if (state.status === 'failed') {
+            await this.#publishTerminal(state);
+            return this.#snapshot(state);
+        }
+        this.#queueTurn(state, input.prompt, execution.startTurn, []);
+        const detachParentAbort = !input.background && options.signal
+            ? linkAbort(options.signal, () => {
+                void this.cancel(state.agentId);
+            })
+            : undefined;
+        try {
+            if (!input.background)
+                await state.turn.completion;
+            return this.#snapshot(state);
+        }
+        finally {
+            detachParentAbort?.();
+        }
+    }
+    async output(agentId, options = {}) {
+        options.signal?.throwIfAborted();
+        const state = await this.#find(agentId);
+        if (options.waitMs !== undefined &&
+            (!Number.isInteger(options.waitMs) ||
+                options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
+                options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs))
+            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Task wait is invalid.');
+        const waitMs = options.waitMs === undefined || options.waitMs === 0
+            ? undefined
+            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+        if (waitMs !== undefined &&
+            state.turn &&
+            (state.status === 'queued' || state.status === 'running'))
+            await waitForCompletion(state.turn.completion, waitMs, options.signal);
+        return this.#snapshot(state);
+    }
+    async message(agentId, message, options = {}) {
+        const execution = this.#requireExecution();
+        if (typeof message !== 'string' ||
+            message.trim().length === 0 ||
+            Buffer.byteLength(message) > TOOL_EXECUTION_LIMITS.subagentMessageMaxBytes ||
+            (options.delivery !== undefined &&
+                options.delivery !== 'append' &&
+                options.delivery !== 'replace'))
+            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Agent message input is invalid.');
+        const state = await this.#find(agentId);
+        return this.#control(state, async () => {
+            this.#requireExecution();
+            options.signal?.throwIfAborted();
+            // Resolve before cancelling so an unavailable model does not stop valid work.
+            const selected = resolveExistingModel(execution, state);
+            if (options.delivery === 'replace')
+                await this.#cancelState(state);
+            this.#requireExecution();
+            options.signal?.throwIfAborted();
+            const turnId = state.turn?.turnId ?? randomUUID();
+            const receipt = { messageId: randomUUID(), turnId, deliveryStatus: 'accepted' };
+            const mutableReceipt = receipt;
+            const delivery = {
+                messageId: receipt.messageId,
+                applied: () => {
+                    mutableReceipt.deliveryStatus = 'applied';
+                }
+            };
+            if (state.status === 'running' && state.turn) {
+                const turn = state.turn;
+                if (!turn.handle)
+                    await turn.handleReady;
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+                if (state.status === 'running' &&
+                    state.turn === turn &&
+                    turn.handle?.enqueueMessage(message, delivery)) {
+                    state.receipt = mutableReceipt;
+                    return this.#snapshot(state);
+                }
+                await turn.completion;
+            }
+            else if (state.status === 'queued' && state.turn) {
+                state.turn.pendingMessages.push({ text: message, delivery });
+                state.receipt = mutableReceipt;
+                return this.#snapshot(state);
+            }
+            this.#requireExecution();
+            options.signal?.throwIfAborted();
+            state.modelId = selected.id;
+            state.modelName = selected.name;
+            state.reasoningEffort = selected.reasoningEffort;
+            // A closing turn may have rejected append; reserve a fresh identity for its successor.
+            mutableReceipt.turnId = randomUUID();
+            state.receipt = mutableReceipt;
+            this.#queueTurn(state, message, execution.startTurn, [], mutableReceipt.turnId, delivery);
+            return this.#snapshot(state);
+        });
+    }
+    async cancel(agentId) {
+        const state = await this.#find(agentId);
+        return this.#control(state, () => this.#cancelState(state));
+    }
+    #control(state, operation) {
+        const result = (state.controlTail ?? Promise.resolve()).then(operation);
+        state.controlTail = result.catch(() => undefined);
+        return result;
+    }
+    async #cancelState(state) {
+        if (state.status === 'queued' && state.turn) {
+            const index = this.#queue.indexOf(state);
+            if (index >= 0)
+                this.#queue.splice(index, 1);
+            state.status = 'cancelled';
+            this.#closeReceipt(state);
+            state.terminalPending = true;
+            await this.#publishTerminal(state);
+            state.turn.resolve();
+            delete state.turn;
+            this.#drain();
+        }
+        else if (state.status === 'running' && state.turn) {
+            const turn = state.turn;
+            if (turn.handle)
+                turn.handle.cancel();
+            else {
+                turn.cancelRequested = true;
+                await turn.handleReady;
+            }
+            await turn.completion;
+        }
+        return this.#snapshot(state);
+    }
+    listSessionResources() {
+        return [...this.#agents.values()].map((state) => ({
+            agentId: state.agentId,
+            status: state.status,
+            description: state.description
+        }));
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const state of this.#queue.splice(0)) {
+            state.status = 'cancelled';
+            this.#closeReceipt(state);
+            state.turn?.resolve();
+            delete state.turn;
+        }
+        for (const state of this.#agents.values()) {
+            if (state.status !== 'running' || !state.turn)
+                continue;
+            if (state.turn.handle)
+                state.turn.handle.cancel();
+            else
+                state.turn.cancelRequested = true;
+        }
+        await Promise.allSettled([...this.#agents.values()].flatMap((state) => state.turn === undefined ? [] : [state.turn.completion]));
+        this.#execution = undefined;
+    }
+    #queueTurn(state, prompt, start, pendingMessages, turnId = randomUUID(), delivery) {
+        let resolve;
+        let resolveHandleReady;
+        const completion = new Promise((done) => (resolve = done));
+        const handleReady = new Promise((done) => (resolveHandleReady = done));
+        state.status = 'queued';
+        delete state.summary;
+        delete state.errorCode;
+        delete state.errorMessage;
+        state.changedFiles = [];
+        state.verification = [];
+        state.evidence = [];
+        state.terminalPending = false;
+        state.turn = {
+            turnId,
+            ...(delivery === undefined ? {} : { delivery }),
+            prompt,
+            start,
+            pendingMessages,
+            handleReady,
+            completion,
+            resolve,
+            resolveHandleReady
+        };
+        this.#queue.push(state);
+        this.#drain();
+    }
+    #drain() {
+        while (!this.#disposed && this.#running < this.limits.maxConcurrent && this.#queue.length > 0) {
+            const state = this.#queue.shift();
+            const turn = state.turn;
+            if (!turn || state.status !== 'queued')
+                continue;
+            state.status = 'running';
+            this.#running++;
+            void this.#startAndConsumeTurn(state, turn);
+        }
+    }
+    async #startAndConsumeTurn(state, turn) {
+        try {
+            turn.handle = await turn.start({
+                turnId: turn.turnId,
+                ...(turn.delivery === undefined ? {} : { delivery: turn.delivery }),
+                sessionId: state.agentId,
+                prompt: turn.prompt,
+                modelId: state.modelId,
+                reasoningEffort: state.reasoningEffort,
+                role: state.role,
+                initialMailbox: turn.pendingMessages.splice(0)
+            });
+        }
+        catch (error) {
+            turn.resolveHandleReady();
+            await this.#failTurn(state, error);
+            return;
+        }
+        if (turn.cancelRequested)
+            turn.handle.cancel();
+        turn.resolveHandleReady();
+        await this.#consumeTurn(state, turn);
+    }
+    async #consumeTurn(state, turn) {
+        try {
+            const consume = (async () => {
+                for await (const event of turn.handle)
+                    observeAgentEvent(state, event);
+            })();
+            const result = await turn.handle.result();
+            await consume;
+            if (result.status === 'completed') {
+                state.status = 'completed';
+                state.summary = truncateUtf8(result.finalAnswer, TOOL_EXECUTION_LIMITS.subagentSummaryMaxBytes);
+            }
+            else if (result.status === 'cancelled')
+                state.status = 'cancelled';
+            else {
+                state.status = 'failed';
+                state.errorCode = result.errorCode ?? 'MAR_AGENT_SUBAGENT_FAILED';
+                state.errorMessage = result.errorMessage ?? 'Subagent execution failed.';
+            }
+            state.terminalPending = true;
+            this.#closeReceipt(state);
+            await this.#publishTerminal(state);
+        }
+        catch (error) {
+            this.#setFailure(state, error);
+            this.#closeReceipt(state);
+            await this.#publishTerminal(state);
+        }
+        finally {
+            this.#closeReceipt(state);
+            this.#running--;
+            turn.resolve();
+            if (state.turn === turn)
+                delete state.turn;
+            this.#drain();
+        }
+    }
+    async #failTurn(state, error) {
+        this.#setFailure(state, error);
+        this.#closeReceipt(state);
+        const turn = state.turn;
+        delete state.turn;
+        this.#running--;
+        turn?.resolve();
+        await this.#publishTerminal(state);
+        this.#drain();
+    }
+    #setFailure(state, error) {
+        const diagnostic = describeMarAgentError(error, 'MAR_AGENT_SUBAGENT_FAILED');
+        state.status = 'failed';
+        state.errorCode = diagnostic.code;
+        state.errorMessage = diagnostic.message;
+        state.terminalPending = true;
+    }
+    #closeReceipt(state) {
+        if (state.receipt?.deliveryStatus === 'accepted' && state.receipt.turnId === state.turn?.turnId)
+            state.receipt.deliveryStatus = state.status === 'cancelled' ? 'cancelled' : 'failed';
+    }
+    async #deleteUnstartedSession(agentId, error) {
+        this.#agents.delete(agentId);
+        try {
+            await this.backend.deleteSession(agentId);
+        }
+        catch (cleanupError) {
+            const original = describeMarAgentError(error, 'MAR_AGENT_SUBAGENT_FAILED');
+            const cleanup = describeMarAgentError(cleanupError, 'MAR_AGENT_SUBAGENT_FAILED');
+            throw new MarAgentError(original.code, `${original.message} Cleanup also failed: ${cleanup.message}`, { cause: cleanupError });
+        }
+        throw error;
+    }
+    async #find(agentId) {
+        const known = this.#agents.get(agentId);
+        if (known)
+            return known;
+        const persisted = await this.backend.loadChild(this.parentSessionId, agentId);
+        if (!persisted)
+            throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
+        const restored = restoreAgentState(persisted);
+        this.#agents.set(agentId, restored);
+        return restored;
+    }
+    #requireExecution() {
+        if (this.#disposed)
+            throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
+        if (!this.#execution)
+            throw new MarAgentError('MAR_AGENT_SUBAGENT_FAILED', 'Subagent control requires an active parent execution.');
+        return this.#execution;
+    }
+    #snapshot(state) {
+        return {
+            agentId: state.agentId,
+            description: state.description,
+            status: state.status,
+            ...state.receipt,
+            ...(state.modelId === undefined ? {} : { modelId: state.modelId }),
+            ...(state.modelName === undefined ? {} : { modelName: state.modelName }),
+            ...(state.reasoningEffort === undefined ? {} : { reasoningEffort: state.reasoningEffort }),
+            ...(state.latestMessage === undefined ? {} : { latestMessage: { ...state.latestMessage } }),
+            ...(state.summary === undefined ? {} : { summary: state.summary }),
+            ...(state.changedFiles.length === 0 ? {} : { changedFiles: [...state.changedFiles] }),
+            ...(state.verification.length === 0 ? {} : { verification: [...state.verification] }),
+            ...(state.evidence.length === 0
+                ? {}
+                : { evidence: state.evidence.map((item) => ({ ...item })) }),
+            ...(state.errorCode === undefined ? {} : { errorCode: state.errorCode }),
+            ...(state.errorMessage === undefined ? {} : { errorMessage: state.errorMessage })
+        };
+    }
+    async #publishTerminal(state) {
+        if (!state.terminalPending || !this.#execution)
+            return;
+        try {
+            await this.#execution.emitTerminal(this.#snapshot(state));
+            state.terminalPending = false;
+        }
+        catch {
+            // Keep the terminal transition pending for a later active parent Execution.
+        }
+    }
+}
+function validateTaskInput(input) {
+    if (input.parentSubagentId ||
+        !input.description.trim() ||
+        input.description.length > TOOL_EXECUTION_LIMITS.subagentDescriptionMaxCharacters ||
+        !input.prompt.trim() ||
+        Buffer.byteLength(input.prompt) > TOOL_EXECUTION_LIMITS.subagentPromptMaxBytes)
+        throw new MarAgentError(input.parentSubagentId
+            ? 'MAR_AGENT_SUBAGENT_RECURSION_DISABLED'
+            : 'MAR_AGENT_TOOL_INPUT_INVALID', input.parentSubagentId ? 'Subagents cannot create subagents.' : 'Subagent task is invalid.');
+}
+function resolveModel(execution, input) {
+    const modelId = input.modelId ?? execution.modelId;
+    const model = execution.models.get(modelId);
+    if (!model)
+        throw new MarAgentError('MAR_AGENT_SUBAGENT_MODEL_UNAVAILABLE', 'Selected model is unavailable for subagents.');
+    if (input.reasoningEffort !== undefined &&
+        !model.reasoningEfforts.includes(input.reasoningEffort))
+        throw new MarAgentError('MAR_AGENT_SUBAGENT_REASONING_EFFORT_UNAVAILABLE', 'Selected reasoning effort is unavailable for the subagent model.', {
+            details: {
+                modelId,
+                reasoningEffort: input.reasoningEffort,
+                supportedReasoningEfforts: model.reasoningEfforts
+            }
+        });
+    const reasoningEffort = input.reasoningEffort ??
+        (model.reasoningEfforts.includes(execution.reasoningEffort)
+            ? execution.reasoningEffort
+            : model.defaultReasoningEffort);
+    return { ...model, reasoningEffort };
+}
+function resolveExistingModel(execution, state) {
+    const model = execution.models.get(state.modelId ?? execution.modelId);
+    if (!model)
+        throw new MarAgentError('MAR_AGENT_SUBAGENT_MODEL_UNAVAILABLE', 'The subagent model is no longer available.');
+    return {
+        ...model,
+        reasoningEffort: state.reasoningEffort && model.reasoningEfforts.includes(state.reasoningEffort)
+            ? state.reasoningEffort
+            : model.defaultReasoningEffort
+    };
+}
+function restoreAgentState(session) {
+    const delivered = session.records.findLast((record) => record.type === 'turn.user' &&
+        isRecord(record.payload) &&
+        typeof record.payload.messageId === 'string' &&
+        typeof record.turnId === 'string');
+    const latestExecutionStart = session.records.findLastIndex((record) => eventType(record) === 'execution.started');
+    const currentRecords = latestExecutionStart < 0 ? session.records : session.records.slice(latestExecutionStart);
+    const header = session.records.findLast((record) => record.type === 'execution.header' && isRecord(record.payload))?.payload;
+    const terminal = currentRecords.findLast((record) => ['execution.completed', 'execution.failed', 'execution.cancelled'].includes(eventType(record) ?? ''));
+    const terminalType = eventType(terminal);
+    const latestMessageRecord = session.records.findLast((record) => eventType(record) === 'message.completed');
+    const latestMessage = latestMessageRecord && isRecord(latestMessageRecord.payload)
+        ? latestMessageFromPayload(latestMessageRecord.payload)
+        : undefined;
+    const state = {
+        agentId: session.id,
+        description: session.source.description,
+        role: session.source.role,
+        status: terminalType === 'execution.completed'
+            ? 'completed'
+            : terminalType === 'execution.failed'
+                ? 'failed'
+                : terminalType === 'execution.cancelled'
+                    ? 'cancelled'
+                    : 'interrupted',
+        ...(delivered && isRecord(delivered.payload)
+            ? {
+                receipt: {
+                    messageId: delivered.payload.messageId,
+                    turnId: delivered.turnId,
+                    deliveryStatus: 'applied'
+                }
+            }
+            : {}),
+        ...(typeof header?.modelId === 'string' ? { modelId: header.modelId } : {}),
+        ...(typeof header?.modelName === 'string' ? { modelName: header.modelName } : {}),
+        ...(isReasoningEffort(header?.reasoningEffort)
+            ? { reasoningEffort: header.reasoningEffort }
+            : {}),
+        ...(latestMessage === undefined ? {} : { latestMessage }),
+        changedFiles: [],
+        verification: [],
+        evidence: [],
+        terminalPending: false
+    };
+    if (state.status === 'completed' && latestMessage?.phase === 'final_answer')
+        state.summary = truncateUtf8(latestMessage.text, TOOL_EXECUTION_LIMITS.subagentSummaryMaxBytes);
+    if (state.status === 'failed' && terminal && isRecord(terminal.payload)) {
+        if (typeof terminal.payload.code === 'string')
+            state.errorCode = terminal.payload.code;
+        if (typeof terminal.payload.message === 'string')
+            state.errorMessage = terminal.payload.message;
+    }
+    for (const record of currentRecords) {
+        if (!isRecord(record.payload) || eventType(record) !== 'tool.completed')
+            continue;
+        const event = record.payload;
+        if (event.type === 'tool.completed')
+            observeAgentEvent(state, event);
+    }
+    return state;
+}
+function observeAgentEvent(state, event) {
+    if (event.type === 'message.completed') {
+        state.latestMessage = latestMessageFromEvent(event);
+        return;
+    }
+    if (event.type !== 'tool.completed')
+        return;
+    if (event.toolName === 'apply_patch' && isRecord(event.data)) {
+        const data = event.data;
+        const files = Array.isArray(data.files) ? data.files : [];
+        for (const file of files) {
+            if (!isRecord(file))
+                continue;
+            for (const path of [file.path, file.targetPath])
+                if (typeof path === 'string' &&
+                    path.length > 0 &&
+                    !state.changedFiles.includes(path) &&
+                    state.changedFiles.length < TOOL_EXECUTION_LIMITS.subagentChangedFilesMaxItems)
+                    state.changedFiles.push(path);
+        }
+    }
+    else if (event.toolName === 'read' && isRecord(event.data)) {
+        const data = event.data;
+        const results = Array.isArray(data.results) ? data.results : [];
+        for (const result of results) {
+            if (!isRecord(result) ||
+                typeof result.path !== 'string' ||
+                result.error !== undefined ||
+                state.evidence.length >= TOOL_EXECUTION_LIMITS.subagentEvidenceMaxItems)
+                continue;
+            const evidence = {
+                path: result.path,
+                ...(isPositiveInteger(result.startLine) ? { startLine: result.startLine } : {}),
+                ...(isPositiveInteger(result.endLine) ? { endLine: result.endLine } : {})
+            };
+            if (!state.evidence.some((item) => JSON.stringify(item) === JSON.stringify(evidence)))
+                state.evidence.push(evidence);
+        }
+    }
+    else if (event.toolName === 'exec' &&
+        state.verification.length < TOOL_EXECUTION_LIMITS.subagentVerificationMaxItems)
+        state.verification.push(truncateUtf8(event.summary, 2_000));
+}
+function eventType(record) {
+    return record && isRecord(record.payload) && typeof record.payload.type === 'string'
+        ? record.payload.type
+        : undefined;
+}
+function latestMessageFromEvent(event) {
+    const text = truncateCharacters(event.text, 10_000);
+    return {
+        itemId: event.itemId,
+        turnId: event.turnId ?? '',
+        phase: event.phase,
+        text,
+        timestamp: event.timestamp,
+        truncated: text !== event.text
+    };
+}
+function latestMessageFromPayload(payload) {
+    if (typeof payload.itemId !== 'string' ||
+        typeof payload.turnId !== 'string' ||
+        (payload.phase !== 'commentary' && payload.phase !== 'final_answer') ||
+        typeof payload.text !== 'string' ||
+        typeof payload.timestamp !== 'string')
+        return undefined;
+    const text = truncateCharacters(payload.text, 10_000);
+    return {
+        itemId: payload.itemId,
+        turnId: payload.turnId,
+        phase: payload.phase,
+        text,
+        timestamp: payload.timestamp,
+        truncated: text !== payload.text
+    };
+}
+function isReasoningEffort(value) {
+    return (value === 'low' ||
+        value === 'medium' ||
+        value === 'high' ||
+        value === 'xhigh' ||
+        value === 'max' ||
+        value === 'ultra');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+}
+function truncateUtf8(value, maximumBytes) {
+    const bytes = Buffer.from(value);
+    if (bytes.length <= maximumBytes)
+        return value;
+    let end = maximumBytes;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return bytes.subarray(0, end).toString('utf8');
+}
+function truncateCharacters(value, maximumCharacters) {
+    const characters = [...value];
+    return characters.length <= maximumCharacters
+        ? value
+        : characters.slice(0, maximumCharacters).join('');
+}
+function waitForCompletion(completion, waitMs, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        };
+        const abort = () => finish(signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
+        const timer = setTimeout(finish, waitMs);
+        timer.unref();
+        signal?.addEventListener('abort', abort, { once: true });
+        void completion.then(() => finish());
+        if (signal?.aborted)
+            abort();
+    });
+}
+function linkAbort(signal, abort) {
+    const listener = () => abort();
+    signal.addEventListener('abort', listener, { once: true });
+    if (signal.aborted)
+        listener();
+    return () => signal.removeEventListener('abort', listener);
+}