@aloud/runner 0.2.5 → 0.3.1

package/src/protocol/approval.ts

@@ -0,0 +1,99 @@
+/**
+ * Getting a credential onto this machine without anybody carrying one.
+ *
+ * The client asks the server to open an approval, prints a URL and a short code, and waits. A person
+ * opens that URL in a browser they are already signed in to, types the code this printed, and
+ * approves. The next poll returns the credential and writes it to disk.
+ *
+ * The reason this exists rather than a prompt: a prompt needs a terminal, and the thing driving
+ * setup is increasingly an agent that does not have one. Waiting on a click needs nothing but time,
+ * so the same command works for a person and for an agent, and neither of them ever sees a token.
+ */
+export interface ApprovalStart {
+  id: string;
+  userCode: string;
+  deviceCode: string;
+  approveUrl: string;
+  expiresAt: string;
+  pollMs: number;
+}
+
+export type ApprovalOutcome =
+  | { status: "approved"; secret: string; kind: "runner" | "mcp" }
+  | { status: "denied" }
+  | { status: "expired" };
+
+export class ApprovalFailed extends Error {}
+
+export async function startApproval(input: {
+  server: string;
+  kind: "runner" | "mcp";
+  name?: string | null;
+  fetchImpl?: typeof fetch;
+}): Promise<ApprovalStart> {
+  const response = await (input.fetchImpl ?? fetch)(new URL("api/approvals", input.server + "/"), {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    redirect: "error",
+    body: JSON.stringify({ kind: input.kind, name: input.name ?? null }),
+  });
+  if (!response.ok) {
+    throw new ApprovalFailed(`${input.server} would not start an approval (${response.status}).`);
+  }
+  return (await response.json()) as ApprovalStart;
+}
+
+/**
+ * Polls until somebody answers, or the request expires.
+ *
+ * `204` means keep waiting, matching the run loop's claim endpoint. The interval comes from the
+ * server rather than being chosen here, because every poll is an invocation on the other end and
+ * the server is the side that knows what it can afford.
+ */
+export async function waitForApproval(
+  start: ApprovalStart,
+  deps: {
+    server: string;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    onWaiting?: (secondsElapsed: number) => void;
+    signal?: AbortSignal;
+  },
+): Promise<ApprovalOutcome> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now ?? (() => Date.now());
+
+  const startedAt = now();
+  const deadline = Date.parse(start.expiresAt);
+  let announced = 0;
+
+  for (;;) {
+    if (deps.signal?.aborted) throw new ApprovalFailed("Stopped waiting.");
+    if (now() >= deadline) return { status: "expired" };
+
+    const response = await fetchImpl(new URL("api/approvals/collect", deps.server + "/"), {
+      method: "POST",
+      headers: { authorization: `Bearer ${start.deviceCode}`, accept: "application/json" },
+      redirect: "error",
+    }).catch(() => null);
+
+    // A dropped poll is not an answer. Keep waiting rather than failing someone's setup because a
+    // wifi card slept: the deadline is what ends this, not one bad request.
+    if (response && response.status !== 204) {
+      if (!response.ok) {
+        throw new ApprovalFailed(`${deps.server} refused the approval check (${response.status}).`);
+      }
+      const body = (await response.json()) as ApprovalOutcome;
+      if (body.status !== "expired" || now() >= deadline) return body;
+    }
+
+    const elapsed = Math.round((now() - startedAt) / 1000);
+    if (elapsed - announced >= 15) {
+      announced = elapsed;
+      deps.onWaiting?.(elapsed);
+    }
+    await sleep(start.pollMs);
+  }
+}

package/src/protocol/client.ts

@@ -76,6 +76,7 @@ export interface ModelProxyRequest {
   system: string | null;
   prompt: string;
   responseShape: string;
+  responseSchema: Record<string, unknown>;
   maxOutputTokens: number;
   temperature: number;
   images: unknown[];

package/src/run/execute.ts

@@ -155,6 +155,7 @@ export async function executeLease(deps: ExecuteDeps): Promise<ExecuteResult> {
       run: { ...deps.run, snapshot },
       snapshot,
       productId: deps.productId,
+      syntheticEmailTemplate: deps.local.syntheticEmailTemplate,
     },
     {
       gateway,
@@ -253,6 +254,9 @@ export async function executeLease(deps: ExecuteDeps): Promise<ExecuteResult> {
   if (outcome && !leaseLost) {
     // Same order as the server's own persistence: findings before the report, because the report
     // holds ordered identifiers that have to resolve to something.
+    // Sessions are checkpointed before synthesis, then posted again here because integrity runs
+    // during synthesis and enriches them with the evidence exclusions the replay must disclose.
+    await postPart(deps.client, deps.lease.id, "sessions", outcome.sessions);
     await postPart(deps.client, deps.lease.id, "judgments", outcome.judgments);
     await postPart(deps.client, deps.lease.id, "issues", outcome.issues);
     await postPart(deps.client, deps.lease.id, "findings", outcome.findings);

package/src/version.ts

@@ -10,7 +10,62 @@
  * package.json beside it to read, and importing one into the source trips the composite build's
  * rootDir. `version.test.ts` asserts this matches, so the drift this invites cannot survive CI.
  */
-export const RUNNER_VERSION = "0.2.5";
+export const RUNNER_VERSION = "0.3.1";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";
+
+export interface RunnerVersionPolicy {
+  /** The oldest release that may claim new work. */
+  minimum: string;
+  /** The exact official release a start should move to when it can. */
+  recommended: string;
+}
+
+/** Strict because a server response eventually becomes part of an npm package specifier. */
+function versionParts(value: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (!match) return null;
+  const parts = [Number(match[1]), Number(match[2]), Number(match[3])] as [number, number, number];
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+/** Numeric comparison, so 0.10.0 is newer than 0.9.9 rather than lexicographically smaller. */
+export function compareRunnerVersions(left: string, right: string): number | null {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index]! > b[index]!) return 1;
+    if (a[index]! < b[index]!) return -1;
+  }
+  return 0;
+}
+
+/** Parses only a coherent policy. A bad control-plane response never becomes an install command. */
+export function runnerVersionPolicyFrom(value: unknown): RunnerVersionPolicy | null {
+  if (!value || typeof value !== "object") return null;
+  const policy = value as { minimum?: unknown; recommended?: unknown };
+  if (typeof policy.minimum !== "string" || typeof policy.recommended !== "string") return null;
+  const order = compareRunnerVersions(policy.recommended, policy.minimum);
+  if (order === null || order < 0) return null;
+  return { minimum: policy.minimum, recommended: policy.recommended };
+}
+
+export interface RunnerUpdate {
+  target: string;
+  /** Required means the installed release cannot claim work if updating fails. */
+  required: boolean;
+}
+
+/** What this installed runner should do with one valid server policy. Never chooses a downgrade. */
+export function runnerUpdateFor(
+  policy: RunnerVersionPolicy,
+  current: string = RUNNER_VERSION,
+): RunnerUpdate | null {
+  const recommendedOrder = compareRunnerVersions(policy.recommended, current);
+  const minimumOrder = compareRunnerVersions(policy.minimum, current);
+  if (recommendedOrder === null || minimumOrder === null) return null;
+  if (recommendedOrder <= 0) return null;
+  return { target: policy.recommended, required: minimumOrder > 0 };
+}