@mnemom/mnemom 0.17.32 → 0.17.34-next.1

package/dist/lib/runner/executor-client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The thin runner's executor client (ruling 34.12 (7)): S1's executor routes, the same protocol as
+ * C2's host client, plus the two post-claim reads outside S1 (the job, W-L15; the served bundle,
+ * W-L12) and the JWKS. Every executor route carries the executor key in X-Mnemom-Api-Key and
+ * never Authorization (ruling 33.28 (1)), and so does the job read (api#4165 authorizes the executor
+ * holding the lease); the bundle fetch carries the lease key the same way.
+ *
+ * Nothing here decides an outcome: each call returns its status, body and error code, and the job
+ * (job.ts) maps them to 34.12's reasons. Never throws: a network failure is status 0.
+ */
+export interface HttpResult {
+    readonly status: number;
+    readonly body: unknown;
+    /** The raw body text (the served bundle is verified against these exact bytes). */
+    readonly text: string;
+    /** The error code: `{error: {code}}`, `{error: "code"}` or `{code}`; null on success. */
+    readonly code: string | null;
+    readonly networkError?: string;
+}
+export type FetchFn = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+export declare function errorCode(body: unknown): string | null;
+export declare function errorDetails(body: unknown): Record<string, unknown>;
+/** The post-claim job read (W-L15), with the executor key. */
+export declare const JOB_READ_PATH: (sessionId: string) => string;
+/** The served bundle fetch, per claim (W-L12). */
+export declare const BUNDLE_FETCH_PATH: (sessionId: string) => string;
+export declare const JWKS_PATH = "/v1/.well-known/jwks.json";
+export interface RunnerApi {
+    readyList(limit: number): Promise<HttpResult>;
+    attest(sessionId: string, nonce: string): Promise<HttpResult>;
+    claim(sessionId: string, body: {
+        nonce: string;
+        new_key?: true;
+    }): Promise<HttpResult>;
+    append(sessionId: string, body: Record<string, unknown>): Promise<HttpResult>;
+    hello(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        spawn_id: string;
+    }): Promise<HttpResult>;
+    heartbeat(body: {
+        nonce: string;
+        entries: {
+            session_id: string;
+            epoch: number;
+            spawn_id: string;
+        }[];
+    }): Promise<HttpResult>;
+    release(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+    }): Promise<HttpResult>;
+    fail(sessionId: string, body: Record<string, unknown>): Promise<HttpResult>;
+    job(sessionId: string): Promise<HttpResult>;
+    bundle(sessionId: string, leaseKey: string): Promise<HttpResult>;
+    jwks(): Promise<HttpResult>;
+}
+export declare function runnerApi(opts: {
+    apiUrl: string;
+    executorKey: string;
+    fetch: FetchFn;
+    timeoutMs?: number;
+}): RunnerApi;

package/dist/lib/runner/executor-client.js

@@ -0,0 +1,97 @@
+/**
+ * The thin runner's executor client (ruling 34.12 (7)): S1's executor routes, the same protocol as
+ * C2's host client, plus the two post-claim reads outside S1 (the job, W-L15; the served bundle,
+ * W-L12) and the JWKS. Every executor route carries the executor key in X-Mnemom-Api-Key and
+ * never Authorization (ruling 33.28 (1)), and so does the job read (api#4165 authorizes the executor
+ * holding the lease); the bundle fetch carries the lease key the same way.
+ *
+ * Nothing here decides an outcome: each call returns its status, body and error code, and the job
+ * (job.ts) maps them to 34.12's reasons. Never throws: a network failure is status 0.
+ */
+import { EXECUTOR_KEY_HEADER, routePath } from "../../vendor/durable-contract/index.js";
+export function errorCode(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const b = body;
+    if (b.error && typeof b.error === "object") {
+        const c = b.error.code;
+        if (typeof c === "string")
+            return c;
+    }
+    if (typeof b.error === "string")
+        return b.error;
+    return typeof b.code === "string" ? b.code : null;
+}
+export function errorDetails(body) {
+    if (!body || typeof body !== "object")
+        return {};
+    const e = body.error;
+    const d = e && typeof e === "object" ? e.details : undefined;
+    return d && typeof d === "object" && !Array.isArray(d) ? d : {};
+}
+/** The post-claim job read (W-L15), with the executor key. */
+export const JOB_READ_PATH = (sessionId) => `/v1/executor/sessions/${sessionId}/job`;
+/** The served bundle fetch, per claim (W-L12). */
+export const BUNDLE_FETCH_PATH = (sessionId) => `/v1/executor/sessions/${sessionId}/bundle`;
+export const JWKS_PATH = "/v1/.well-known/jwks.json";
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function runnerApi(opts) {
+    const base = opts.apiUrl.replace(/\/+$/, "");
+    const call = async (path, method, key, body) => {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? 15_000);
+        const headers = { accept: "application/json" };
+        if (key !== null)
+            headers[EXECUTOR_KEY_HEADER] = key;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        try {
+            const res = await opts.fetch(`${base}${path}`, {
+                method,
+                headers,
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: ctl.signal,
+            });
+            const text = await res.text();
+            let parsed = null;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = text;
+            }
+            return {
+                status: res.status,
+                body: parsed,
+                text,
+                code: res.status >= 400 ? errorCode(parsed) : null,
+            };
+        }
+        catch (e) {
+            return { status: 0, body: null, text: "", code: null, networkError: e.message };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    // A session id from the api goes into a path; refuse anything but a lowercase uuid.
+    const scoped = (id) => {
+        if (!SESSION_ID_RE.test(id))
+            throw new RangeError("session id must be a lowercase uuid");
+        return id;
+    };
+    const ex = opts.executorKey;
+    return {
+        readyList: (limit) => call(`${routePath("exec_ready_list")}?limit=${limit}`, "GET", ex),
+        attest: (id, nonce) => call(routePath("exec_attest", scoped(id)), "POST", ex, { nonce }),
+        claim: (id, body) => call(routePath("exec_claim", scoped(id)), "POST", ex, body),
+        append: (id, body) => call(routePath("exec_append", scoped(id)), "POST", ex, body),
+        hello: (id, body) => call(routePath("exec_hello", scoped(id)), "POST", ex, body),
+        heartbeat: (body) => call(routePath("exec_heartbeat"), "POST", ex, body),
+        release: (id, body) => call(routePath("exec_release", scoped(id)), "POST", ex, body),
+        fail: (id, body) => call(routePath("exec_fail", scoped(id)), "POST", ex, body),
+        job: (id) => call(JOB_READ_PATH(scoped(id)), "GET", ex),
+        bundle: (id, leaseKey) => call(BUNDLE_FETCH_PATH(scoped(id)), "GET", leaseKey),
+        jwks: () => call(JWKS_PATH, "GET", null),
+    };
+}

package/dist/lib/runner/job.d.ts

@@ -0,0 +1,70 @@
+/**
+ * One served-phase job, claim to outcome (ruling 34.12; Doors W-L13, W3.11 and W4.4).
+ *
+ * attest → claim (needs_key retry) → register the spawn → hello → heartbeats → served bundle
+ * (verified, bound to this claim) → job read (contract bytes bound to the claim's seal) → repo →
+ * phases through the runner's own proxy → PR → release. Every Mnemom error maps to one of S1's
+ * refused reasons and fails closed; under --fail-mode open, only bundle_unavailable,
+ * job_unavailable and api_unavailable are ridden through, and only once a verified bundle is held
+ * (34.12 (2)). A bundle that fails verification stops the job in every mode.
+ *
+ * Every side effect is in `JobDeps`, so each arm is tested; `liveJobDeps` (commands/agent-run.ts)
+ * is the thin driver.
+ */
+import { type HttpResult, type RunnerApi } from "./executor-client.js";
+import { type OutcomeFields, type RefusedReason } from "./outcome.js";
+import { type PhaseInvocation } from "./phases.js";
+import type { ModelProxy, ProxyState } from "./proxy.js";
+import { type RunnerFailMode } from "./settings.js";
+/** A claimed job's working copy. */
+export interface Workspace {
+    dir: string;
+    /** A fresh, empty HOME for the phases. */
+    home: string;
+    branch: string;
+}
+export interface JobDeps {
+    api: RunnerApi;
+    /** One nonce per runner process, reused on every call (A3 fences on it). */
+    nonce: string;
+    newSpawnId(): string;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    log(line: string): void;
+    gatewayUrl: string;
+    startProxy(state: ProxyState): Promise<ModelProxy>;
+    prepareWorkspace(repo: string, sessionId: string): Promise<Workspace>;
+    /** Run one phase's process; resolves its exit code. Rejects only when it could not start. */
+    runPhase(inv: PhaseInvocation, ws: Workspace, modelUrl: string, signal: AbortSignal): Promise<number>;
+    /** Push the job branch and open its PR; resolves the PR URL. */
+    openPr(repo: string, ws: Workspace, title: string): Promise<string>;
+    enableAutoMerge(prUrl: string): Promise<void>;
+    cleanup(ws: Workspace): Promise<void>;
+}
+export interface JobOptions {
+    failMode: RunnerFailMode;
+    /** Aborted by SIGTERM or SIGINT: release the lease, print no outcome line. */
+    stop: AbortSignal;
+}
+/** What one claim attempt came to. */
+export type JobResult = {
+    kind: "next";
+} | {
+    kind: "outcome";
+    outcome: OutcomeFields;
+} | {
+    kind: "stopped";
+};
+/** A3's executor auth rejections, on whichever executor route comes first (34.12 (8), (10)). */
+export declare function authRefusal(r: HttpResult): RefusedReason | null;
+/**
+ * Run one candidate session to an outcome. Never throws for a Mnemom error: every one is an
+ * outcome. Throws only on a runner bug.
+ */
+export declare function runJob(sessionId: string, opts: JobOptions, deps: JobDeps): Promise<JobResult>;
+/**
+ * Report a failed or refused job after claim (34.12 (6), (10)). The fail reason vocabulary is the
+ * Durable lead's to rule (A3 accepts only transcript_lost today); a refused report is logged and
+ * never changes the outcome, because the lease lapses on its own.
+ */
+export declare function reportFail(deps: JobDeps, sessionId: string, epoch: number, kind: "runner_failed" | "runner_refused", reason: string): Promise<void>;