aiterm-mcp 0.60.0 → 0.61.0

package/dist/execution-checkpoint.js

@@ -0,0 +1,83 @@
+// Existing execution metadata only. Completion means the OS acknowledged the
+// file and directory sync operations, not native interruption/fence evidence.
+import * as fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { ExecutionError } from "./execution-wire.js";
+export const executionCheckpoint = "file_and_directory_sync.v1";
+/** Existing metadata directory entries only; no native effect or recovery. */
+export function syncExecutionDirectories(...directories) {
+    if (process.platform === "win32")
+        throw new ExecutionError("EXECUTION_UNSUPPORTED");
+    const synced = new Set();
+    for (const input of directories) {
+        let directory = path.resolve(input);
+        for (;;) {
+            if (synced.has(directory))
+                break;
+            let descriptor;
+            try {
+                descriptor = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY);
+                fs.fsyncSync(descriptor);
+                fs.closeSync(descriptor);
+                descriptor = undefined;
+            }
+            catch {
+                throw new ExecutionError("EXECUTION_STATE_UNAVAILABLE", "possible");
+            }
+            finally {
+                if (descriptor !== undefined) {
+                    try {
+                        fs.closeSync(descriptor);
+                    }
+                    catch { /* no native receipt */ }
+                }
+            }
+            synced.add(directory);
+            const parent = path.dirname(directory);
+            if (parent === directory)
+                break;
+            directory = parent;
+        }
+    }
+}
+/** A native operation must not run if any checkpoint step fails, including a
+ * directory flush after rename. The renamed state may then already be visible:
+ * do not roll it back, erase an issued slot or replay the native operation.
+ * Flush ancestors too: a newly-created scope directory must not depend on an
+ * unflushed parent entry. Unsupported filesystems/platforms fail closed.
+ */
+export function writeExecutionCheckpoint(file, value) {
+    if (process.platform === "win32")
+        throw new ExecutionError("EXECUTION_UNSUPPORTED");
+    const temporary = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+    let descriptor, renamed = false;
+    try {
+        descriptor = fs.openSync(temporary, "wx", 0o600);
+        fs.writeFileSync(descriptor, JSON.stringify(value, null, 2) + "\n");
+        fs.fchmodSync(descriptor, 0o600);
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        fs.renameSync(temporary, file);
+        renamed = true;
+        syncExecutionDirectories(path.dirname(file));
+    }
+    catch {
+        throw new ExecutionError("EXECUTION_STATE_UNAVAILABLE", "possible");
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fs.closeSync(descriptor);
+            }
+            catch { /* unavailable, never a native receipt */ }
+        }
+        if (!renamed) {
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch { /* no rollback of the committed state */ }
+        }
+    }
+}

package/dist/execution-close.js

@@ -0,0 +1,82 @@
+// Synchronous expected-generation close. The serving adapter must already own
+// the shared issued close slot; this helper does not replace admission/drain.
+import { executionLaunchSchema } from "./execution-contract.js";
+import { ExecutionError } from "./execution-wire.js";
+import { z } from "zod";
+export const executionNativeBindingSchema = z.object({ schema: z.literal("aiterm.execution-native.v1"),
+    native_id: z.string().regex(/^\$\d+$/),
+    server: z.object({ pid: z.number().int().positive(), started_identity: z.string().min(1).max(256) }).strict(),
+}).strict();
+export function parseExecutionNativeSessions(text) {
+    const sessions = [];
+    for (const line of text.split(/\r?\n/).filter(Boolean)) {
+        const parts = line.split("\t");
+        if (parts.length !== 2 || !/^\$\d+$/.test(parts[0])
+            || !executionLaunchSchema.shape.session_id.safeParse(parts[1]).success
+            || sessions.some(value => value.session_id === parts[1] || value.native_id === parts[0]))
+            return { state: "unknown" };
+        sessions.push({ native_id: parts[0], session_id: parts[1] });
+    }
+    return { state: "known", sessions };
+}
+export function closeExpectedExecution(input, bindings) {
+    const expected = executionLaunchSchema.parse(input);
+    const snapshot = () => {
+        try {
+            return bindings.sessions();
+        }
+        catch {
+            return { state: "unknown" };
+        }
+    };
+    const current = () => {
+        try {
+            const result = bindings.launch(expected.session_id);
+            return result ? executionLaunchSchema.parse(result) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const before = snapshot();
+    if (before.state !== "known")
+        throw new ExecutionError("EXECUTION_UNCONFIRMED", "not_started");
+    const target = before.sessions.find(value => value.session_id === expected.session_id);
+    if (!target)
+        return "already_closed";
+    const launch = current();
+    if (!launch)
+        throw new ExecutionError("EXECUTION_UNCONFIRMED", "not_started");
+    if (launch.session_id !== expected.session_id || launch.launch_id !== expected.launch_id)
+        throw new ExecutionError("EXECUTION_STALE_GENERATION", "not_started");
+    const ready = snapshot();
+    if (ready.state !== "known")
+        throw new ExecutionError("EXECUTION_UNCONFIRMED", "not_started");
+    const still = ready.sessions.find(value => value.session_id === expected.session_id);
+    if (!still)
+        return "already_closed";
+    if (still.native_id !== target.native_id)
+        throw new ExecutionError("EXECUTION_STALE_GENERATION", "not_started");
+    // Metadata must still agree after collecting native identity. No await or
+    // idle wait separates this check and the single synchronous native effect.
+    const last = current();
+    if (!last || last.session_id !== expected.session_id || last.launch_id !== expected.launch_id)
+        throw new ExecutionError(last ? "EXECUTION_STALE_GENERATION" : "EXECUTION_UNCONFIRMED", "not_started");
+    try {
+        if (bindings.kill(target.native_id).code !== 0)
+            throw new Error("native close unconfirmed");
+    }
+    catch (error) {
+        // The single native primitive's gate can refuse before dispatch. No
+        // earlier native effect exists inside this kill callback to hide here.
+        if (error instanceof ExecutionError && error.effect === "not_started")
+            throw error;
+        throw new ExecutionError("EXECUTION_UNCONFIRMED", "possible");
+    }
+    const after = snapshot();
+    if (after.state !== "known" || after.sessions.some(value => value.native_id === target.native_id))
+        throw new ExecutionError("EXECUTION_UNCONFIRMED", "possible");
+    // Do not clean by reusable name: another generation may already exist there.
+    // The serving service also performs its normal expected-seat post-observation.
+    return "closed";
+}

package/dist/execution-context.js

@@ -0,0 +1,19 @@
+// Existing serving request reference, captured by product code, never a tool
+// argument or a latest-active-job lookup. No issued native callback is stored.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { executionRequestSchema, executionPointSchema } from "./execution-contract.js";
+const requests = new AsyncLocalStorage();
+export function withExecutionRequest(input, body, ingress) {
+    const fixed = ingress ? structuredClone(ingress) : null;
+    if (fixed?.source)
+        fixed.source = executionPointSchema.parse(fixed.source);
+    return requests.run({ request: executionRequestSchema.parse(input), ingress: fixed }, body);
+}
+export function currentExecutionRequest() {
+    const context = requests.getStore();
+    return context ? structuredClone(context.request) : null;
+}
+export function currentExecutionIngress() {
+    const context = requests.getStore();
+    return context ? structuredClone(context) : null;
+}

package/dist/execution-contract.js

@@ -0,0 +1,263 @@
+// Contract and pure snapshot planning for the injectable execution service.
+// Production MCP/core runtime evidence and mutation adapters are not mounted.
+import { z } from "zod";
+const sessionId = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+const launchId = z.string().regex(/^[0-9a-f]{32}$/);
+const referenceId = z.string().min(1).max(256);
+export const executionLaunchSchema = z.object({
+    session_id: sessionId, launch_id: launchId,
+}).strict();
+// Existing references, normalized by the runtime adapter to an immutable run
+// boundary. A later native turn ID is an alias, not permission to rekey history.
+export const executionBoundarySchema = z.object({
+    event_cursor: z.number().int().nonnegative(),
+    operation_id: z.string().regex(/^sha256:[0-9a-f]{64}$/).nullable(),
+    turn_id: referenceId.nullable(),
+    steer_id: z.string().regex(/^[0-9a-f]{16}$/).nullable(),
+}).strict();
+export const executionPointSchema = z.object({
+    launch: executionLaunchSchema, boundary: executionBoundarySchema.nullable(),
+}).strict();
+// Scope is the serving local Aiterm. Remote scopes require an explicit adapter.
+// Room fan-out uses actual target, not just the requested responders.
+export const executionRequestSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("delivery"), delivery_id: referenceId, target_session_id: sessionId }).strict(),
+    z.object({ kind: z.literal("room"), message_id: referenceId, target_session_id: sessionId }).strict(),
+    z.object({ kind: z.literal("call"), call_session_id: referenceId,
+        event: z.enum(["session.message", "session.reply"]), seq: z.number().int().nonnegative(),
+        target_session_id: sessionId }).strict(),
+    z.object({ kind: z.literal("aiterm"), launch: executionLaunchSchema, boundary: executionBoundarySchema }).strict(),
+    // Existing JSON-RPC call identity, scoped by the serving process's native
+    // identity. No new job/delivery ID is allocated for direct stdio operations.
+    z.object({ kind: z.literal("mcp"), process_pid: z.number().int().positive(),
+        process_started_identity: referenceId,
+        request_id: z.union([referenceId, z.number().int().safe()]),
+        tool: z.enum(["agent_launch", "claude_agent", "codex_agent", "grok_agent", "pty_open", "pty_send", "pty_key", "pty_close",
+            "agent_configure", "agent_auth.start", "agent_auth.status", "agent_auth.cancel", "agent_approval.respond",
+            "claude_approval.respond", "claude_turn.issue"]), target_session_id: sessionId }).strict(),
+]);
+// Owner correction: interruption preserves the current session/launch and
+// conversation. The former close result is deliberately a different version.
+export const cascadeInterruptRequestSchema = z.object({
+    schema: z.literal("aiterm.cascade-stop-request.v2"), mode: z.literal("interrupt"),
+    roots: z.array(executionLaunchSchema).min(1),
+}).strict();
+export const cascadeInterruptResultObjectSchema = z.object({
+    schema: z.literal("aiterm.cascade-stop-result.v2"), mode: z.literal("interrupt"),
+    roots: z.array(executionLaunchSchema).min(1), status: z.enum(["confirmed", "partial", "unconfirmed"]),
+    relation_coverage: z.enum(["complete", "incomplete"]),
+    unresolved: z.array(z.object({ request: executionRequestSchema.nullable(), reason: z.string() }).strict()),
+    targets: z.array(z.object({ launch: executionLaunchSchema, run: executionPointSchema.nullable(),
+        key: z.enum(["Escape", "C-c"]).nullable(), key_receipt: z.enum(["not_sent", "accepted", "unknown"]),
+        interruption: z.enum(["interrupted", "already_idle", "unconfirmed", "unsupported", "replaced"]),
+        session_preserved: z.enum(["confirmed", "unconfirmed"]), reason: z.string(),
+    }).strict()),
+}).strict();
+export const cascadeInterruptResultSchema = cascadeInterruptResultObjectSchema.superRefine((value, context) => {
+    const confirmed = (target) => target.session_preserved === "confirmed"
+        && ["interrupted", "already_idle"].includes(target.interruption);
+    if (value.targets.some(target => (target.run && (target.run.launch.session_id !== target.launch.session_id
+        || target.run.launch.launch_id !== target.launch.launch_id))
+        || (target.key_receipt === "accepted" && !target.key)
+        || (target.interruption === "interrupted" && !target.run?.boundary)
+        || (target.interruption === "already_idle" && (target.key !== null || target.key_receipt !== "not_sent")))
+        || value.roots.some(root => !value.targets.some(target => target.launch.session_id === root.session_id && target.launch.launch_id === root.launch_id))
+        || (value.status === "confirmed" && (!value.targets.length || !value.targets.every(confirmed)
+            || value.relation_coverage !== "complete" || value.unresolved.length > 0))
+        || (value.status === "partial" && !value.targets.some(confirmed)))
+        context.addIssue({ code: "custom", message: "key receipt alone cannot confirm interruption or preserved-session coverage" });
+});
+// Mechanical operation type, never an interpretation of the message contents.
+// Mutation admission still fences/drains non-work operations; they do not
+// become an AI invocation edge merely because they touched another seat.
+export function executionRequestStartsWork(request) {
+    return request.kind !== "mcp" || ["agent_launch", "claude_agent", "codex_agent", "grok_agent", "pty_send", "pty_key",
+        "agent_approval.respond", "claude_approval.respond", "claude_turn.issue"].includes(request.tool);
+}
+export const executionSourceClaimSchema = z.object({
+    launch: executionLaunchSchema.nullable(),
+    boundary: executionBoundarySchema.nullable(),
+}).strict();
+function equal(a, b) { return JSON.stringify(a) === JSON.stringify(b); }
+export function assessExecutionSource(input, evidence) {
+    const claim = executionSourceClaimSchema.parse(input);
+    const runtime = evidence.runtime_launch && executionLaunchSchema.parse(evidence.runtime_launch);
+    const result = (status, reason) => ({ status, reason, point: null, boundary_status: "missing" });
+    if (!claim.launch || !runtime)
+        return result("unknown", "launch_unavailable");
+    if (!equal(claim.launch, runtime))
+        return result("stale", "launch_changed");
+    if (!evidence.caller_bound)
+        return result("unknown", "caller_unbound");
+    const boundary = evidence.invocation_boundary && executionBoundarySchema.parse(evidence.invocation_boundary);
+    const mismatch = !!boundary && !!claim.boundary && !equal(boundary, claim.boundary);
+    return { status: "verified", reason: "matched", point: { launch: runtime, boundary: mismatch ? null : boundary },
+        boundary_status: mismatch ? "mismatch" : boundary ? "matched" : "missing" };
+}
+function requestTarget(request) {
+    return request.kind === "aiterm" ? request.launch.session_id : request.target_session_id;
+}
+export const executionReservationSchema = z.object({
+    schema: z.literal("aiterm.execution-reservation.v1"), request: executionRequestSchema,
+    source: executionSourceClaimSchema,
+    target: z.object({ session_id: sessionId, expected_launch_id: launchId.nullable() }).strict(),
+}).strict().superRefine((value, context) => {
+    if (requestTarget(value.request) !== value.target.session_id || (value.request.kind === "aiterm"
+        && value.target.expected_launch_id !== value.request.launch.launch_id))
+        context.addIssue({ code: "custom", message: "reservation reference and target must identify the same execution" });
+});
+// Runtime-owned snapshot, NOT a public register/finish request. Completion must
+// be backed by the exact request/launch/boundary, not queue acceptance, a generic
+// delivery status, an aborted waiter, a timeout, or an idle snapshot alone.
+export const executionPhaseSchema = z.enum(["reserved", "invoked", "submitted_unknown", "unsent"]);
+export const executionRelationSchema = z.object({
+    request: executionRequestSchema,
+    source_session_id: sessionId.nullable(), // hint for reporting an unbound source only
+    source: executionPointSchema.nullable(), target: executionPointSchema.nullable(),
+    phase: executionPhaseSchema,
+    completion: z.enum(["open", "completed", "interrupted", "unknown"]),
+    target_fence: z.enum(["open", "closed", "unknown"]),
+    // Set after the recorded invocation and its known return/descendant work finish.
+    // This is relation lifetime, not proof that a CLI process has terminated.
+    // A retired edge is never revived by unrelated work on the same seat.
+    lifecycle: z.enum(["tracking", "retired"]),
+}).strict().superRefine((value, context) => {
+    if ((value.source && value.source_session_id !== value.source.launch.session_id)
+        || (value.target && requestTarget(value.request) !== value.target.launch.session_id)
+        || (value.target && value.request.kind === "aiterm" && !equal(value.request.launch, value.target.launch)))
+        context.addIssue({ code: "custom", message: "relation reference and bound execution disagree" });
+    if ((value.phase === "reserved" || value.phase === "unsent") && value.completion !== "open")
+        context.addIssue({ code: "custom", message: "an uninvoked reservation has no execution completion" });
+    if ((value.completion === "completed" && !value.target?.boundary)
+        || (value.completion === "interrupted" && !value.target))
+        context.addIssue({ code: "custom", message: "completion requires a bound run; generation-wide interruption requires a bound launch" });
+    if (value.lifecycle === "retired" && value.phase !== "unsent"
+        && (value.target_fence !== "closed" || (value.completion !== "completed" && value.completion !== "interrupted")))
+        context.addIssue({ code: "custom", message: "retirement requires terminal execution or confirmed unsent" });
+});
+/** Pure snapshot plan. No PTY, wall-clock cutoff, process, I/O or LLM judgment.
+ * Every reached launch is included even if shared with unrelated live work.
+ * Terminal history is excluded unless needed to reach unfinished descendants.
+ * Atomic runtime admission/draining and closure verification are separate work.
+ */
+function relationActivity(relations) {
+    const active = new Set();
+    const uncertainRetention = new Set();
+    for (let i = 0; i < relations.length; i++) {
+        const edge = relations[i];
+        if (!executionRequestStartsWork(edge.request))
+            continue;
+        if (edge.lifecycle !== "retired" && edge.phase !== "unsent"
+            && (edge.phase === "reserved" || edge.completion === "open" || edge.completion === "unknown" || edge.target_fence !== "closed"))
+            active.add(i);
+    }
+    // Least fixed point: all-terminal cycles expire. Completed parents remain
+    // connectors only for unfinished descendants of the same runtime execution.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (let i = 0; i < relations.length; i++) {
+            const edge = relations[i];
+            if (!executionRequestStartsWork(edge.request) || active.has(i) || edge.lifecycle === "retired" || edge.phase === "unsent" || !edge.target)
+                continue;
+            for (const j of active) {
+                const child = relations[j];
+                // A known unbound child candidate cannot silently prove the ancestor's
+                // branch complete. Retain only the already-recorded ancestor; do not
+                // fabricate or traverse that child's unbound generation edge.
+                const unboundChild = !child.source && child.source_session_id === edge.target.launch.session_id;
+                if (!unboundChild && (!child.source || !equal(edge.target.launch, child.source.launch)))
+                    continue;
+                const missing = unboundChild || !edge.target.boundary || !child.source?.boundary;
+                if (!missing && !equal(edge.target.boundary, child.source?.boundary))
+                    continue;
+                active.add(i);
+                if (missing)
+                    uncertainRetention.add(i);
+                changed = true;
+                break;
+            }
+        }
+    }
+    return { active, uncertainRetention };
+}
+export function unfinishedExecutionRelations(input) {
+    const relations = z.array(executionRelationSchema).parse(input);
+    return [...relationActivity(relations).active].map(index => relations[index]);
+}
+export function planCascadeStop(rootInput, relationInput) {
+    const roots = z.array(executionLaunchSchema).min(1).parse(rootInput);
+    const relations = z.array(executionRelationSchema).parse(relationInput);
+    const { active, uncertainRetention } = relationActivity(relations);
+    const plan = { targets: [], retained: [], cancel_reservations: [], gaps: [] };
+    const visited = new Set();
+    const reported = new Set();
+    const gap = (edge, reason) => {
+        const key = JSON.stringify([edge.request, reason]);
+        if (!reported.has(key)) {
+            reported.add(key);
+            plan.gaps.push({ request: edge.request, reason });
+        }
+    };
+    const queue = [...roots];
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const launch = queue[cursor];
+        const key = JSON.stringify(launch);
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        plan.targets.push(launch);
+        for (const i of active) {
+            const edge = relations[i];
+            if (!edge.source) {
+                if (edge.source_session_id === launch.session_id)
+                    gap(edge, "source_generation_missing");
+                continue;
+            }
+            if (!equal(edge.source.launch, launch))
+                continue;
+            plan.retained.push(edge.request);
+            if (edge.phase === "reserved") {
+                plan.cancel_reservations.push(edge.request);
+                continue;
+            }
+            if (!edge.target) {
+                gap(edge, "target_generation_missing");
+                continue;
+            }
+            queue.push(edge.target.launch);
+            if (!edge.source.boundary || !edge.target.boundary)
+                gap(edge, "run_boundary_missing");
+            if (edge.completion === "unknown")
+                gap(edge, "completion_missing");
+            if ((edge.completion === "completed" || edge.completion === "interrupted") && edge.target_fence !== "closed")
+                gap(edge, "invocation_fence_unconfirmed");
+            if (edge.phase === "submitted_unknown")
+                gap(edge, "invocation_outcome_unknown");
+            if (uncertainRetention.has(i))
+                gap(edge, "descendant_binding_missing");
+        }
+    }
+    return plan;
+}
+export const cascadeStopRequestSchema = z.object({
+    schema: z.literal("aiterm.cascade-stop-request.v1"), roots: z.array(executionLaunchSchema).min(1),
+}).strict();
+export const cascadeStopResultObjectSchema = z.object({
+    schema: z.literal("aiterm.cascade-stop-result.v1"), roots: z.array(executionLaunchSchema).min(1),
+    status: z.enum(["stopped", "partial", "unconfirmed"]), relation_coverage: z.enum(["complete", "incomplete"]),
+    unresolved: z.array(z.object({ request: executionRequestSchema.nullable(), reason: referenceId }).strict()),
+    targets: z.array(z.object({
+        launch: executionLaunchSchema,
+        outcome: z.enum(["closed", "already_closed", "unknown", "unsupported", "replaced"]),
+        reason: referenceId,
+    }).strict()),
+}).strict();
+export const cascadeStopResultSchema = cascadeStopResultObjectSchema.superRefine((value, context) => {
+    if (value.status !== "stopped")
+        return;
+    const closed = value.targets.filter(target => target.outcome === "closed" || target.outcome === "already_closed");
+    if (value.relation_coverage !== "complete" || value.unresolved.length || closed.length !== value.targets.length
+        || value.roots.some(root => !closed.some(target => equal(root, target.launch))))
+        context.addIssue({ code: "custom", message: "stopped requires complete relations, no unresolved work and every root/target closed" });
+});