maka-agent 0.2.2-dev.92.20261019 → 0.2.2-dev.97.20261024

package/node_modules/@maka/runtime-host/dist/server/session-checkin.js

@@ -0,0 +1,257 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { isWorkHubCoordinationSessionId, userFacingText, } from '@maka/core/session';
+import { SIDE_CONVERSATION_SESSION_LABEL } from '@maka/core/side-conversation';
+import { buildCheckinPrompt, CHECKIN_LOOKBACK_MS, decodeCheckinModelOutput, selectCheckinCandidates, validateCheckinCards, } from '@maka/runtime/session-checkin';
+import { abortable } from '../client/wait-for-ready.js';
+/** Sessions read in full per check-in; the rest of the catalog is judged by its row. */
+const CHECKIN_DEEP_READ_MAX = 24;
+const CHECKIN_TIMEOUT_MS = 60_000;
+const CHECKIN_EFFECTS_RETAINED = 16;
+const EXCLUDED_LABELS = new Set([
+    SIDE_CONVERSATION_SESSION_LABEL,
+    'mode:bot',
+    'mode:deep_research',
+    'scheduled-task',
+]);
+/**
+ * Runs one check-in per effect identity: a retry with the same identity gets
+ * the same answer and never pays for a second model call while this Host runs.
+ */
+export class HostSessionCheckinCoordinator {
+    ports;
+    handlers = {
+        'session.checkin.generate': (input, context) => this.generate(input, context),
+    };
+    #effects = new Map();
+    #aborts = new Set();
+    #closed = false;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    generate(input, context) {
+        if (this.#closed)
+            return Promise.resolve(draining());
+        const existing = this.#effects.get(input.effectId);
+        if (existing) {
+            return existing.since === input.since
+                ? existing.task
+                : Promise.resolve({
+                    ok: false,
+                    error: {
+                        code: 'operation_conflict',
+                        message: 'Check-in effect identity is already in use',
+                    },
+                });
+        }
+        const residency = context.acquireResidency();
+        const abort = new AbortController();
+        this.#aborts.add(abort);
+        const signal = AbortSignal.any([
+            abort.signal,
+            AbortSignal.timeout(this.ports.timeoutMs ?? CHECKIN_TIMEOUT_MS),
+        ]);
+        const task = this.#run(input, context, signal)
+            .then((result) => ({ ok: true, result }), () => this.#closed
+            ? draining()
+            : { ok: false, error: { code: 'internal_failure', message: 'Check-in failed' } })
+            .finally(() => {
+            this.#aborts.delete(abort);
+            residency.release();
+        });
+        this.#effects.set(input.effectId, { since: input.since, task });
+        while (this.#effects.size > CHECKIN_EFFECTS_RETAINED) {
+            this.#effects.delete(this.#effects.keys().next().value);
+        }
+        return task;
+    }
+    beginDrain() {
+        this.#closed = true;
+        for (const abort of this.#aborts)
+            abort.abort();
+    }
+    async close() {
+        this.beginDrain();
+        await Promise.allSettled([...this.#effects.values()].map((effect) => effect.task));
+    }
+    async #run(input, context, signal) {
+        const effectId = input.effectId;
+        if (!(await abortable(() => this.ports.allowed(), signal)))
+            return { kind: 'empty', effectId };
+        const target = await abortable(() => this.ports.readModelTarget(), signal);
+        if (!target)
+            return { kind: 'failed', effectId, errorClass: 'configuration' };
+        const now = this.ports.now?.() ?? Date.now();
+        const sessions = await abortable(() => this.ports.listSessions(context), signal);
+        const recent = sessions
+            .filter((session) => checkinMayRead(session, now))
+            .sort((a, b) => b.activityAt - a.activityAt)
+            .slice(0, CHECKIN_DEEP_READ_MAX);
+        const states = [];
+        let unreadable = 0;
+        for (const session of recent) {
+            const state = await abortable(() => this.ports.readSession(session), signal).catch((error) => {
+                if (signal.aborted)
+                    throw error;
+                unreadable += 1;
+                return undefined;
+            });
+            if (state)
+                states.push(state);
+        }
+        // One unreadable Session is skipped; reading none at all is a broken check-in, not a quiet one.
+        if (unreadable > 0 && states.length === 0) {
+            return { kind: 'failed', effectId, errorClass: 'unknown' };
+        }
+        const candidates = selectCheckinCandidates(states, { now, since: input.since });
+        if (candidates.length === 0)
+            return { kind: 'empty', effectId };
+        const model = await this.ports.generate({
+            target,
+            prompt: buildCheckinPrompt(candidates),
+            abortSignal: signal,
+        });
+        if (!model.ok)
+            return { kind: 'failed', effectId, errorClass: model.errorClass };
+        const decoded = decodeCheckinModelOutput(model.text);
+        if (!decoded.ok)
+            return { kind: 'failed', effectId, errorClass: 'invalid_response' };
+        const validation = validateCheckinCards(decoded.cards, candidates);
+        return {
+            kind: 'generated',
+            effectId,
+            cards: validation.cards,
+            dropped: validation.dropped.length,
+        };
+    }
+}
+const CATALOG_PAGES_MAX = 10;
+const MESSAGES_KEPT = 20;
+/** Reads catalog pages until they run out or the page budget does. */
+export async function listCheckinCatalogSessions(query) {
+    const sessions = [];
+    let next = { kind: 'list_start' };
+    for (let page = 0; page < CATALOG_PAGES_MAX; page += 1) {
+        const outcome = await query(next);
+        if (!outcome.ok || outcome.result.kind !== 'page')
+            break;
+        for (const item of outcome.result.sessions) {
+            if (!('kind' in item))
+                sessions.push(item);
+        }
+        if (!outcome.result.nextCursor)
+            break;
+        next = {
+            kind: 'list_continue',
+            revision: outcome.result.revision,
+            cursor: outcome.result.nextCursor,
+        };
+    }
+    return sessions;
+}
+/** Maps what the Host recorded about one Session into the check-in's view of it. */
+export function checkinSessionState(input) {
+    const turn = input.canonical.rootTurn;
+    const waitingForUser = input.session.status === 'waiting_for_user' ||
+        input.canonical.interactions.pending.length > 0 ||
+        turn?.status === 'waiting_for_user';
+    let lastTurn = null;
+    if (!turn && !waitingForUser)
+        lastTurn = recordedLastTurn(input.turns);
+    if (turn && !waitingForUser) {
+        if (turn.status === 'completed')
+            lastTurn = { status: 'completed' };
+        else if (turn.status === 'failed') {
+            lastTurn = {
+                status: 'failed',
+                failureClass: turn.failureClass,
+                ...(turn.failureMessage ? { failureMessage: turn.failureMessage } : {}),
+            };
+        }
+        else if (turn.status === 'cancelled') {
+            lastTurn = { status: 'cancelled', abortSource: turn.abortSource };
+        }
+        else
+            lastTurn = { status: 'in_progress' };
+    }
+    const goal = input.canonical.goal;
+    const texts = [];
+    for (const message of input.messages) {
+        if (message.type === 'user' && !message.origin && typeof message.text === 'string') {
+            texts.push({ role: 'user', text: userFacingText(message) });
+        }
+        else if (message.type === 'assistant' && typeof message.text === 'string') {
+            texts.push({ role: 'assistant', text: message.text });
+        }
+    }
+    const first = texts.find((message) => message.role === 'user');
+    const recent = texts.slice(-MESSAGES_KEPT);
+    return {
+        sessionId: input.session.id,
+        revision: input.session.revision,
+        name: input.session.name,
+        activityAt: input.session.activityAt,
+        lastTurn,
+        waitingForUser,
+        goal: goal
+            ? { status: goal.status, condition: goal.condition, lastReason: goal.lastReason }
+            : null,
+        todos: input.todos,
+        messages: first && !recent.includes(first) ? [first, ...recent] : recent,
+    };
+}
+/**
+ * A Session written before Root Turn admissions, or imported, still carries
+ * `turn_state` records. Only a recorded status counts; an inferred one is a
+ * reading of old data, not evidence.
+ */
+function recordedLastTurn(turns) {
+    const turn = turns.at(-1);
+    if (!turn || turn.statusSource !== 'recorded')
+        return null;
+    switch (turn.status) {
+        case 'completed':
+            return { status: 'completed' };
+        case 'failed':
+            return {
+                status: 'failed',
+                failureClass: turn.errorClass ?? 'unknown',
+                ...(turn.failureMessage ? { failureMessage: turn.failureMessage } : {}),
+            };
+        case 'aborted':
+            return { status: 'cancelled', abortSource: turn.abortSource ?? 'unknown' };
+        case 'running':
+            return { status: 'in_progress' };
+    }
+}
+/** Judged from the catalog row alone, before any Session is read in full. */
+export function checkinMayRead(session, now) {
+    return (!session.isArchived &&
+        !session.subagent &&
+        !session.parentSessionId &&
+        session.backend === 'ai-sdk' &&
+        session.status !== 'running' &&
+        !(session.liveRunState?.runningTurnIds.length ?? 0) &&
+        !isWorkHubCoordinationSessionId(session.id) &&
+        !session.labels.some((label) => EXCLUDED_LABELS.has(label)) &&
+        session.activityAt >= now - CHECKIN_LOOKBACK_MS);
+}
+function draining() {
+    return { ok: false, error: { code: 'host_draining', message: 'Runtime Host is draining' } };
+}

package/node_modules/@maka/runtime-host/dist/server/session-checkpoint-coordinator.js

@@ -0,0 +1,282 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { randomUUID } from 'node:crypto';
+import { publishSessionCheckpointV1, SessionRepositoryError, } from '@maka/storage/session-repository';
+import { SessionSnapshotError } from '@maka/storage/quiescent-session-snapshot';
+export class HostCheckpointError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'HostCheckpointError';
+    }
+}
+/** Explicit management API, not a model tool, automatic live write, or second Head. */
+export class HostSessionCheckpointCoordinator {
+    dependencies;
+    #active = new Set();
+    #drain = new AbortController();
+    #closed = false;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    publish(input) {
+        if (this.#closed)
+            return Promise.reject(new HostCheckpointError('closed', 'Checkpoint publication is closed'));
+        const accepted = { ...input };
+        if (!validId(accepted.sessionId) ||
+            !validId(accepted.requestId) ||
+            (accepted.signal !== undefined && !(accepted.signal instanceof AbortSignal)) ||
+            (accepted.confirmationGrantId !== undefined &&
+                !/^[A-Za-z0-9_-]{1,128}$/u.test(accepted.confirmationGrantId)) ||
+            (accepted.deadlineAt !== undefined && !Number.isSafeInteger(accepted.deadlineAt))) {
+            return Promise.reject(new HostCheckpointError('invalid_input', 'Invalid checkpoint publication request'));
+        }
+        // Cooperative deadline for the whole attempt, not part of commit identity.
+        const deadlineAt = Math.min(accepted.deadlineAt ?? Infinity, Date.now() + 60_000);
+        if (deadlineAt <= Date.now())
+            return Promise.reject(new HostCheckpointError('cancelled', 'Checkpoint deadline has expired'));
+        const timer = AbortSignal.timeout(Math.max(0, deadlineAt - Date.now()));
+        const signal = AbortSignal.any([
+            timer,
+            this.#drain.signal,
+            ...(accepted.signal ? [accepted.signal] : []),
+        ]);
+        const task = this.dependencies
+            .runAuthorized(() => this.#publish(accepted, signal, deadlineAt))
+            .catch((error) => {
+            throw normalizeError(error);
+        });
+        this.#active.add(task);
+        void task.finally(() => this.#active.delete(task)).catch(() => { });
+        return task;
+    }
+    beginDrain() {
+        this.#closed = true;
+        this.#drain.abort();
+    }
+    async close() {
+        this.beginDrain();
+        await Promise.allSettled([...this.#active]);
+    }
+    async #publish(input, signal, deadlineAt) {
+        const deps = this.dependencies;
+        signal.throwIfAborted();
+        return deps.journal.withSession(input.sessionId, async (document, save) => {
+            signal.throwIfAborted();
+            const releaseBundle = async (position) => {
+                const pending = document.requests[position];
+                if (!pending.bundleCleanupPending)
+                    return 'released';
+                try {
+                    await deps.cleanupBundle(pending.commitId);
+                    const { bundleCleanupPending: _pending, ...released } = pending;
+                    document.requests[position] = released;
+                    try {
+                        await save();
+                    }
+                    catch (error) {
+                        document.requests[position] = pending;
+                        throw error;
+                    }
+                    return 'released';
+                }
+                catch {
+                    // The terminal outcome is already durable. Retain cleanup ownership
+                    // for the next request/restart, without changing that outcome.
+                    return 'pending_recovery';
+                }
+            };
+            let index = document.requests.findIndex((request) => request.requestId === input.requestId);
+            let request = document.requests[index];
+            if (request && request.confirmationGrantId !== input.confirmationGrantId) {
+                throw new HostCheckpointError('conflict', 'Checkpoint request identity was reused with different input');
+            }
+            // Holding this process-safe lock proves no earlier capture is still running.
+            // Its bytes were never durably fixed, so the identity can only be aborted.
+            for (let position = 0; position < document.requests.length; position++) {
+                const previous = document.requests[position];
+                if (previous.phase === 'capturing') {
+                    document.requests[position] = { ...previous, phase: 'aborted' };
+                    await save();
+                }
+                if (previous.phase !== 'prepared')
+                    await releaseBundle(position);
+            }
+            request = document.requests[index];
+            if (request?.phase === 'aborted') {
+                throw new HostCheckpointError('interrupted', 'Snapshot capture did not complete; use a new request identity');
+            }
+            if (request?.phase === 'conflicted')
+                throw new HostCheckpointError('conflict', 'Checkpoint publication previously conflicted');
+            if (!request) {
+                if (document.requests.some((record) => record.phase === 'prepared')) {
+                    throw new HostCheckpointError('busy', 'A prepared checkpoint must be reconciled using its original request identity');
+                }
+                let current;
+                try {
+                    current = await deps.repository.checkoutCurrent(document.binding.repositorySessionId);
+                }
+                catch (error) {
+                    if (!(error instanceof SessionRepositoryError) || error.code !== 'session_not_found')
+                        throw error;
+                }
+                if (current && current.agentId !== document.binding.agentId) {
+                    throw new HostCheckpointError('conflict', 'Repository Session binding does not match this Host');
+                }
+                request = {
+                    requestId: input.requestId,
+                    commitId: randomUUID(),
+                    ...(input.confirmationGrantId ? { confirmationGrantId: input.confirmationGrantId } : {}),
+                    expectedRevision: current?.ref.revision ?? null,
+                    bundleCleanupPending: true,
+                    phase: 'capturing',
+                };
+                index = document.requests.length;
+                document.requests.push(request);
+                await save();
+                signal.throwIfAborted();
+                const artifact = await deps.capture({
+                    binding: document.binding,
+                    commitId: request.commitId,
+                    confirmationGrantId: input.confirmationGrantId,
+                    signal,
+                    deadlineAt,
+                });
+                signal.throwIfAborted();
+                const checkpoint = await publishSessionCheckpointV1({
+                    objectStore: deps.objects,
+                    compatibilityBundle: artifact,
+                });
+                request = {
+                    ...request,
+                    phase: 'prepared',
+                    checkpoint,
+                    ...(artifact.snapshotCleanup.state === 'pending_recovery'
+                        ? { snapshotCleanupPending: true }
+                        : {}),
+                };
+                document.requests[index] = request;
+                // On an uncertain journal write, leave recovery to a fresh read. Never
+                // overwrite a possibly prepared record with a fabricated failure.
+                await save();
+            }
+            if (request.phase === 'committed') {
+                await deps.objects.assertReadable(request.checkpoint.manifest);
+                await deps.objects.assertReadable(request.checkpoint.value.compatibilityBundle);
+                return structuredClone({
+                    requestId: request.requestId,
+                    binding: document.binding,
+                    committed: request.result,
+                    stagingCleanup: request.snapshotCleanupPending ? 'pending_recovery' : 'released',
+                    bundleCleanup: request.bundleCleanupPending ? 'pending_recovery' : 'released',
+                });
+            }
+            if (request.phase !== 'prepared')
+                throw new Error('Invalid checkpoint publication transition');
+            signal.throwIfAborted();
+            // No cancellation point between CAS and receipt persistence: after CAS
+            // succeeds, reporting cancellation would falsely suggest nothing committed.
+            let committed;
+            try {
+                committed =
+                    request.expectedRevision === null
+                        ? await deps.repository
+                            .createSession({
+                            sessionId: document.binding.repositorySessionId,
+                            agentId: document.binding.agentId,
+                            checkpoint: request.checkpoint,
+                        })
+                            .catch(async (error) => {
+                            if (!(error instanceof SessionRepositoryError) ||
+                                error.code !== 'session_already_exists')
+                                throw error;
+                            const existing = await deps.repository.checkoutCurrent(document.binding.repositorySessionId);
+                            if (existing.agentId !== document.binding.agentId ||
+                                existing.forkedFrom !== undefined ||
+                                existing.lastCommittedActivationId !== undefined ||
+                                JSON.stringify(existing.checkpoint) !== JSON.stringify(request.checkpoint))
+                                throw error;
+                            return existing;
+                        })
+                        : await deps.repository.commit({
+                            sessionId: document.binding.repositorySessionId,
+                            expectedRevision: request.expectedRevision,
+                            checkpoint: request.checkpoint,
+                            commitId: request.commitId,
+                        });
+            }
+            catch (error) {
+                if (error instanceof SessionRepositoryError &&
+                    ['revision_conflict', 'session_already_exists', 'idempotency_conflict'].includes(error.code)) {
+                    document.requests[index] = { ...request, phase: 'conflicted' };
+                    await save();
+                    await releaseBundle(index);
+                }
+                throw error;
+            }
+            const completed = {
+                ...request,
+                phase: 'committed',
+                result: committed,
+            };
+            document.requests[index] = completed;
+            await save();
+            const bundleCleanup = await releaseBundle(index);
+            return structuredClone({
+                requestId: request.requestId,
+                binding: document.binding,
+                committed,
+                stagingCleanup: request.snapshotCleanupPending ? 'pending_recovery' : 'released',
+                bundleCleanup,
+            });
+        });
+    }
+}
+function validId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/u.test(value);
+}
+function normalizeError(error) {
+    if (error instanceof HostCheckpointError)
+        return error;
+    // The generic snapshot layer wraps Host eligibility failures. Preserve their
+    // bounded public classification without exposing arbitrary provider errors.
+    if (error instanceof SessionSnapshotError && error.cause instanceof HostCheckpointError)
+        return error.cause;
+    if (error instanceof SessionRepositoryError) {
+        const code = ['revision_conflict', 'session_already_exists', 'idempotency_conflict'].includes(error.code)
+            ? 'conflict'
+            : 'publication_failed';
+        return new HostCheckpointError(code, 'Checkpoint Repository rejected publication', {
+            cause: error,
+        });
+    }
+    if (error instanceof SessionSnapshotError) {
+        if (error.code === 'snapshot_busy' || error.code === 'session_not_quiescent') {
+            return new HostCheckpointError('busy', 'Session is not quiescent', { cause: error });
+        }
+    }
+    if ((error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) ||
+        (error instanceof SessionSnapshotError && error.code === 'snapshot_cancelled')) {
+        return new HostCheckpointError('cancelled', 'Checkpoint publication attempt was cancelled', {
+            cause: error,
+        });
+    }
+    return new HostCheckpointError('publication_failed', 'Checkpoint publication failed; retry the same request to reconcile', { cause: error });
+}