@a5c-ai/genty-platform 5.1.1-staging.0007199a1cb2

package/dist/api/effectsTypes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type definitions for the effects API.
+ * Extracted from effects.ts for max-lines compliance.
+ */
+import type { JsonRecord } from "../types";
+export type EffectStatusFilter = "requested" | "resolved" | "cancelled";
+export 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[];
+}
+//# sourceMappingURL=effectsTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"effectsTypes.d.ts","sourceRoot":"","sources":["../../src/api/effectsTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;AACxE,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE9F,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAAG,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE;AAE/D,MAAM,WAAW,eAAe;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAErE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;AACxF,MAAM,WAAW,kBAAkB;IAAG,SAAS,EAAE,MAAM,CAAA;CAAE;AAEzD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE;QACN,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,UAAU,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,sBAAsB,EAAE,CAAA;CAAE;AAC9F,MAAM,WAAW,uBAAuB;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAC9G,MAAM,WAAW,wBAAwB;IAAG,OAAO,EAAE,uBAAuB,EAAE,CAAA;CAAE"}

package/dist/api/effectsTypes.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Type definitions for the effects API.
+ * Extracted from effects.ts for max-lines compliance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/eventStream.d.ts

@@ -0,0 +1,34 @@
+/**
+ * GAP-JSON-005: Event Stream API — subscription management.
+ *
+ * High-level API for subscribing to journal event streams.
+ * Wraps JournalWatcher with subscription tracking and ApiResult envelopes.
+ */
+import type { ApiResult } from "./runs";
+import type { JournalEvent } from "../storage/types";
+export interface SubscribeRunEventsInput {
+    runId: string;
+    runsDir?: string;
+    afterSeq?: number;
+    pollIntervalMs?: number;
+    onEvent: (event: JournalEvent) => void;
+    onError?: (error: Error) => void;
+    onDone?: () => void;
+}
+export interface SubscribeRunEventsOutput {
+    subscriptionId: string;
+    lastSeq: number;
+}
+export interface UnsubscribeRunEventsOutput {
+    lastSeq: number;
+}
+export declare function apiSubscribeRunEvents(input: SubscribeRunEventsInput): Promise<ApiResult<SubscribeRunEventsOutput>>;
+export declare function apiUnsubscribeRunEvents(input: {
+    subscriptionId: string;
+}): ApiResult<UnsubscribeRunEventsOutput>;
+export declare function getActiveSubscriptions(): Map<string, {
+    runId: string;
+    lastSeq: number;
+}>;
+export declare function closeAllSubscriptions(): void;
+//# sourceMappingURL=eventStream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eventStream.d.ts","sourceRoot":"","sources":["../../src/api/eventStream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAaD,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC,CAyC9C;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAChC,SAAS,CAAC,0BAA0B,CAAC,CAoBvC;AAED,wBAAgB,sBAAsB,IAAI,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CASxF;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}

package/dist/api/eventStream.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * GAP-JSON-005: Event Stream API — subscription management.
+ *
+ * High-level API for subscribing to journal event streams.
+ * Wraps JournalWatcher with subscription tracking and ApiResult envelopes.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiSubscribeRunEvents = apiSubscribeRunEvents;
+exports.apiUnsubscribeRunEvents = apiUnsubscribeRunEvents;
+exports.getActiveSubscriptions = getActiveSubscriptions;
+exports.closeAllSubscriptions = closeAllSubscriptions;
+const crypto = __importStar(require("node:crypto"));
+const path = __importStar(require("node:path"));
+const global_1 = require("../orchestration/global");
+const journalWatcher_1 = require("../storage/journalWatcher");
+const utils_1 = require("./utils");
+const subscriptions = new Map();
+// ── API functions ─────────────────────────────────────────────────────────
+async function apiSubscribeRunEvents(input) {
+    try {
+        if (!input.runId) {
+            return (0, utils_1.fail)("INVALID_INPUT", "runId must be a non-empty string");
+        }
+        if (typeof input.runsDir === "string" && input.runsDir.trim().length === 0) {
+            return (0, utils_1.fail)("INVALID_INPUT", "runsDir must be a non-empty string");
+        }
+        const runDir = path.join(input.runsDir ?? (0, global_1.getGlobalRegistry)().getOrchestration().resolveRunsDir(), input.runId);
+        if (!(await (0, utils_1.pathExists)(runDir))) {
+            return (0, utils_1.fail)("RUN_NOT_FOUND", `Run not found: ${input.runId}`);
+        }
+        const subscriptionId = crypto.randomUUID();
+        const watcher = (0, journalWatcher_1.createJournalWatcher)({
+            runDir,
+            afterSeq: input.afterSeq,
+            pollIntervalMs: input.pollIntervalMs,
+            onEvent: input.onEvent,
+            onError: input.onError,
+            onDone: () => {
+                // Clean up subscription Map when watcher auto-closes on terminal events
+                subscriptions.delete(subscriptionId);
+                if (input.onDone)
+                    input.onDone();
+            },
+        });
+        subscriptions.set(subscriptionId, {
+            runId: input.runId,
+            watcher,
+        });
+        return (0, utils_1.ok)({
+            subscriptionId,
+            lastSeq: watcher.lastSeenSeq,
+        });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return (0, utils_1.fail)("INTERNAL_ERROR", msg);
+    }
+}
+function apiUnsubscribeRunEvents(input) {
+    try {
+        if (!input.subscriptionId) {
+            return (0, utils_1.fail)("INVALID_INPUT", "subscriptionId must be a non-empty string");
+        }
+        const entry = subscriptions.get(input.subscriptionId);
+        if (!entry) {
+            return (0, utils_1.fail)("SUBSCRIPTION_NOT_FOUND", `Subscription not found: ${input.subscriptionId}`);
+        }
+        const lastSeq = entry.watcher.lastSeenSeq;
+        entry.watcher.close();
+        subscriptions.delete(input.subscriptionId);
+        return (0, utils_1.ok)({ lastSeq });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return (0, utils_1.fail)("INTERNAL_ERROR", msg);
+    }
+}
+function getActiveSubscriptions() {
+    const result = new Map();
+    for (const [id, entry] of subscriptions) {
+        result.set(id, {
+            runId: entry.runId,
+            lastSeq: entry.watcher.lastSeenSeq,
+        });
+    }
+    return result;
+}
+function closeAllSubscriptions() {
+    for (const [id, entry] of subscriptions) {
+        entry.watcher.close();
+        subscriptions.delete(id);
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,10 @@
+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, ShowEffectInput, ShowEffectOutput, CancelEffectInput, CancelEffectOutput, BatchCommitEffectsInput, BatchCommitEffectResult, BatchCommitEffectsOutput, } from "./effects";
+export type { EffectSummary, BatchCommitEffectEntry } from "./effectsTypes";
+export { apiListBreakpoints, apiShowBreakpoint, apiRespondToBreakpoint, apiListAutoApprovalRules, apiAddAutoApprovalRule, apiRemoveAutoApprovalRule, apiEvaluateAutoApproval, } from "./breakpoints";
+export type { ListBreakpointsOutput, BreakpointSummary, ShowBreakpointOutput, RespondToBreakpointInput, AddAutoApprovalRuleInput, EvaluateAutoApprovalInput, } from "./breakpoints";
+export { apiSubscribeRunEvents, apiUnsubscribeRunEvents, getActiveSubscriptions, closeAllSubscriptions, } from "./eventStream";
+export type { SubscribeRunEventsInput, SubscribeRunEventsOutput, UnsubscribeRunEventsOutput, } from "./eventStream";
+//# 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,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,eAAe,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closeAllSubscriptions = exports.getActiveSubscriptions = exports.apiUnsubscribeRunEvents = exports.apiSubscribeRunEvents = exports.apiEvaluateAutoApproval = exports.apiRemoveAutoApprovalRule = exports.apiAddAutoApprovalRule = exports.apiListAutoApprovalRules = exports.apiRespondToBreakpoint = exports.apiShowBreakpoint = exports.apiListBreakpoints = 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; } });
+var breakpoints_1 = require("./breakpoints");
+Object.defineProperty(exports, "apiListBreakpoints", { enumerable: true, get: function () { return breakpoints_1.apiListBreakpoints; } });
+Object.defineProperty(exports, "apiShowBreakpoint", { enumerable: true, get: function () { return breakpoints_1.apiShowBreakpoint; } });
+Object.defineProperty(exports, "apiRespondToBreakpoint", { enumerable: true, get: function () { return breakpoints_1.apiRespondToBreakpoint; } });
+Object.defineProperty(exports, "apiListAutoApprovalRules", { enumerable: true, get: function () { return breakpoints_1.apiListAutoApprovalRules; } });
+Object.defineProperty(exports, "apiAddAutoApprovalRule", { enumerable: true, get: function () { return breakpoints_1.apiAddAutoApprovalRule; } });
+Object.defineProperty(exports, "apiRemoveAutoApprovalRule", { enumerable: true, get: function () { return breakpoints_1.apiRemoveAutoApprovalRule; } });
+Object.defineProperty(exports, "apiEvaluateAutoApproval", { enumerable: true, get: function () { return breakpoints_1.apiEvaluateAutoApproval; } });
+var eventStream_1 = require("./eventStream");
+Object.defineProperty(exports, "apiSubscribeRunEvents", { enumerable: true, get: function () { return eventStream_1.apiSubscribeRunEvents; } });
+Object.defineProperty(exports, "apiUnsubscribeRunEvents", { enumerable: true, get: function () { return eventStream_1.apiUnsubscribeRunEvents; } });
+Object.defineProperty(exports, "getActiveSubscriptions", { enumerable: true, get: function () { return eventStream_1.getActiveSubscriptions; } });
+Object.defineProperty(exports, "closeAllSubscriptions", { enumerable: true, get: function () { return eventStream_1.closeAllSubscriptions; } });

package/dist/api/runs.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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, JsonRecord } from "../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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"}

package/dist/api/runs.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiCreateRun = apiCreateRun;
+exports.apiIterate = apiIterate;
+exports.apiCommitEffect = apiCommitEffect;
+exports.apiRunStatus = apiRunStatus;
+exports.apiRunEvents = apiRunEvents;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+// SDK-owned: orchestration iteration loop is the core SDK runtime engine
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+const global_1 = require("../orchestration/global");
+const runFiles_1 = require("../storage/runFiles");
+function ok(data) {
+    return { ok: true, data };
+}
+function fail(code, message) {
+    return { ok: false, error: { code, message } };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function parseEntrypoint(entrypoint) {
+    const hashIndex = entrypoint.lastIndexOf("#");
+    if (hashIndex <= 0) {
+        return { importPath: entrypoint, exportName: undefined };
+    }
+    return {
+        importPath: entrypoint.slice(0, hashIndex),
+        exportName: entrypoint.slice(hashIndex + 1) || undefined,
+    };
+}
+async function pathExists(p) {
+    try {
+        await fs_1.promises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function classifyError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.startsWith("Unknown effectId")) {
+        return { code: "UNKNOWN_EFFECT", message: msg };
+    }
+    return { code: "INTERNAL_ERROR", message: msg };
+}
+// ── API functions ───────────────────────────────────────────────────────────
+async function apiCreateRun(input) {
+    try {
+        // Validate inputs
+        if (!input.processId || typeof input.processId !== "string") {
+            return fail("INVALID_INPUT", "processId must be a non-empty string");
+        }
+        if (!input.entrypoint || typeof input.entrypoint !== "string") {
+            return fail("INVALID_INPUT", "entrypoint must be a non-empty string");
+        }
+        const { importPath, exportName } = parseEntrypoint(input.entrypoint);
+        const orch = (0, global_1.getGlobalRegistry)().getOrchestration();
+        const result = await orch.createRun({
+            processId: input.processId,
+            entrypoint: input.entrypoint,
+            prompt: input.prompt ?? "",
+            harness: input.harness,
+            inputs: input.inputs,
+            runsDir: input.runsDir ?? orch.resolveRunsDir(),
+        });
+        return ok({ runId: result.runId, runDir: result.runDir });
+    }
+    catch (error) {
+        const classified = classifyError(error);
+        return fail(classified.code, classified.message);
+    }
+}
+async function apiIterate(input) {
+    try {
+        if (!(await pathExists(input.runDir))) {
+            return fail("RUN_NOT_FOUND", `Run directory not found: ${input.runDir}`);
+        }
+        const result = await (0, babysitter_sdk_1.orchestrateIteration)({
+            runDir: input.runDir,
+            subprocessSupport: "agent-platform",
+        });
+        const output = { status: result.status };
+        if (result.metadata !== undefined) {
+            output.metadata = result.metadata;
+        }
+        if (result.status === "completed") {
+            output.output = result.output;
+        }
+        else if (result.status === "waiting") {
+            output.nextActions = result.nextActions;
+        }
+        else if (result.status === "failed" || result.status === "process-error") {
+            output.error = result.error;
+        }
+        return ok(output);
+    }
+    catch (error) {
+        const classified = classifyError(error);
+        return fail(classified.code, classified.message);
+    }
+}
+async function apiCommitEffect(input) {
+    try {
+        if (input.result.status === "ok" && input.result.value === undefined) {
+            return fail("INVALID_INPUT", "value is required when status is 'ok'");
+        }
+        if (input.result.status === "error" && !input.result.error) {
+            return fail("INVALID_INPUT", "error is required when status is 'error'");
+        }
+        const handle = {
+            runId: input.runDir.split(/[\\/]/).pop() ?? "",
+            runDir: input.runDir,
+            processId: "",
+            status: "running",
+        };
+        await (0, global_1.getGlobalRegistry)().getOrchestration().postEffectResult(handle, input.effectId, {
+            status: input.result.status,
+            value: input.result.status === "ok" ? input.result.value : undefined,
+            error: input.result.status === "error" ? input.result.error : undefined,
+            startedAt: input.result.startedAt,
+            finishedAt: input.result.finishedAt,
+        });
+        return ok({ resultRef: `tasks/${input.effectId}/result.json` });
+    }
+    catch (error) {
+        const classified = classifyError(error);
+        return fail(classified.code, classified.message);
+    }
+}
+async function apiRunStatus(input) {
+    try {
+        const runDir = path.join(input.runsDir ?? (0, global_1.getGlobalRegistry)().getOrchestration().resolveRunsDir(), input.runId);
+        if (!(await pathExists(runDir))) {
+            return fail("RUN_NOT_FOUND", `Run not found: ${input.runId}`);
+        }
+        const metadata = await (0, runFiles_1.readRunMetadata)(runDir);
+        const events = await (0, global_1.loadJournalEvents)(runDir);
+        const state = deriveRunState(events);
+        const pendingEffects = derivePendingEffects(events);
+        return ok({
+            state,
+            processId: metadata.processId,
+            runId: metadata.runId,
+            pendingEffects,
+        });
+    }
+    catch (error) {
+        const classified = classifyError(error);
+        return fail(classified.code, classified.message);
+    }
+}
+async function apiRunEvents(input) {
+    try {
+        if (input.limit !== undefined && input.limit < 0) {
+            return fail("INVALID_INPUT", "limit must be a non-negative number");
+        }
+        const runDir = path.join(input.runsDir ?? (0, global_1.getGlobalRegistry)().getOrchestration().resolveRunsDir(), input.runId);
+        if (!(await pathExists(runDir))) {
+            return fail("RUN_NOT_FOUND", `Run not found: ${input.runId}`);
+        }
+        let events = await (0, global_1.loadJournalEvents)(runDir);
+        if (input.filterType) {
+            events = events.filter((e) => e.type === input.filterType);
+        }
+        if (input.limit !== undefined) {
+            events = events.slice(0, input.limit);
+        }
+        return ok({
+            events: events.map((e) => ({
+                seq: e.seq,
+                type: e.type,
+                recordedAt: e.recordedAt,
+                data: e.data,
+            })),
+        });
+    }
+    catch (error) {
+        const classified = classifyError(error);
+        return fail(classified.code, classified.message);
+    }
+}
+// ── State derivation helpers ────────────────────────────────────────────────
+function deriveRunState(events) {
+    // Walk events in reverse to find the latest terminal or pending state.
+    for (let i = events.length - 1; i >= 0; i--) {
+        const type = events[i].type;
+        if (type === "RUN_COMPLETED")
+            return "completed";
+        if (type === "RUN_FAILED")
+            return "failed";
+    }
+    // Check if there are any unresolved EFFECT_REQUESTED events.
+    const requested = new Set();
+    const resolved = new Set();
+    for (const event of events) {
+        if (event.type === "EFFECT_REQUESTED") {
+            const effectId = event.data.effectId;
+            if (effectId)
+                requested.add(effectId);
+        }
+        else if (event.type === "EFFECT_RESOLVED" || event.type === "EFFECT_CANCELLED") {
+            const effectId = event.data.effectId;
+            if (effectId)
+                resolved.add(effectId);
+        }
+    }
+    const pending = [...requested].filter((id) => !resolved.has(id));
+    if (pending.length > 0)
+        return "waiting";
+    // Has any iteration happened?
+    const hasCreated = events.some((e) => e.type === "RUN_CREATED");
+    if (hasCreated && resolved.size > 0)
+        return "running";
+    return "created";
+}
+function derivePendingEffects(events) {
+    const requested = new Map();
+    const resolved = new Set();
+    for (const event of events) {
+        if (event.type === "EFFECT_REQUESTED") {
+            const data = event.data;
+            const effectId = data.effectId;
+            if (effectId) {
+                requested.set(effectId, {
+                    effectId,
+                    kind: typeof data.kind === "string" ? data.kind : undefined,
+                });
+            }
+        }
+        else if (event.type === "EFFECT_RESOLVED" || event.type === "EFFECT_CANCELLED") {
+            const effectId = event.data.effectId;
+            if (effectId)
+                resolved.add(effectId);
+        }
+    }
+    return [...requested.entries()]
+        .filter(([id]) => !resolved.has(id))
+        .map(([, info]) => info);
+}