@saadnvd1/agent-os 0.3.637 → 0.3.644

package/lib/tasks/contract/client.ts

@@ -0,0 +1,296 @@
+/**
+ * The one client for a task running on a linked machine: every call the Mac
+ * makes to that machine's task API, with its path, body, timeout and retry in
+ * one place. Callers hold a HostLink and say what they want; none of them
+ * builds a task URL.
+ */
+
+import { MERGE_METHODS, type MergeMethod } from "../merge-methods";
+import type { Session } from "../../db";
+import {
+  HostApiError,
+  cleanRemoteBlock,
+  cleanRemoteText,
+  hostApi,
+  type HostLink,
+} from "../../hosts/remote-api";
+import type { OrchestratedBundle } from "../move-bundle";
+import type { TaskBundle } from "../move-bundle";
+import {
+  HELD_REPLIES,
+  IMPORT,
+  LIST,
+  TIMEOUT,
+  arrivedPath,
+  taskPath,
+} from "./routes";
+import type { ChatFacts, HostTasks } from "./types";
+
+export const unknownOutcome = (err: unknown) =>
+  err instanceof HostApiError && !err.refused;
+
+/** POST a call that's safe to repeat; once more if we can't tell it landed. */
+export async function postIdempotent<T>(
+  link: HostLink,
+  path: string,
+  body: unknown,
+  timeout: number
+): Promise<T> {
+  try {
+    return await hostApi<T>(link, path, { body, timeout });
+  } catch (err) {
+    if (!unknownOutcome(err)) throw err;
+    return hostApi<T>(link, path, { body, timeout });
+  }
+}
+
+/** POST, repeated when the outcome is unknown (the calls are idempotent). */
+export async function tell(
+  link: HostLink,
+  path: string,
+  body: object = {}
+): Promise<void> {
+  for (let i = 0; ; i++) {
+    try {
+      await hostApi(link, path, { body });
+      return;
+    } catch (err) {
+      if (!unknownOutcome(err) || i === 2) throw err;
+    }
+  }
+}
+
+const cache = new Map<string, { at: number; list: Promise<HostTasks> }>();
+
+/** The machine's task list; the last answer within 3 s unless `fresh`. */
+export function list(link: HostLink, fresh = false): Promise<HostTasks> {
+  const hit = cache.get(link.hostId);
+  if (!fresh && hit && Date.now() - hit.at < 3000) return hit.list;
+  const next = hostApi<HostTasks>(link, LIST, { timeout: TIMEOUT.list });
+  cache.set(link.hostId, { at: Date.now(), list: next });
+  next.catch(() => cache.delete(link.hostId));
+  return next;
+}
+
+export const forget = (hostId: string) => cache.delete(hostId);
+
+export async function view(
+  link: HostLink,
+  id: string,
+  fresh = false
+): Promise<HostTasks["tasks"][number] | undefined> {
+  const { tasks } = await list(link, fresh);
+  return (Array.isArray(tasks) ? tasks : []).find((t) => t?.id === id);
+}
+
+/**
+ * A machine on an older AgentOS would take a chat task as a terminal one,
+ * or an orchestrator's task as a plain one that anyone there could merge, or
+ * refuse to hand one over.
+ */
+export async function requireCapability(
+  link: HostLink,
+  capability: string,
+  what: string,
+  verb = "move"
+): Promise<void> {
+  const { capabilities = [] } = await list(link, true).catch((err) => {
+    throw new Error(
+      `Can't ask ${link.hostName} whether it takes ${what}: ${(err as Error).message}`
+    );
+  });
+  if (!capabilities.includes(capability))
+    throw new Error(
+      `${link.hostName}'s AgentOS can't ${verb} ${what} yet; update it first`
+    );
+}
+
+export const start = (link: HostLink, body: object) =>
+  postIdempotent<{ session: Session }>(link, LIST, body, TIMEOUT.start);
+
+export async function plan(link: HostLink, id: string): Promise<string | null> {
+  const { text } = await hostApi<{ text: string | null }>(
+    link,
+    taskPath(id, "plan"),
+    { timeout: TIMEOUT.plan }
+  );
+  return text;
+}
+
+export const approvePlan = (link: HostLink, id: string, message?: string) =>
+  hostApi<{ model?: string }>(link, taskPath(id, "approve-plan"), {
+    body: message ? { message } : {},
+    timeout: TIMEOUT.approvePlan,
+  });
+
+export async function hold(
+  link: HostLink,
+  id: string,
+  orchestrated: OrchestratedBundle
+): Promise<void> {
+  await hostApi(link, taskPath(id, "hold"), {
+    body: { orchestrated },
+    timeout: TIMEOUT.hold,
+  });
+}
+
+export async function message(
+  link: HostLink,
+  id: string,
+  body: { id?: string; line: string; from: string }
+): Promise<"queued" | "delivered"> {
+  const { state } = await hostApi<{ state?: unknown }>(
+    link,
+    taskPath(id, "message"),
+    { body, timeout: TIMEOUT.message }
+  );
+  return state === "queued" ? "queued" : "delivered";
+}
+
+export async function chatTail(
+  link: HostLink,
+  id: string,
+  lines: number
+): Promise<string | null> {
+  const { text } = await hostApi<{ text?: unknown }>(
+    link,
+    `${taskPath(id, "chat-tail")}?lines=${lines}`,
+    { timeout: TIMEOUT.chat }
+  );
+  // Whole lines, as a local read has them (read.ts caps and trims them).
+  return typeof text === "string" ? cleanRemoteBlock(text, 16000) : null;
+}
+
+export async function chatFacts(
+  link: HostLink,
+  id: string
+): Promise<ChatFacts | null> {
+  const res = await hostApi<{ blocked?: unknown; turn?: unknown }>(
+    link,
+    taskPath(id, "chat-facts"),
+    { timeout: TIMEOUT.chat }
+  );
+  if (res.blocked !== null && typeof res.blocked !== "string") return null;
+  if (res.turn !== null && typeof res.turn !== "string") return null;
+  return {
+    blocked: res.blocked ? cleanRemoteBlock(res.blocked, 2000) : null,
+    turn: res.turn,
+  };
+}
+
+export async function stop(link: HostLink, id: string): Promise<string> {
+  const { text } = await hostApi<{ text?: unknown }>(
+    link,
+    taskPath(id, "stop"),
+    {
+      body: {},
+      timeout: TIMEOUT.stop,
+    }
+  );
+  return cleanRemoteText(text);
+}
+
+export async function done(link: HostLink, id: string): Promise<void> {
+  await hostApi(link, taskPath(id, "done"), {
+    body: {},
+    timeout: TIMEOUT.done,
+  });
+}
+
+/** A merge returns the method that machine merged with; null when it doesn't say. */
+export async function merge(
+  link: HostLink,
+  id: string,
+  pin?: { head: string; base?: string | null },
+  label = "it"
+): Promise<{ head: string | null; method: MergeMethod | null }> {
+  // An AgentOS that predates pinned merges would ignore the head and merge
+  // whatever the PR is at: refuse before asking it.
+  if (pin)
+    await requireCapability(link, "pinned-merge", "a merge to a commit", "pin");
+  const res = await hostApi<{ head?: string | null; method?: unknown }>(
+    link,
+    taskPath(id, "merge"),
+    {
+      // base: what the gates here were judged against; the machine that
+      // merges compares the PR with it, not with a base only it recorded.
+      body: {
+        ...(pin && { head: pin.head }),
+        ...(pin?.base && { base: pin.base }),
+      },
+      timeout: TIMEOUT.merge,
+    }
+  ).catch(async (err) => {
+    if (!unknownOutcome(err)) throw err;
+    // A proxy or a dropped connection after the merge ran answers 502 with
+    // nothing from AgentOS: ask what state the task is in before failing.
+    const merged = await view(link, id, true)
+      .then((t) => t?.state === "merged")
+      .catch(() => false);
+    if (!merged)
+      throw new Error(
+        `${(err as Error).message}: couldn't confirm whether ${link.hostName} merged ${label}; check its PR before signing off again`
+      );
+    return { head: pin?.head ?? null, method: undefined };
+  });
+  forget(link.hostId);
+  return {
+    head: res.head ?? null,
+    method: MERGE_METHODS.find((m) => m === res.method) ?? null,
+  };
+}
+
+export async function drop(link: HostLink, id: string): Promise<void> {
+  await hostApi(link, taskPath(id, "drop"), {
+    body: {},
+    timeout: TIMEOUT.merge,
+  });
+  forget(link.hostId);
+}
+
+export const resume = (link: HostLink, id: string, body: object = {}) =>
+  tell(link, taskPath(id, "resume"), body);
+
+export const confirmMoved = (link: HostLink, id: string, to: string) =>
+  tell(link, taskPath(id, "moved"), { to });
+
+export async function exportOut(
+  link: HostLink,
+  id: string,
+  to: string
+): Promise<TaskBundle> {
+  const { bundle } = await postIdempotent<{ bundle: TaskBundle }>(
+    link,
+    taskPath(id, "export"),
+    { to },
+    TIMEOUT.exportOut
+  );
+  return bundle;
+}
+
+export const importBundle = (link: HostLink, bundle: TaskBundle) =>
+  postIdempotent<{ session: Session }>(
+    link,
+    IMPORT,
+    bundle,
+    TIMEOUT.importBundle
+  );
+
+export async function arrived(
+  link: HostLink,
+  from: string
+): Promise<Session | null> {
+  const { session } = await hostApi<{ session: Session | null }>(
+    link,
+    arrivedPath(from)
+  );
+  return session;
+}
+
+export const replies = (link: HostLink) =>
+  hostApi<{ messages?: unknown }>(link, HELD_REPLIES, {
+    timeout: TIMEOUT.replies,
+  });
+
+export const ackReplies = (link: HostLink, ids: number[]) =>
+  hostApi(link, HELD_REPLIES, { body: { ids }, timeout: TIMEOUT.replies });

package/lib/tasks/{held-remote.ts → contract/held-calls.ts}

@@ -1,25 +1,22 @@
 /**
- * An orchestrator's calls on a task it moved to a linked machine, which that
- * machine's AgentOS answers for the device that sent the task (held.ts). The
- * orchestrator polls and calls; the other machine never reaches back.
+ * An orchestrator's calls on a task it put on a linked machine, which that
+ * machine's AgentOS answers for the device that sent the task (held.ts). A
+ * machine that doesn't hold the task yet is asked to, once, and the call
+ * repeated. The orchestrator polls and calls; the other machine never reaches
+ * back.
  */
 
-import { db, type Session } from "../db";
+import { db, type Session } from "../../db";
 import {
   HostApiError,
-  cleanRemoteBlock,
-  cleanRemoteText,
-  hostApi,
   hostLink,
   requireHostLink,
-} from "../hosts/remote-api";
-import type { Delivery } from "../bus/delivery";
-import { wakeLine } from "../bus/format";
-import { orchestratedStart } from "./held";
-import { orchestratorOf } from "./starter";
-
-const path = (id: string, leaf: string) =>
-  `/api/tasks/${encodeURIComponent(id)}/${leaf}`;
+} from "../../hosts/remote-api";
+import type { Delivery } from "../../bus/delivery";
+import { wakeLine } from "../../bus/format";
+import { orchestratedStart } from "../held";
+import { orchestratorOf } from "../starter";
+import * as client from "./client";
 
 /**
  * A task its orchestrator put on a linked machine, whether by moving it or
@@ -54,16 +51,11 @@ async function adoptHeld(task: Held): Promise<boolean> {
   if (adopted.has(task.id)) return false;
   adopted.set(task.id, now);
   try {
-    const link = requireHostLink(task.host_id);
-    await hostApi(link, path(task.id, "hold"), {
-      body: {
-        orchestrated: orchestratedStart(
-          task.started_by!,
-          task.task_since ?? null
-        ),
-      },
-      timeout: 20000,
-    });
+    await client.hold(
+      requireHostLink(task.host_id),
+      task.id,
+      orchestratedStart(task.started_by!, task.task_since ?? null)
+    );
   } catch {
     return false;
   }
@@ -72,6 +64,8 @@ async function adoptHeld(task: Held): Promise<boolean> {
   return true;
 }
 
+// compat: task-contract-1. A task the queue placed before machines held them
+// is unheld there; drop this heal once every linked machine holds on start.
 /** The call, held first if that machine says it isn't, once. */
 async function withHold<T>(task: Held, call: () => Promise<T>): Promise<T> {
   try {
@@ -142,16 +136,13 @@ export async function relayToHeldTask(
   try {
     const link = requireHostLink(to.host_id);
     const send = () =>
-      hostApi<{ state?: unknown }>(link, path(to.id, "message"), {
-        body: {
-          id: messageId ? `bus-${messageId}` : undefined,
-          line,
-          from: fromName,
-        },
-        timeout: 20000,
+      client.message(link, to.id, {
+        id: messageId ? `bus-${messageId}` : undefined,
+        line,
+        from: fromName,
       });
-    const { state } = await (heal ? withHold(to, send) : send());
-    return { state: state === "queued" ? "queued" : "delivered" };
+    const state = await (heal ? withHold(to, send) : send());
+    return { state };
   } catch (error) {
     const why = error instanceof Error ? error.message : String(error);
     return { state: "failed", why: why.slice(0, 300) };
@@ -164,15 +155,9 @@ export async function heldChatTail(
   lines: number
 ): Promise<string | null> {
   const link = requireHostLink(task.host_id);
-  const { text } = await withHold(task, () =>
-    hostApi<{ text?: unknown }>(
-      link,
-      `${path(task.id, "chat-tail")}?lines=${lines}`,
-      { timeout: 10000 }
-    )
-  ).catch(() => ({ text: undefined }));
-  // Whole lines, as a local read has them (read.ts caps and trims them).
-  return typeof text === "string" ? cleanRemoteBlock(text, 16000) : null;
+  return withHold(task, () => client.chatTail(link, task.id, lines)).catch(
+    () => null
+  );
 }
 
 /**
@@ -184,38 +169,22 @@ export async function heldChatFacts(
   task: Held
 ): Promise<{ blocked: string | null; turn: string | null } | null> {
   const link = requireHostLink(task.host_id);
-  const res = await withHold(task, () =>
-    hostApi<{ blocked?: unknown; turn?: unknown }>(
-      link,
-      path(task.id, "chat-facts"),
-      { timeout: 10000 }
-    )
-  ).catch(() => null);
-  if (!res || (res.blocked !== null && typeof res.blocked !== "string"))
-    return null;
-  if (res.turn !== null && typeof res.turn !== "string") return null;
-  return {
-    blocked: res.blocked ? cleanRemoteBlock(res.blocked, 2000) : null,
-    turn: res.turn,
-  };
+  return withHold(task, () => client.chatFacts(link, task.id)).catch(
+    () => null
+  );
 }
 
 /** Stops its agent there; its conversation and worktree are kept. */
 export async function stopHeldTask(task: Held): Promise<string> {
   const link = requireHostLink(task.host_id);
-  const { text } = await withHold(task, () =>
-    hostApi<{ text?: unknown }>(link, path(task.id, "stop"), {
-      body: {},
-      timeout: 30000,
-    })
+  return (
+    (await withHold(task, () => client.stop(link, task.id))) ||
+    `Stopped ${task.name}.`
   );
-  return cleanRemoteText(text) || `Stopped ${task.name}.`;
 }
 
 /** Done there: its agent stops and its worktree goes. Never a merge. */
 export async function doneHeldTask(task: Held): Promise<void> {
   const link = requireHostLink(task.host_id);
-  await withHold(task, () =>
-    hostApi(link, path(task.id, "done"), { body: {}, timeout: 120000 })
-  );
+  await withHold(task, () => client.done(link, task.id));
 }

package/lib/tasks/contract/index.ts

@@ -0,0 +1,28 @@
+/**
+ * How a task runs on a linked machine: one client for its API
+ * (client.ts), one authorization rule per route (authorize.ts), one loop that
+ * keeps mirrors current (sync.ts). Local code paths call these through the
+ * entry points they already had (signOff, dropTask, deliver, ...).
+ */
+
+export * as taskClient from "./client";
+export { TASK_CAPABILITIES, type HostTasks } from "./types";
+export {
+  isMirror,
+  mirrorTask,
+  startRemoteTask,
+  setMirrorStatus,
+} from "./start";
+export { mergeThere, dropThere } from "./actions";
+export { mirrorViews } from "./views";
+export { syncMirrors } from "./sync";
+export { taskRoute, refuse, callerRefusal, type Rule } from "./authorize";
+export {
+  isHeldRemote,
+  relayToHeldTask,
+  heldChatTail,
+  heldChatFacts,
+  stopHeldTask,
+  doneHeldTask,
+  flushUndelivered,
+} from "./held-calls";

package/lib/tasks/{remote-plan-path.ts → contract/plan-path.ts}

@@ -1,7 +1,7 @@
 import path from "path";
-import { plansDir } from "../plans/features";
+import { plansDir } from "../../plans/features";
 
 // A plan written on a linked machine, copied here so this machine's
-// orchestrator and plan view can read it (remote-plan.ts).
+// orchestrator and plan view can read it (contract/plan.ts).
 export const remotePlanPath = (sessionId: string) =>
   path.join(plansDir(), "remote", `${sessionId}.md`);