@sentropic/h2a-runtime 0.81.0

package/dist/h2a-jobs.js

@@ -0,0 +1,388 @@
+/**
+ * h2a job callback + decision channel — P3 of cross-type agent delegation.
+ *
+ * Pure helpers (builders + parsing + instance derivation) plus a thin fs layer
+ * to DROP an envelope into a local h2a inbox. The bridge (`remote h2a bridge`)
+ * already transports envelopes pod↔local and is idempotent by file name, so
+ * everything here is best-effort: an undelivered envelope never blocks a job.
+ *
+ *  - `job.done`        agent → PARENT, when a delegated job terminates (body:
+ *                      {jobId, type, state, exitCode?, summary?, resultRef?}).
+ *  - `decision.requested`  agent → PARENT, when the job needs a human/parent
+ *                      decision (body: {jobId, question, options?}).
+ *  - `decision.reply`  PARENT → agent, the answer (body: {jobId, answer}).
+ *
+ * Envelopes mirror the on-disk h2a shape exactly (the format `h2a-bridge.ts`
+ * documents in the Pod README): {protocol, version, id, type, actor:{instance,
+ * role, scope}, to, body, createdAt}. They drop into
+ * `<localRoot>/inbox/<recipient-dir>/env__<ts>__<slug>.json`, where the dir is
+ * the recipient instance id with ":" → "__" — the bridge's SAFE_ENTRY shape.
+ *
+ * SECURITY: jobId / answer / question ride structured argv → the envelope body,
+ * NEVER a shell string. jobId is `assertSafeName`-checked before it becomes a
+ * file slug. The bridge itself re-validates every entry name (SAFE_ENTRY).
+ *
+ * KNOWN LIMIT — depends on agent behavior: a delegated interactive agent must
+ * CHOOSE to call its h2a MCP tool (h2a_inbox / write an envelope) to read a
+ * `decision.reply` or to emit a `decision.requested`. We build the channel and
+ * the transport; we cannot force the agent to use it. `job.done` for an
+ * interactive job is independent of that (it rides the SessionEnd hook), and
+ * for headless rides reconciliation — neither needs the agent to cooperate.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { assertSafeName } from "./delegate.js";
+import { defaultLocalH2aRoot, instanceInboxDir } from "./h2a-bridge.js";
+export const H2A_PROTOCOL = "sentropic.h2a";
+export const H2A_VERSION = "0.1";
+const DEFAULT_ROLE = "AGENTS";
+const DEFAULT_SCOPE = "scope:default";
+/**
+ * The h2a INSTANCE id of a delegated job's agent — the inbox a `decision.reply`
+ * must reach, and the `actor.instance` on envelopes the job emits.
+ *  - remote (kind:"remote"): the Pod default mapping `<tool>:remote:<sessionId>`
+ *    (same as `h2a-bridge.ts` defaultPodInstance), so the bridge already routes
+ *    to/from it.
+ *  - local: `<tool>:job:<jobId>` — a stable, predictable instance for the local
+ *    job's h2a side-window. jobId already passed assertSafeName at delegate time.
+ * Pure, exported for tests.
+ */
+export function jobInstance(entry) {
+    if (entry.kind === "remote") {
+        return `${entry.tool}:remote:${entry.remoteId ?? entry.id}`;
+    }
+    return `${entry.tool}:job:${entry.id}`;
+}
+/**
+ * The PARENT instance to address a callback to: the explicit `callbackTo`
+ * recorded on the job at delegate time (`--parent`/`--on-done`), else undefined
+ * (no parent → no callback is emitted; best-effort). Pure, exported for tests.
+ */
+export function parentInstance(entry) {
+    const to = entry.callbackTo;
+    return to && to.length > 0 ? to : undefined;
+}
+/** A monotonic-ish envelope id slug. Pure given (jobId, kind, ts). */
+function envelopeId(kind, jobId, ts) {
+    return `env:${ts}:${kind}-${jobId}`;
+}
+// ---------------------------------------------------------------------------
+// S1 — envelope AUTHENTICATION (shared RWX is multi-tenant).
+//
+// The h2a inbox lives on the shared RWX volume, writable by EVERY pod. Nothing
+// signs an envelope, so any pod can DROP a file claiming to be a `job.done` for
+// another job, or a `decision.requested`/`decision.reply` piloting a neighbour's
+// agent. We can't make the file bus cryptographically trustworthy here, but we
+// CAN reject envelopes whose claimed `actor.instance` doesn't match the instance
+// the addressed job is KNOWN to use:
+//   - a `job.done`/`decision.requested` ABOUT job X must come FROM job X's own
+//     agent → actor.instance === jobInstance(X). A different sender is forged.
+//   - a `decision.reply` is PARENT→agent and is treated as ADVISORY: it is never
+//     used to gate a privileged action (the agent chooses to act on it), and a
+//     reply whose actor isn't the job's recorded parent is dropped from the
+//     "answered" set so it can't silently suppress a real pending decision.
+//
+// LIMIT: this is integrity-by-convention, not authentication — a pod that knows
+// the victim's jobId AND can compute jobInstance() (a deterministic
+// `<tool>:job:<id>` / `<tool>:remote:<id>`) could still forge a matching actor.
+// Real trust needs signed envelopes (h2a_sign), tracked separately. This check
+// stops the trivial cross-job spoof, which is the immediate exposure.
+// ---------------------------------------------------------------------------
+/** The `actor.instance` an envelope carries, or undefined when malformed. Pure. */
+export function envelopeActorInstance(envelope) {
+    const inst = envelope.actor?.instance;
+    return typeof inst === "string" && inst.length > 0 ? inst : undefined;
+}
+/**
+ * Is `envelope`'s sender the instance we EXPECT for this job? `expectedInstance`
+ * is the job's `jobInstance(...)` (for job.done / decision.requested ABOUT the
+ * job) or the job's recorded parent (for decision.reply). An undefined expected
+ * instance means we can't verify (no job/parent on record) → reject (fail
+ * closed). Pure, exported for tests.
+ */
+export function isEnvelopeFromExpected(envelope, expectedInstance) {
+    if (!expectedInstance)
+        return false;
+    return envelopeActorInstance(envelope) === expectedInstance;
+}
+/** On-disk file name for an envelope — matches the bridge's SAFE_ENTRY shape. */
+export function envelopeFileName(kind, jobId, ts) {
+    // "." in the type is not allowed in a SAFE_ENTRY dir/file segment lead, but
+    // is fine mid-name; we slugify it to "_" to stay maximally safe.
+    const slug = kind.replace(/\./g, "_");
+    return `env__${ts}__${slug}-${jobId}.json`;
+}
+/**
+ * STABLE (timestamp-free) file name for a `job.done` callback: ONE per job, so
+ * the SessionEnd hook and the reconcile loop can BOTH attempt the emit and the
+ * second one is a no-op (dropEnvelope skips an existing file; the bridge skips
+ * by file name too). Idempotency by name, exactly the bridge's contract.
+ */
+export function jobDoneFileName(jobId) {
+    return `env__job_done-${jobId}.json`;
+}
+function nowIso(ms) {
+    return new Date(ms).toISOString();
+}
+/**
+ * Build a `job.done` envelope: emitted BY the job's agent, addressed TO the
+ * parent. The body carries jobId/type/state and optional exitCode/summary/
+ * resultRef. Pure, exported for tests (ts/id are injected for determinism).
+ */
+export function buildJobDoneEnvelope(args) {
+    const ts = args.nowMs ?? Date.now();
+    const body = {
+        jobId: args.job.id,
+        type: args.job.tool,
+        state: args.state,
+    };
+    if (args.exitCode !== undefined)
+        body.exitCode = args.exitCode;
+    if (args.summary !== undefined)
+        body.summary = args.summary;
+    if (args.resultRef !== undefined)
+        body.resultRef = args.resultRef;
+    return {
+        protocol: H2A_PROTOCOL,
+        version: H2A_VERSION,
+        id: envelopeId("job-done", args.job.id, ts),
+        type: "job.done",
+        actor: { instance: jobInstance(args.job), role: DEFAULT_ROLE, scope: DEFAULT_SCOPE },
+        to: args.to,
+        body,
+        createdAt: nowIso(ts),
+    };
+}
+/**
+ * Build a `decision.requested` envelope: emitted BY the job's agent, addressed
+ * TO the parent. Pure, exported for tests.
+ */
+export function buildDecisionRequested(args) {
+    const ts = args.nowMs ?? Date.now();
+    const body = {
+        jobId: args.job.id,
+        question: args.question,
+    };
+    if (args.options !== undefined)
+        body.options = args.options;
+    return {
+        protocol: H2A_PROTOCOL,
+        version: H2A_VERSION,
+        id: envelopeId("decision-req", args.job.id, ts),
+        type: "decision.requested",
+        actor: { instance: jobInstance(args.job), role: DEFAULT_ROLE, scope: DEFAULT_SCOPE },
+        to: args.to,
+        body,
+        createdAt: nowIso(ts),
+    };
+}
+/**
+ * Build a `decision.reply` envelope: emitted BY the parent, addressed TO the
+ * job's agent inbox. The `answer` is opaque text — passed straight through, no
+ * shell concat. Pure, exported for tests.
+ */
+export function buildDecisionReply(args) {
+    const ts = args.nowMs ?? Date.now();
+    return {
+        protocol: H2A_PROTOCOL,
+        version: H2A_VERSION,
+        id: envelopeId("decision-reply", args.job.id, ts),
+        type: "decision.reply",
+        actor: {
+            instance: args.parentInstance,
+            role: DEFAULT_ROLE,
+            scope: DEFAULT_SCOPE,
+        },
+        to: jobInstance(args.job),
+        body: { jobId: args.job.id, answer: args.answer },
+        createdAt: nowIso(ts),
+    };
+}
+/**
+ * Drop an envelope into `<localRoot>/inbox/<to-dir>/<fileName>`, where <to-dir>
+ * is `envelope.to` with ":" → "__". Idempotent by FILE NAME (an existing file is
+ * left untouched — same contract as the bridge). The jobId in the file name is
+ * already assertSafeName-checked by the caller. Returns where it landed.
+ */
+export function dropEnvelope(envelope, fileName, localRoot = defaultLocalH2aRoot()) {
+    const dir = join(localRoot, "inbox", instanceInboxDir(envelope.to));
+    const path = join(dir, fileName);
+    if (existsSync(path))
+        return { path, written: false };
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+    return { path, written: true };
+}
+/** Minimal parse of an on-disk envelope; tolerant of unrelated files. */
+function parseEnvelope(raw) {
+    try {
+        const e = JSON.parse(raw);
+        if (e.protocol === H2A_PROTOCOL &&
+            typeof e.type === "string" &&
+            typeof e.id === "string" &&
+            e.body !== undefined) {
+            return e;
+        }
+    }
+    catch {
+        // not an envelope / malformed → skip
+    }
+    return undefined;
+}
+/**
+ * AUTHENTICATE a flat list of job envelopes (S1): keep only those whose claimed
+ * `actor.instance` matches the instance the addressed job is known to use (per
+ * the resolver). A forged cross-job envelope (wrong actor) is DROPPED. Envelopes
+ * that aren't one of our job types pass through untouched (they're not our
+ * concern here). Pure over (envelopes, resolver), exported for tests.
+ */
+export function authenticateJobEnvelopes(envelopes, expectedInstanceOf) {
+    const out = [];
+    for (const e of envelopes) {
+        if (e.type !== "job.done" &&
+            e.type !== "decision.requested" &&
+            e.type !== "decision.reply") {
+            out.push(e);
+            continue;
+        }
+        const body = e.body;
+        const jobId = typeof body?.jobId === "string" ? body.jobId : undefined;
+        if (!jobId)
+            continue; // a job envelope without a jobId is unusable → drop
+        if (isEnvelopeFromExpected(e, expectedInstanceOf(jobId, e.type))) {
+            out.push(e);
+        }
+        // else: forged / unverifiable actor → dropped
+    }
+    return out;
+}
+/**
+ * From a flat list of (fileName, rawJson) envelopes found in the PARENT's inbox
+ * and the JOB inboxes, return the `decision.requested` that have NO matching
+ * `decision.reply` yet (same jobId). Pure, exported for tests — the fs read is
+ * done by the caller so this stays deterministic.
+ *
+ * A reply is matched to a request by jobId (the channel is one open decision per
+ * job at a time; P4 may add a per-request id). `repliedJobIds` is the set of
+ * jobIds for which a `decision.reply` exists anywhere we can see.
+ */
+export function pendingDecisions(envelopes, repliedJobIds) {
+    const out = [];
+    for (const e of envelopes) {
+        if (e.type !== "decision.requested")
+            continue;
+        const body = e.body;
+        if (typeof body.jobId !== "string" || typeof body.question !== "string") {
+            continue;
+        }
+        if (repliedJobIds.has(body.jobId))
+            continue;
+        const d = {
+            jobId: body.jobId,
+            question: body.question,
+            envelopeId: e.id,
+        };
+        if (Array.isArray(body.options))
+            d.options = body.options.map(String);
+        out.push(d);
+    }
+    return out;
+}
+/** The set of jobIds that already have a `decision.reply` in `envelopes`. Pure. */
+export function repliedDecisionJobIds(envelopes) {
+    const set = new Set();
+    for (const e of envelopes) {
+        if (e.type !== "decision.reply")
+            continue;
+        const body = e.body;
+        if (typeof body.jobId === "string")
+            set.add(body.jobId);
+    }
+    return set;
+}
+/**
+ * Read every envelope under `<localRoot>/inbox/**` (one dir level deep, the h2a
+ * layout). The fs read is isolated HERE so the listing/matching above stays
+ * pure. Missing store → empty. Never throws on a bad file (skips it).
+ */
+export function readInboxEnvelopes(localRoot = defaultLocalH2aRoot()) {
+    const inbox = join(localRoot, "inbox");
+    if (!existsSync(inbox))
+        return [];
+    const out = [];
+    for (const dir of readdirSync(inbox, { withFileTypes: true })) {
+        if (!dir.isDirectory())
+            continue;
+        const dirPath = join(inbox, dir.name);
+        for (const f of readdirSync(dirPath, { withFileTypes: true })) {
+            if (!f.isFile() || !f.name.endsWith(".json"))
+                continue;
+            let raw;
+            try {
+                raw = readFileSync(join(dirPath, f.name), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const env = parseEnvelope(raw);
+            if (env)
+                out.push(env);
+        }
+    }
+    return out;
+}
+/**
+ * Does the job have an UNANSWERED `decision.requested`? Used by `jobs status` to
+ * show `awaiting-decision`. Pure over the envelope list, exported for tests.
+ */
+export function isAwaitingDecision(jobId, envelopes) {
+    const replied = repliedDecisionJobIds(envelopes);
+    return pendingDecisions(envelopes, replied).some((d) => d.jobId === jobId);
+}
+/**
+ * One-line render of a pending decision for `jobs decisions` — jobId + question
+ * only (no raw envelope body beyond the essentials, per the security note).
+ * Pure, exported for tests.
+ */
+export function renderPendingDecisions(decisions) {
+    if (decisions.length === 0)
+        return "(no pending decisions)";
+    const lines = decisions.map((d) => {
+        const opts = d.options && d.options.length > 0 ? `  [${d.options.join(" | ")}]` : "";
+        return `${d.jobId}\t${d.question}${opts}`;
+    });
+    return ["JOB\tQUESTION", ...lines].join("\n");
+}
+/**
+ * Best-effort: emit a `job.done` envelope for a finished job into the parent's
+ * local inbox. No-op (emitted:false, "no-parent") when the job has no recorded
+ * `callbackTo` — a job delegated without a parent simply has nobody to notify.
+ * NEVER throws: any fs/build error is swallowed into emitted:false so a callback
+ * failure can't take down the SessionEnd hook or the reconcile loop.
+ */
+export function emitJobDone(job, args = { state: job.jobState ?? "done" }) {
+    try {
+        const to = parentInstance(job);
+        if (!to)
+            return { emitted: false, reason: "no-parent" };
+        assertSafeName(job.id);
+        // Prefer the job's terminal time so the envelope id is stable across the
+        // hook + reconcile paths; the FILE name is timestamp-free (one per job).
+        const ts = args.nowMs ?? (job.endedAt ? Date.parse(job.endedAt) : Date.now());
+        const envelope = buildJobDoneEnvelope({
+            job,
+            to,
+            state: args.state,
+            ...(args.exitCode !== undefined ? { exitCode: args.exitCode } : {}),
+            ...(args.summary !== undefined ? { summary: args.summary } : {}),
+            ...(args.resultRef !== undefined ? { resultRef: args.resultRef } : {}),
+            nowMs: ts,
+        });
+        const { path, written } = dropEnvelope(envelope, jobDoneFileName(job.id), args.localRoot);
+        return { emitted: true, path, written, to };
+    }
+    catch (error) {
+        return { emitted: false, reason: "error", error: String(error) };
+    }
+}
+//# sourceMappingURL=h2a-jobs.js.map

package/dist/h2a-jobs.js.map

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

package/dist/h2a-ping.d.ts

@@ -0,0 +1,38 @@
+import { H2A_PROTOCOL, H2A_VERSION, type EnvelopeActor } from "./h2a-jobs.js";
+export type H2aPingEnvelope = {
+    protocol: typeof H2A_PROTOCOL;
+    version: typeof H2A_VERSION;
+    id: string;
+    type: "h2a.ping";
+    actor: EnvelopeActor;
+    to: string;
+    body: {
+        message: string;
+        cwd?: string;
+    };
+    createdAt: string;
+};
+export type H2aPingResult = {
+    path: string;
+    written: boolean;
+    envelope: H2aPingEnvelope;
+};
+export declare function h2aPingFileName(ts: number): string;
+export declare function remoteSessionIdFromInstance(instance: string): string | undefined;
+export declare function buildH2aPingEnvelope(args: {
+    to: string;
+    from?: string;
+    message?: string;
+    cwd?: string;
+    nowMs?: number;
+}): H2aPingEnvelope;
+export declare function dropH2aPing(envelope: H2aPingEnvelope, localRoot?: string): H2aPingResult;
+export declare function sendH2aPing(args: {
+    to: string;
+    from?: string;
+    message?: string;
+    cwd?: string;
+    localRoot?: string;
+    nowMs?: number;
+}): H2aPingResult;
+//# sourceMappingURL=h2a-ping.d.ts.map

package/dist/h2a-ping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"h2a-ping.d.ts","sourceRoot":"","sources":["../src/h2a-ping.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAI9E,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,OAAO,YAAY,CAAC;IAC9B,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAAC;AAcF,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,eAAe,CAmBlB;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,eAAe,EACzB,SAAS,GAAE,MAA8B,GACxC,aAAa,CAUf;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,aAAa,CAGhB"}

package/dist/h2a-ping.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { defaultLocalH2aRoot, instanceInboxDir } from "./h2a-bridge.js";
+import { H2A_PROTOCOL, H2A_VERSION } from "./h2a-jobs.js";
+const SAFE_INSTANCE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+function assertSafeInstance(instance) {
+    if (!SAFE_INSTANCE.test(instance)) {
+        throw new Error(`unsafe h2a instance "${instance}" (allowed: letters, digits, ".", "_", "-", ":")`);
+    }
+}
+function nowIso(ms) {
+    return new Date(ms).toISOString();
+}
+export function h2aPingFileName(ts) {
+    return `env__${ts}__h2a_ping.json`;
+}
+export function remoteSessionIdFromInstance(instance) {
+    const match = /^[A-Za-z0-9._-]+:remote:([A-Za-z0-9._-]+)$/.exec(instance);
+    return match?.[1];
+}
+export function buildH2aPingEnvelope(args) {
+    const ts = args.nowMs ?? Date.now();
+    const from = args.from ?? "remote:cli";
+    assertSafeInstance(args.to);
+    assertSafeInstance(from);
+    const body = {
+        message: args.message ?? "ping",
+    };
+    if (args.cwd !== undefined)
+        body.cwd = args.cwd;
+    return {
+        protocol: H2A_PROTOCOL,
+        version: H2A_VERSION,
+        id: `env:${ts}:h2a-ping`,
+        type: "h2a.ping",
+        actor: { instance: from, role: "AGENTS", scope: "scope:default" },
+        to: args.to,
+        body,
+        createdAt: nowIso(ts),
+    };
+}
+export function dropH2aPing(envelope, localRoot = defaultLocalH2aRoot()) {
+    assertSafeInstance(envelope.to);
+    const ts = Date.parse(envelope.createdAt);
+    const file = h2aPingFileName(Number.isFinite(ts) ? ts : Date.now());
+    const dir = join(localRoot, "inbox", instanceInboxDir(envelope.to));
+    const path = join(dir, file);
+    if (existsSync(path))
+        return { path, written: false, envelope };
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+    return { path, written: true, envelope };
+}
+export function sendH2aPing(args) {
+    const envelope = buildH2aPingEnvelope(args);
+    return dropH2aPing(envelope, args.localRoot);
+}
+//# sourceMappingURL=h2a-ping.js.map

package/dist/h2a-ping.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { type RegistryEntry } from "./registry.js";
+export declare const packageName = "@sentropic/remote-cli";
+export { run } from "./run.js";
+export type { RunOptions, RunResult } from "./run.js";
+export { attach, createRemoteSession, getRemoteSession, listRemoteSessions, refreshRemoteSession, renameRemoteSession, stopRemoteSession, } from "./attach.js";
+export type { AttachOptions, AttachResult } from "./attach.js";
+export { inspectProfileAuth } from "./auth-diagnostics.js";
+export type { AuthDiagnosticsResult, AuthDiagnosticsStatus, } from "./auth-diagnostics.js";
+export { AuthRefreshError, ensureProfileAuthFresh } from "./auth-refresh.js";
+export { AuthBundleMissingError, assertRequiredAuthBundle, collectProfileAuth, } from "./auth-bundle.js";
+export type { AuthBundle } from "./auth-bundle.js";
+export { resolveProfile, coerceCliProfileName, isCliProfile, withResume, type ProfileConfig, } from "./profiles.js";
+export { smokeRemoteProfile } from "./smoke.js";
+export type { SmokeRemoteProfileOptions, SmokeRemoteProfileResult, } from "./smoke.js";
+export { migrateForward, migrateBack } from "./migrate.js";
+export type { MigrateForwardOptions, MigrateForwardResult, MigrateBackOptions, MigrateBackResult, } from "./migrate.js";
+export { pluginAdd, pluginAddInstaller, pluginLs, pluginSync, pluginSyncCheck, reconcileSessionPlugins, parseMcpSpec, parseMcpSpecs, detectMcpBins, upsertCodexMcpServer, mergeClaudeMcpServers, buildPodSyncScript, } from "./plugin.js";
+/** Validate `--watch <minutes>`: a whole number of minutes >= 1. */
+export declare function parseWatchMinutes(raw: string): number;
+/**
+ * Soft-refresh EVERY live remote session (profile carried by each session).
+ * Per-session errors don't stop the pass; ends with a recap (ok / unchanged /
+ * failed) and returns the failure count. `hashes` carries the previous pass's
+ * bundle hashes (sessionId -> sha256) so unchanged creds are a no-op WITHOUT
+ * respawning the Pod CLI.
+ */
+export declare function softRefreshAllSessions(url: string, opts: {
+    authRefresh?: boolean;
+}, hashes: Map<string, string>): Promise<{
+    failed: number;
+}>;
+/**
+ * Foreground refresh loop for `--watch <minutes>`: pass, sleep, repeat. NO
+ * daemonization, no pid file — the user runs it in a dedicated tmux window.
+ * Each pass is timestamped on stderr; SIGINT (Ctrl-C) stops it cleanly with a
+ * message and exit 0. Pass failures are logged and the loop keeps going.
+ */
+export declare function watchRefreshLoop(minutes: number, pass: () => Promise<{
+    failed: number;
+}>, signals?: {
+    on(event: "SIGINT", listener: () => void): unknown;
+    removeListener(event: "SIGINT", listener: () => void): unknown;
+}): Promise<number>;
+/**
+ * P4 — the conductor's FOREGROUND watch loop (NO daemon, NO pid file — run it in
+ * a dedicated tmux window, exactly like `watchRefreshLoop` / `h2a bridge
+ * --watch`). Each pass is timestamped; SIGINT (Ctrl-C) stops it cleanly with a
+ * message and exit 0. A pass failure is logged and the loop keeps going. The
+ * `pass` is the conductor pass (reconcile + start `pending` jobs under the cap);
+ * `signals` is injectable so tests never emit a real SIGINT.
+ */
+export declare function conductLoop(minutes: number, pass: () => Promise<{
+    started: number;
+    finished: number;
+}>, signals?: {
+    on(event: "SIGINT", listener: () => void): unknown;
+    removeListener(event: "SIGINT", listener: () => void): unknown;
+}): Promise<number>;
+export type StartJobResult = {
+    started: true;
+    target: "local" | "remote";
+    detail: string;
+} | {
+    started: false;
+    error: string;
+};
+/**
+ * Launch a job that is enrolled in the registry (typically `pending`): spawn the
+ * agent (local detached tmux, or a Pod), advance the registry entry to
+ * `running`, mirror it under track (best-effort), and propagate the spawn-depth
+ * budget to the child via `REMOTE_DELEGATE_DEPTH`. The launch params are read
+ * from the entry's queued-launch fields (tool/task/headless/remoteTarget/
+ * originCwd/explicitCwd/depthBudget/trackWp), set at `delegate` time.
+ *
+ * Never throws: any spawn/registry error is returned as `{started:false}` so the
+ * conductor loop keeps going. For remote, the per-job workspace is created here
+ * (so a queued remote job doesn't hold a workspace while waiting).
+ */
+export declare function startJob(job: RegistryEntry): Promise<StartJobResult>;
+/**
+ * Reliability slice 1 — RESUME a throttled HEADLESS LOCAL job. Relaunch the SAME
+ * job in the SAME `runCwd` it already ran in (its recorded `cwd` — NOT a fresh
+ * worktree, so it continues the prior conversation in place) with the tool's
+ * CONTINUE flag (`claude -p --continue` / `codex exec resume --last`, via the
+ * safe argv `buildThrottleResumeArgs` — never `bash -lc` concat), redirecting to
+ * the SAME result.json/output.log, then transition `throttled → running`. The
+ * throttle bookkeeping is PRESERVED so a re-throttle bumps `attempts` (the cap is
+ * enforced in reconcile). Never throws — a spawn error is returned as
+ * `{started:false}` so the conductor keeps going.
+ *
+ * SCOPE: headless local only. Interactive resume (send-keys) and remote resume
+ * (control-plane) are phase 2 — see the TODOs at the call site.
+ */
+export declare function resumeThrottledJob(job: RegistryEntry): StartJobResult;
+export declare function main(argv: ReadonlyArray<string>): Promise<number>;
+export { main as dispatch };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAgGA,OAAO,EAYL,KAAK,aAAa,EAGnB,MAAM,eAAe,CAAC;AAuNvB,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,UAAU,EACV,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EACV,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,uBAAuB,EACvB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AA0XrB,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQrD;AA4HD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,EAC/B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA6G7B;AAyED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAEvC,OAAO,GAAE;IACP,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CACtD,GACV,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,OAAO,GAAE;IACP,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CACtD,GACV,OAAO,CAAC,MAAM,CAAC,CAyCjB;AAQD,MAAM,MAAM,cAAc,GACtB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAwP1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CAqHrE;AA4SD,wBAAsB,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CA82MvE;AA0BD,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,CAAC"}