@a5c-ai/babysitter-sdk 0.0.187-staging.cbc8da4a → 0.0.187-staging.cbd8dccc

package/dist/api/effects.d.ts

@@ -0,0 +1,87 @@
+/**
+ * GAP-JSON-002: Effect Dispatch and Response Protocol.
+ *
+ * Typed API wrappers for listing, showing, cancelling, and batch-committing
+ * effects.  All functions return ApiResult envelopes and never throw.
+ */
+import type { ApiResult } from "./runs";
+import type { JsonRecord } from "../storage/types";
+type EffectStatusFilter = "requested" | "resolved" | "cancelled";
+type EffectStatusOutput = "requested" | "resolved_ok" | "resolved_error" | "cancelled";
+export interface ListEffectsInput {
+    runDir: string;
+    filter?: {
+        kind?: string | string[];
+        status?: EffectStatusFilter;
+    };
+}
+export interface EffectSummary {
+    effectId: string;
+    kind?: string;
+    status: EffectStatusOutput;
+    taskId?: string;
+    labels?: string[];
+    requestedAt?: string;
+    resolvedAt?: string;
+}
+export interface ListEffectsOutput {
+    effects: EffectSummary[];
+}
+export interface ShowEffectInput {
+    runDir: string;
+    effectId: string;
+}
+export interface ShowEffectOutput {
+    effectId: string;
+    kind?: string;
+    status: EffectStatusOutput;
+    taskId?: string;
+    labels?: string[];
+    requestedAt?: string;
+    resolvedAt?: string;
+    taskDefinition?: JsonRecord;
+    result?: unknown;
+    autoApproval?: unknown;
+}
+export interface CancelEffectInput {
+    runDir: string;
+    effectId: string;
+    reason?: string;
+}
+export interface CancelEffectOutput {
+    resultRef: string;
+}
+export interface BatchCommitEffectEntry {
+    effectId: string;
+    result: {
+        status: "ok" | "error";
+        value?: unknown;
+        error?: string;
+        stdout?: string;
+        stderr?: string;
+        stdoutRef?: string;
+        stderrRef?: string;
+        startedAt?: string;
+        finishedAt?: string;
+        metadata?: JsonRecord;
+    };
+}
+export interface BatchCommitEffectsInput {
+    runDir: string;
+    effects: BatchCommitEffectEntry[];
+}
+export interface BatchCommitEffectResult {
+    effectId: string;
+    ok: boolean;
+    resultRef?: string;
+    error?: string;
+}
+export interface BatchCommitEffectsOutput {
+    results: BatchCommitEffectResult[];
+}
+export declare function apiListEffects(input: ListEffectsInput): Promise<ApiResult<ListEffectsOutput>>;
+export declare function apiShowEffect(input: ShowEffectInput): Promise<ApiResult<ShowEffectOutput>>;
+export declare function apiCancelEffect(input: CancelEffectInput): Promise<ApiResult<CancelEffectOutput>>;
+export declare function apiBatchCommitEffects(input: BatchCommitEffectsInput): Promise<ApiResult<BatchCommitEffectsOutput>>;
+export {};
+//# sourceMappingURL=effects.d.ts.map

package/dist/api/effects.d.ts.map

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

package/dist/api/effects.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * GAP-JSON-002: Effect Dispatch and Response Protocol.
+ *
+ * Typed API wrappers for listing, showing, cancelling, and batch-committing
+ * effects.  All functions return ApiResult envelopes and never throw.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiListEffects = apiListEffects;
+exports.apiShowEffect = apiShowEffect;
+exports.apiCancelEffect = apiCancelEffect;
+exports.apiBatchCommitEffects = apiBatchCommitEffects;
+const fs_1 = require("fs");
+const journal_1 = require("../storage/journal");
+const tasks_1 = require("../storage/tasks");
+const lock_1 = require("../storage/lock");
+const serializer_1 = require("../tasks/serializer");
+// ── Result envelope helpers (mirror runs.ts) ───────────────────────────────
+function ok(data) {
+    return { ok: true, data };
+}
+function fail(code, message) {
+    return { ok: false, error: { code, message } };
+}
+async function pathExists(p) {
+    try {
+        await fs_1.promises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function buildEffectInfoMap(events) {
+    const effects = new Map();
+    for (const event of events) {
+        if (event.type === "EFFECT_REQUESTED") {
+            const data = event.data;
+            const effectId = data.effectId;
+            if (!effectId)
+                continue;
+            effects.set(effectId, {
+                effectId,
+                kind: typeof data.kind === "string" ? data.kind : undefined,
+                taskId: typeof data.taskId === "string" ? data.taskId : undefined,
+                labels: Array.isArray(data.labels) ? data.labels : undefined,
+                status: "requested",
+                requestedAt: event.recordedAt,
+            });
+        }
+        else if (event.type === "EFFECT_RESOLVED") {
+            const data = event.data;
+            const effectId = data.effectId;
+            if (!effectId)
+                continue;
+            const existing = effects.get(effectId);
+            if (existing) {
+                const resultStatus = data.status;
+                existing.status = resultStatus === "error" ? "resolved_error" : "resolved_ok";
+                existing.resolvedAt = event.recordedAt;
+            }
+        }
+        else if (event.type === "EFFECT_CANCELLED") {
+            const data = event.data;
+            const effectId = data.effectId;
+            if (!effectId)
+                continue;
+            const existing = effects.get(effectId);
+            if (existing) {
+                existing.status = "cancelled";
+                existing.resolvedAt = event.recordedAt;
+            }
+        }
+    }
+    return effects;
+}
+// ── API functions ──────────────────────────────────────────────────────────
+async function apiListEffects(input) {
+    try {
+        if (!input.runDir) {
+            return fail("INVALID_INPUT", "runDir must be a non-empty string");
+        }
+        if (!(await pathExists(input.runDir))) {
+            return fail("RUN_NOT_FOUND", `Run directory not found: ${input.runDir}`);
+        }
+        const events = await (0, journal_1.loadJournal)(input.runDir);
+        const effectMap = buildEffectInfoMap(events);
+        let effects = Array.from(effectMap.values());
+        // Apply filters
+        if (input.filter) {
+            if (input.filter.kind !== undefined) {
+                const kinds = Array.isArray(input.filter.kind) ? input.filter.kind : [input.filter.kind];
+                effects = effects.filter((e) => e.kind !== undefined && kinds.includes(e.kind));
+            }
+            if (input.filter.status !== undefined) {
+                const statusFilter = input.filter.status;
+                effects = effects.filter((e) => {
+                    if (statusFilter === "requested")
+                        return e.status === "requested";
+                    if (statusFilter === "resolved")
+                        return e.status === "resolved_ok" || e.status === "resolved_error";
+                    if (statusFilter === "cancelled")
+                        return e.status === "cancelled";
+                    return true;
+                });
+            }
+        }
+        // Sort by effectId ascending
+        effects.sort((a, b) => a.effectId.localeCompare(b.effectId));
+        return ok({
+            effects: effects.map((e) => ({
+                effectId: e.effectId,
+                kind: e.kind,
+                status: e.status,
+                taskId: e.taskId,
+                labels: e.labels,
+                requestedAt: e.requestedAt,
+                resolvedAt: e.resolvedAt,
+            })),
+        });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return fail("INTERNAL_ERROR", msg);
+    }
+}
+async function apiShowEffect(input) {
+    try {
+        if (!input.runDir) {
+            return fail("INVALID_INPUT", "runDir must be a non-empty string");
+        }
+        if (!input.effectId) {
+            return fail("INVALID_INPUT", "effectId must be a non-empty string");
+        }
+        if (!(await pathExists(input.runDir))) {
+            return fail("RUN_NOT_FOUND", `Run directory not found: ${input.runDir}`);
+        }
+        const events = await (0, journal_1.loadJournal)(input.runDir);
+        const effectMap = buildEffectInfoMap(events);
+        const info = effectMap.get(input.effectId);
+        if (!info) {
+            return fail("EFFECT_NOT_FOUND", `Effect not found: ${input.effectId}`);
+        }
+        // Read task definition
+        const taskDef = await (0, tasks_1.readTaskDefinition)(input.runDir, input.effectId);
+        // Read result if resolved
+        let resultData = null;
+        if (info.status === "resolved_ok" || info.status === "resolved_error") {
+            const storedResult = await (0, tasks_1.readTaskResult)(input.runDir, input.effectId);
+            resultData = storedResult ?? null;
+        }
+        const output = {
+            effectId: info.effectId,
+            kind: info.kind,
+            status: info.status,
+            taskId: info.taskId,
+            labels: info.labels,
+            requestedAt: info.requestedAt,
+            resolvedAt: info.resolvedAt,
+            taskDefinition: taskDef ?? undefined,
+            result: resultData === null ? undefined : resultData,
+        };
+        // Include autoApproval for breakpoint effects
+        if (info.kind === "breakpoint" || info.taskId === "__sdk.breakpoint") {
+            if (taskDef && typeof taskDef === "object") {
+                const autoApproval = taskDef.autoApproval;
+                if (autoApproval !== undefined) {
+                    output.autoApproval = autoApproval;
+                }
+            }
+        }
+        return ok(output);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return fail("INTERNAL_ERROR", msg);
+    }
+}
+async function apiCancelEffect(input) {
+    try {
+        if (!input.runDir) {
+            return fail("INVALID_INPUT", "runDir must be a non-empty string");
+        }
+        if (!input.effectId) {
+            return fail("INVALID_INPUT", "effectId must be a non-empty string");
+        }
+        if (!(await pathExists(input.runDir))) {
+            return fail("RUN_NOT_FOUND", `Run directory not found: ${input.runDir}`);
+        }
+        return await (0, lock_1.withRunLock)(input.runDir, "api:cancelEffect", async () => {
+            const events = await (0, journal_1.loadJournal)(input.runDir);
+            const effectMap = buildEffectInfoMap(events);
+            const info = effectMap.get(input.effectId);
+            if (!info) {
+                return fail("EFFECT_NOT_FOUND", `Effect not found: ${input.effectId}`);
+            }
+            if (info.status !== "requested") {
+                return fail("EFFECT_NOT_PENDING", `Effect ${input.effectId} is not pending (status=${info.status})`);
+            }
+            // Extract taskId and invocationKey from the EFFECT_REQUESTED event
+            const requestedEvent = events.find((e) => e.type === "EFFECT_REQUESTED" && e.data.effectId === input.effectId);
+            const eventData = requestedEvent?.data;
+            const taskId = eventData?.taskId ?? `task-${input.effectId}`;
+            const invocationKey = eventData?.invocationKey ?? `key-${input.effectId}`;
+            const { resultRef } = await (0, serializer_1.serializeAndWriteTaskResult)({
+                runDir: input.runDir,
+                effectId: input.effectId,
+                taskId,
+                invocationKey,
+                payload: {
+                    status: "cancelled",
+                    reason: input.reason,
+                    error: { name: "EffectCancelledError", message: input.reason ?? "Effect cancelled" },
+                    metadata: { cancelled: true, reason: input.reason },
+                },
+            });
+            await (0, journal_1.appendEvent)({
+                runDir: input.runDir,
+                eventType: "EFFECT_CANCELLED",
+                event: {
+                    effectId: input.effectId,
+                    reason: input.reason,
+                },
+            });
+            return ok({ resultRef });
+        });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return fail("INTERNAL_ERROR", msg);
+    }
+}
+async function apiBatchCommitEffects(input) {
+    try {
+        if (!input.runDir) {
+            return fail("INVALID_INPUT", "runDir must be a non-empty string");
+        }
+        if (!Array.isArray(input.effects)) {
+            return fail("INVALID_INPUT", "effects must be an array");
+        }
+        if (input.effects.length === 0) {
+            return fail("INVALID_INPUT", "effects array must not be empty");
+        }
+        const results = [];
+        for (const entry of input.effects) {
+            try {
+                const commitResult = await (0, lock_1.withRunLock)(input.runDir, "api:batchCommitEffect", async () => {
+                    // Load journal to find the effect metadata
+                    const events = await (0, journal_1.loadJournal)(input.runDir);
+                    const requestedEvent = events.find((e) => e.type === "EFFECT_REQUESTED" && e.data.effectId === entry.effectId);
+                    if (!requestedEvent) {
+                        throw new Error(`Unknown effectId ${entry.effectId}`);
+                    }
+                    const eventData = requestedEvent.data;
+                    const taskId = eventData.taskId ?? `task-${entry.effectId}`;
+                    const invocationKey = eventData.invocationKey ?? `key-${entry.effectId}`;
+                    // Check if already resolved
+                    const alreadyResolved = events.some((e) => (e.type === "EFFECT_RESOLVED" || e.type === "EFFECT_CANCELLED") &&
+                        e.data.effectId === entry.effectId);
+                    if (alreadyResolved) {
+                        throw new Error(`Effect ${entry.effectId} is already resolved`);
+                    }
+                    const resultPayload = entry.result.status === "ok"
+                        ? {
+                            status: "ok",
+                            result: entry.result.value,
+                            stdout: entry.result.stdout,
+                            stderr: entry.result.stderr,
+                            stdoutRef: entry.result.stdoutRef,
+                            stderrRef: entry.result.stderrRef,
+                            startedAt: entry.result.startedAt,
+                            finishedAt: entry.result.finishedAt,
+                            metadata: entry.result.metadata,
+                        }
+                        : {
+                            status: "error",
+                            error: { name: "Error", message: entry.result.error ?? "Unknown error" },
+                            stdout: entry.result.stdout,
+                            stderr: entry.result.stderr,
+                            stdoutRef: entry.result.stdoutRef,
+                            stderrRef: entry.result.stderrRef,
+                            startedAt: entry.result.startedAt,
+                            finishedAt: entry.result.finishedAt,
+                            metadata: entry.result.metadata,
+                        };
+                    const { resultRef, stdoutRef, stderrRef } = await (0, serializer_1.serializeAndWriteTaskResult)({
+                        runDir: input.runDir,
+                        effectId: entry.effectId,
+                        taskId,
+                        invocationKey,
+                        payload: resultPayload,
+                    });
+                    await (0, journal_1.appendEvent)({
+                        runDir: input.runDir,
+                        eventType: "EFFECT_RESOLVED",
+                        event: {
+                            effectId: entry.effectId,
+                            status: entry.result.status,
+                            resultRef,
+                            stdoutRef: stdoutRef ?? undefined,
+                            stderrRef: stderrRef ?? undefined,
+                            startedAt: resultPayload.startedAt,
+                            finishedAt: resultPayload.finishedAt,
+                        },
+                    });
+                    return { resultRef };
+                });
+                results.push({
+                    effectId: entry.effectId,
+                    ok: true,
+                    resultRef: commitResult.resultRef,
+                });
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                results.push({
+                    effectId: entry.effectId,
+                    ok: false,
+                    error: msg,
+                });
+            }
+        }
+        return ok({ results });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return fail("INTERNAL_ERROR", msg);
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,5 @@
+export { apiCreateRun, apiIterate, apiCommitEffect, apiRunStatus, apiRunEvents, } from "./runs";
+export type { ApiResult, ApiCreateRunInput, ApiIterateOutput, RunStatusOutput, RunEventsOutput, } from "./runs";
+export { apiListEffects, apiShowEffect, apiCancelEffect, apiBatchCommitEffects, } from "./effects";
+export type { ListEffectsInput, ListEffectsOutput, EffectSummary, ShowEffectInput, ShowEffectOutput, CancelEffectInput, CancelEffectOutput, BatchCommitEffectEntry, BatchCommitEffectsInput, BatchCommitEffectResult, BatchCommitEffectsOutput, } from "./effects";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,QAAQ,CAAC;AAEhB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,WAAW,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiBatchCommitEffects = exports.apiCancelEffect = exports.apiShowEffect = exports.apiListEffects = exports.apiRunEvents = exports.apiRunStatus = exports.apiCommitEffect = exports.apiIterate = exports.apiCreateRun = void 0;
+var runs_1 = require("./runs");
+Object.defineProperty(exports, "apiCreateRun", { enumerable: true, get: function () { return runs_1.apiCreateRun; } });
+Object.defineProperty(exports, "apiIterate", { enumerable: true, get: function () { return runs_1.apiIterate; } });
+Object.defineProperty(exports, "apiCommitEffect", { enumerable: true, get: function () { return runs_1.apiCommitEffect; } });
+Object.defineProperty(exports, "apiRunStatus", { enumerable: true, get: function () { return runs_1.apiRunStatus; } });
+Object.defineProperty(exports, "apiRunEvents", { enumerable: true, get: function () { return runs_1.apiRunEvents; } });
+var effects_1 = require("./effects");
+Object.defineProperty(exports, "apiListEffects", { enumerable: true, get: function () { return effects_1.apiListEffects; } });
+Object.defineProperty(exports, "apiShowEffect", { enumerable: true, get: function () { return effects_1.apiShowEffect; } });
+Object.defineProperty(exports, "apiCancelEffect", { enumerable: true, get: function () { return effects_1.apiCancelEffect; } });
+Object.defineProperty(exports, "apiBatchCommitEffects", { enumerable: true, get: function () { return effects_1.apiBatchCommitEffects; } });

package/dist/api/runs.d.ts

@@ -0,0 +1,86 @@
+/**
+ * GAP-JSON-001: Programmatic API for run lifecycle.
+ *
+ * Thin typed wrappers over existing runtime functions with validation,
+ * error handling, and ApiResult envelopes.  These functions never throw.
+ */
+import type { EffectAction, IterationResult } from "../runtime/types";
+import type { JsonRecord } from "../storage/types";
+export type ApiResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface ApiCreateRunInput {
+    processId: string;
+    entrypoint: string;
+    runsDir: string;
+    inputs?: unknown;
+    prompt?: string;
+    harness?: string;
+}
+export interface ApiIterateOutput {
+    status: IterationResult["status"];
+    output?: unknown;
+    error?: unknown;
+    nextActions?: EffectAction[];
+    metadata?: unknown;
+}
+export interface RunStatusOutput {
+    state: "created" | "running" | "waiting" | "completed" | "failed";
+    processId: string;
+    runId: string;
+    pendingEffects: Array<{
+        effectId: string;
+        kind?: string;
+    }>;
+}
+export interface RunEventsOutput {
+    events: Array<{
+        seq: number;
+        type: string;
+        recordedAt: string;
+        data: JsonRecord;
+    }>;
+}
+export declare function apiCreateRun(input: ApiCreateRunInput): Promise<ApiResult<{
+    runId: string;
+    runDir: string;
+}>>;
+export declare function apiIterate(input: {
+    runDir: string;
+}): Promise<ApiResult<ApiIterateOutput>>;
+export declare function apiCommitEffect(input: {
+    runDir: string;
+    effectId: string;
+    result: {
+        status: "ok" | "error";
+        value?: unknown;
+        error?: string;
+        stdout?: string;
+        stderr?: string;
+        stdoutRef?: string;
+        stderrRef?: string;
+        startedAt?: string;
+        finishedAt?: string;
+        metadata?: JsonRecord;
+    };
+}): Promise<ApiResult<{
+    resultRef: string;
+}>>;
+export declare function apiRunStatus(input: {
+    runId: string;
+    runsDir: string;
+}): Promise<ApiResult<RunStatusOutput>>;
+export declare function apiRunEvents(input: {
+    runId: string;
+    runsDir: string;
+    limit?: number;
+    filterType?: string;
+}): Promise<ApiResult<RunEventsOutput>>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/api/runs.d.ts.map

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