@aiden-ade/sandbox-agent 0.1.59 → 0.1.60

package/dist/workspace-run-lease.js

@@ -0,0 +1,241 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { getDaemonCliEnvironment } from "./cli-executable.js";
+import { normalizeRepositoryIdentity } from "./workspace-relocation.js";
+export const WORKSPACE_LEASE_CHECK_INTERVAL_MS = 1_000;
+/**
+ * Git probe timeout. A single `git rev-parse` can overrun a tight 2s window under
+ * OS timer coalescing (backgrounded app / App Nap) or disk-IO contention even
+ * though the checkout is perfectly healthy, which the monitor would misread as a
+ * vanished workspace. Kept configurable; the consecutive-failure gate in the
+ * daemon monitor is the primary defense against a single slow probe.
+ */
+function parsePositiveMs(value, fallback) {
+    const parsed = value ? Number(value) : Number.NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export const WORKSPACE_LEASE_GIT_TIMEOUT_MS = parsePositiveMs(process.env.ALAN_WORKSPACE_LEASE_GIT_TIMEOUT_MS, 2_000);
+function gitValue(cwd, args) {
+    const result = spawnSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        env: getDaemonCliEnvironment(),
+        timeout: WORKSPACE_LEASE_GIT_TIMEOUT_MS,
+    });
+    if (result.status !== 0)
+        return null;
+    return result.stdout.trim() || null;
+}
+function filesystemIdentity(path) {
+    const canonicalPath = realpathSync.native(path);
+    const stat = statSync(canonicalPath);
+    return `${canonicalPath}:${stat.dev}:${stat.ino}`;
+}
+function resolveGitPath(workspacePath, value) {
+    return isAbsolute(value) ? value : resolve(workspacePath, value);
+}
+const DEFAULT_PROBE = {
+    snapshot: (workspacePath) => {
+        try {
+            const canonicalWorkspacePath = realpathSync.native(resolve(workspacePath));
+            const repositoryRoot = gitValue(canonicalWorkspacePath, ["rev-parse", "--show-toplevel"]);
+            const gitDirectory = gitValue(canonicalWorkspacePath, ["rev-parse", "--git-dir"]);
+            const commonDirectory = gitValue(canonicalWorkspacePath, ["rev-parse", "--git-common-dir"]);
+            const branch = gitValue(canonicalWorkspacePath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+            if (!repositoryRoot || !gitDirectory || !commonDirectory || !branch)
+                return null;
+            const remote = gitValue(canonicalWorkspacePath, ["config", "--get", "remote.origin.url"]);
+            const remoteIdentity = remote ? normalizeRepositoryIdentity(remote) : null;
+            return {
+                workspacePath: resolve(workspacePath),
+                workspaceIdentity: filesystemIdentity(canonicalWorkspacePath),
+                repositoryIdentity: `${filesystemIdentity(resolveGitPath(canonicalWorkspacePath, commonDirectory))}:${remoteIdentity ?? "local"}`,
+                worktreeIdentity: filesystemIdentity(resolveGitPath(canonicalWorkspacePath, gitDirectory)),
+                branch,
+            };
+        }
+        catch {
+            return null;
+        }
+    },
+    pathExists: (workspacePath) => {
+        try {
+            return existsSync(resolve(workspacePath));
+        }
+        catch {
+            // A permission/IO error while stat-ing is not proof the path is gone —
+            // treat as "present" (unknown) so it is classified retryable, not fatal.
+            return true;
+        }
+    },
+};
+function unavailableFailure(target) {
+    return {
+        code: "workspace_lease_unavailable",
+        message: "The workspace or Git checkout became unavailable while the run was active. Restore it and start a new run.",
+        workspacePath: target.workspacePath,
+        expectedBranch: target.expectedBranch,
+    };
+}
+function branchFailure(target, expectedBranch, actualBranch) {
+    return {
+        code: "workspace_lease_branch_changed",
+        message: `The workspace branch changed from ${expectedBranch} to ${actualBranch} while the run was active. Restore ${expectedBranch} and start a new run.`,
+        workspacePath: target.workspacePath,
+        expectedBranch,
+        actualBranch,
+    };
+}
+export class WorkspaceRunLease {
+    captured;
+    probe;
+    constructor(captured, probe) {
+        this.captured = captured;
+        this.probe = probe;
+    }
+    static capture(targets, probe = DEFAULT_PROBE) {
+        const captured = [];
+        for (const target of targets) {
+            const normalizedTarget = { ...target, workspacePath: resolve(target.workspacePath) };
+            const identity = probe.snapshot(normalizedTarget.workspacePath);
+            if (!identity)
+                return { lease: null, failure: unavailableFailure(normalizedTarget) };
+            if (normalizedTarget.expectedBranch && identity.branch !== normalizedTarget.expectedBranch) {
+                return {
+                    lease: null,
+                    failure: branchFailure(normalizedTarget, normalizedTarget.expectedBranch, identity.branch),
+                };
+            }
+            captured.push({ target: normalizedTarget, identity });
+        }
+        return {
+            lease: captured.length > 0 ? new WorkspaceRunLease(captured, probe) : null,
+            failure: null,
+        };
+    }
+    /**
+     * Classify the lease state for the run monitor.
+     *
+     * - `transient: true` — a null snapshot while the workspace path still exists:
+     *   the git probe timed out or failed transiently (OS throttling / IO
+     *   contention), NOT a vanished checkout. The monitor should retry (require N
+     *   consecutive transient failures) before declaring the workspace lost.
+     * - `transient: false` — a definitive change: the path is genuinely missing
+     *   (ENOENT), or the workspace/repository/worktree/branch identity changed.
+     *   These are real and fail fast.
+     */
+    verifyDetailed() {
+        for (const captured of this.captured) {
+            const current = this.probe.snapshot(captured.target.workspacePath);
+            if (!current) {
+                const pathGone = this.probe.pathExists?.(captured.target.workspacePath) === false;
+                return { failure: unavailableFailure(captured.target), transient: !pathGone };
+            }
+            if (current.workspaceIdentity !== captured.identity.workspaceIdentity) {
+                return {
+                    failure: {
+                        code: "workspace_lease_path_changed",
+                        message: "The selected workspace folder changed while the run was active. The run stopped before continuing; choose the correct folder and start a new run.",
+                        workspacePath: captured.target.workspacePath,
+                        expectedBranch: captured.identity.branch,
+                        actualBranch: current.branch,
+                    },
+                    transient: false,
+                };
+            }
+            if (current.repositoryIdentity !== captured.identity.repositoryIdentity ||
+                current.worktreeIdentity !== captured.identity.worktreeIdentity) {
+                return {
+                    failure: {
+                        code: "workspace_lease_repository_changed",
+                        message: "The workspace now points to a different repository or worktree. The run stopped before continuing; restore the original checkout and start a new run.",
+                        workspacePath: captured.target.workspacePath,
+                        expectedBranch: captured.identity.branch,
+                        actualBranch: current.branch,
+                    },
+                    transient: false,
+                };
+            }
+            if (current.branch !== captured.identity.branch) {
+                return {
+                    failure: branchFailure(captured.target, captured.identity.branch, current.branch),
+                    transient: false,
+                };
+            }
+        }
+        return { failure: null, transient: false };
+    }
+    verify() {
+        for (const captured of this.captured) {
+            const current = this.probe.snapshot(captured.target.workspacePath);
+            if (!current)
+                return unavailableFailure(captured.target);
+            if (current.workspaceIdentity !== captured.identity.workspaceIdentity) {
+                return {
+                    code: "workspace_lease_path_changed",
+                    message: "The selected workspace folder changed while the run was active. The run stopped before continuing; choose the correct folder and start a new run.",
+                    workspacePath: captured.target.workspacePath,
+                    expectedBranch: captured.identity.branch,
+                    actualBranch: current.branch,
+                };
+            }
+            if (current.repositoryIdentity !== captured.identity.repositoryIdentity ||
+                current.worktreeIdentity !== captured.identity.worktreeIdentity) {
+                return {
+                    code: "workspace_lease_repository_changed",
+                    message: "The workspace now points to a different repository or worktree. The run stopped before continuing; restore the original checkout and start a new run.",
+                    workspacePath: captured.target.workspacePath,
+                    expectedBranch: captured.identity.branch,
+                    actualBranch: current.branch,
+                };
+            }
+            if (current.branch !== captured.identity.branch) {
+                return branchFailure(captured.target, captured.identity.branch, current.branch);
+            }
+        }
+        return null;
+    }
+}
+export const FRESH_LEASE_MONITOR_STATE = {
+    transientStreak: 0,
+    nextCheckAtMs: 0,
+};
+/** Whether the monitor should probe this tick, or is still inside a backoff window. */
+export function isLeaseCheckDue(state, nowMs) {
+    return nowMs >= state.nextCheckAtMs;
+}
+/**
+ * Fold a `verifyDetailed()` result into the monitor state.
+ *
+ * - No failure → reset the streak, resume the normal cadence (`ok`).
+ * - Definitive failure → `fail` immediately (path/repo/branch changed, path gone).
+ * - Transient failure below the streak cap → `transient`: keep the run alive, bump
+ *   the streak, and back the next probe off exponentially (capped). This is what
+ *   stops a single slow/coalesced `git` probe from false-failing a healthy run.
+ * - Transient failure reaching the cap → `fail` (the workspace really is gone).
+ */
+export function applyLeaseCheckResult(input) {
+    const { detailed, nowMs, policy } = input;
+    if (!detailed.failure) {
+        return { action: "ok", state: { ...FRESH_LEASE_MONITOR_STATE } };
+    }
+    if (!detailed.transient) {
+        return { action: "fail", state: input.state, failure: detailed.failure };
+    }
+    const transientStreak = input.state.transientStreak + 1;
+    if (transientStreak >= policy.maxTransientFailures) {
+        return {
+            action: "fail",
+            state: { transientStreak, nextCheckAtMs: input.state.nextCheckAtMs },
+            failure: detailed.failure,
+        };
+    }
+    const backoffMs = Math.min(policy.backoffBaseMs * 2 ** (transientStreak - 1), policy.backoffMaxMs);
+    return {
+        action: "transient",
+        state: { transientStreak, nextCheckAtMs: nowMs + backoffMs },
+        failure: detailed.failure,
+        backoffMs,
+    };
+}
+//# sourceMappingURL=workspace-run-lease.js.map

package/dist/workspace-run-lease.js.map

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

package/dist/ws-client.d.ts

@@ -0,0 +1,194 @@
+import type { AlanMcpRegistration, TerminalRef, TerminalSnapshot } from "@alan-ai/shared/agent";
+import { type AgentRunState } from "@alan-ai/shared/agent-liveness";
+import type { AgentLifecycleContext, AgentLifecycleLogger } from "./lifecycle-logger.js";
+import type { AgentEvent } from "./types.js";
+export interface ResolvedImage {
+    id: string;
+    data: string;
+    mimeType: string;
+    filename: string;
+}
+export interface ResolvedFileAttachment {
+    id: string;
+    data: string;
+    mimeType: string;
+    filename: string;
+    size: number;
+    label: string;
+}
+export interface UserMessagePayload {
+    text: string;
+    images?: ResolvedImage[];
+    files?: ResolvedFileAttachment[];
+    providerSessionId?: string;
+    /**
+     * Compact recent transcript the runner injects when a `providerSessionId`
+     * resume fails on this turn (provider session store lost/corrupt on the
+     * machine). Server-computed per resume dispatch (buildSharedAgentPayload);
+     * carried here so interactive multi-turn resumes rehydrate with context
+     * instead of amnesiac. Only meaningful alongside `providerSessionId`.
+     */
+    resumeFallbackContext?: string;
+    backendKind?: string;
+    agentId?: string;
+    agentPrompt?: string;
+    selectedModel?: string;
+    selectedContextWindow?: string | null;
+    selectedEffortLevel?: string | null;
+    mode?: string;
+    /** Structured task metadata for system prompt injection. */
+    taskMeta?: {
+        id: string;
+        title: string;
+        description: string | null;
+        status: string;
+        priority: string;
+        labels: string[] | null;
+        assignees: Array<{
+            name: string | null;
+            email: string;
+        }>;
+        descriptionAttachmentIds?: Array<{
+            id: string;
+            filename: string;
+        }>;
+        linkedResources?: Array<{
+            id: string;
+            type: "document" | "whiteboard" | "url";
+            title: string;
+            url?: string;
+        }>;
+    };
+    /** Structured pull-request metadata for PR Review Agent sessions. */
+    prMeta?: {
+        prNumber: number;
+        owner: string;
+        repo: string;
+        title: string;
+        body?: string;
+        baseBranch: string;
+        headBranch: string;
+        author?: string;
+        state: "open" | "closed" | "merged";
+        mergeable?: boolean | null;
+        labels: string[];
+        changedFilesCount?: number;
+        additions?: number;
+        deletions?: number;
+        changedFiles?: Array<{
+            path: string;
+            status: string;
+            additions: number;
+            deletions: number;
+        }>;
+        linkedTaskReadableId?: string | null;
+        linkedTaskId?: string | null;
+        linkedTaskNumber?: number | null;
+        htmlUrl?: string;
+    };
+    /** Workflow tool allowlist (present when triggered from a workflow). */
+    workflowTools?: Array<{
+        type: string;
+        id: string;
+    }>;
+    /**
+     * Per-run Alan MCP registration (fresh PAT + run-scoped headers). When present
+     * the sandbox agent writes/refreshes the backend's MCP config before spawning
+     * the CLI instead of relying solely on provision-time injection.
+     */
+    alanMcp?: AlanMcpRegistration;
+    /** Agent run ID for status tracking. */
+    runId?: string;
+    /** Message ID that triggered this run. */
+    messageId?: string;
+    /** Maximum number of agent iterations. */
+    maxIterations?: number;
+    /** Task ID for MCP artifact creation. */
+    taskId?: string;
+    /** Cloud environment ID for telemetry correlation. */
+    cloudEnvironmentId?: string;
+    /** Conversation ID for MCP artifact creation. */
+    conversationId?: string;
+    /** Role attached to this conversation. */
+    /** Team ID of the active team context — injected into system prompt for MCP calls. */
+    teamId?: string;
+    /** User who initiated the run. */
+    currentUser?: {
+        id: string;
+        name: string | null;
+        email: string;
+    };
+    terminalContextRefs?: TerminalRef[];
+    terminalSnapshots?: TerminalSnapshot[];
+}
+export interface WSClientCallbacks {
+    /**
+     * Handle an incoming user message. May be synchronous or return a promise —
+     * either way, the `user_message` socket.io ack is held until this settles
+     * (see the handler in `setupListeners`), so the server only sees `ok:true`
+     * once the message is durably handed off (e.g. enqueued on the run loop),
+     * not merely received. Throwing or rejecting acks `{ ok: false }` so the
+     * server's delivery-failure handling treats the send as undelivered instead
+     * of silently dropping it.
+     */
+    onUserMessage: (payload: UserMessagePayload) => void | Promise<void>;
+    onStop: () => void;
+    onToolResponse?: (toolId: string, response: string) => void;
+    onConnect?: () => void;
+    onDisconnect?: (reason: string) => void;
+    /**
+     * Current run state for the liveness heartbeat. When omitted the agent is
+     * reported as idle. Called on every hello/heartbeat/probe.
+     */
+    getRunState?: () => AgentRunState;
+}
+export declare class WSClient {
+    private readonly lifecycle?;
+    private socket;
+    /** Stable id for this agent process; fences stale heartbeats server-side. */
+    private readonly agentSessionId;
+    /** Monotonic heartbeat sequence — advances on every hello + heartbeat. */
+    private heartbeatSeq;
+    private heartbeatTimer;
+    private readonly agentVersion;
+    private getRunState?;
+    /**
+     * Durable at-least-once delivery for stream events. Active only when
+     * `ALAN_EVENT_OUTBOX_ENABLED === "true"`; otherwise events are fired-and-
+     * forgotten exactly as before (see {@link SandboxEventDispatcher}).
+     */
+    private readonly eventDispatcher;
+    /**
+     * Bounded record of `messageId`s whose handoff to `onUserMessage` already
+     * completed successfully. A redelivered `user_message` for one of these ids
+     * (e.g. the original `ok:true` ack was lost in transit and the server's
+     * ≤5-attempt redelivery re-armed the run) is re-acked `{ ok: true }`
+     * without invoking the handler again, so the message is never processed
+     * twice. A `Set`'s insertion order doubles as recency, so eviction is just
+     * "drop the oldest key" — a minimal LRU without extra bookkeeping.
+     */
+    private readonly acceptedMessageIds;
+    constructor(wsUrl: string, sessionId: string, // conversationId
+    taskId: string, token: string, // sandboxSessionToken
+    callbacks: WSClientCallbacks, agentVersion?: string, lifecycle?: AgentLifecycleLogger | undefined);
+    /** Record a successfully-handed-off messageId, evicting the oldest entry past the cap. */
+    private rememberAcceptedMessageId;
+    /**
+     * Record the run id for events emitted from here on, so the durable outbox can
+     * bucket per-run caps and terminal-event condensation correctly. No-op when the
+     * outbox is disabled.
+     */
+    setCurrentRunId(runId: string | undefined): void;
+    private currentRunState;
+    private buildHeartbeat;
+    /** Emit `agent.hello` on (re)connect and (re)start the heartbeat interval. */
+    private startHeartbeat;
+    private stopHeartbeat;
+    emitEvent(event: AgentEvent): void;
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    get connected(): boolean;
+    setLifecycleContext(context: AgentLifecycleContext): void;
+    close(): void;
+    private setupListeners;
+}
+//# sourceMappingURL=ws-client.d.ts.map

package/dist/ws-client.d.ts.map

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