@runuai/host 0.9.9 → 0.9.10

package/lib/agent-cli.ts

@@ -4,11 +4,12 @@
  * At task-up the host writes two files into the task workspace (bind-mounted at
  * /workspace, like skills — no docker cp/exec needed):
  *   - `.uai/cli.mjs`   — the self-contained agent CLI (Node ESM, fetch-only).
- *   - `.uai/uai.json`  — { apiUrl, token, permissions } the CLI reads.
+ *   - `.uai/uai.json`  — shared, tokenless { apiUrl } config the CLI reads.
  *
- * The token is minted here (host-side) carrying the task id, its owner user, and
- * the UNION of the roster's permissions; the cloud verifies it. Agents invoke it
- * as `node /workspace/.uai/cli.mjs <cmd>` (surfaced in the system preamble).
+ * A token is minted here per agent (host-side), carrying the task id, its owner
+ * user, that agent's identity, and only that agent's permissions; the cloud
+ * verifies it. Agents invoke the CLI as `node /workspace/.uai/cli.mjs <cmd>`
+ * (surfaced in the system preamble).
  */
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -45,7 +46,7 @@ export function loadTaskCliSecret(taskId: string): string | null {
   }
 }
 
-/** The union of a roster's permissions (ADR-048) — the task's effective powers. */
+/** The union used only to decide whether this task needs the shared CLI file. */
 export function rosterPermissions(roster: RosterAgent[]): string[] {
   return Array.from(new Set(roster.flatMap((a) => a.permissions ?? [])));
 }
@@ -253,6 +254,29 @@ async function main() {
       })).task);
       break;
     }
+    case "task close": {
+      const allowed = new Set(["status", "reason"]);
+      const unknown = Object.keys(flags).filter((flag) => !allowed.has(flag));
+      if (pos.length || unknown.length) {
+        console.error("uai: task close accepts only --status and --reason");
+        process.exit(1);
+      }
+      const status = flags.status;
+      if (status !== "finished" && status !== "canceled") {
+        console.error("uai: task close needs --status finished|canceled");
+        process.exit(1);
+      }
+      if (flags.reason === "true") {
+        console.error("uai: --reason needs text (quote multiword reasons)");
+        process.exit(1);
+      }
+      const closed = await api("POST", "/api/agent/tasks/close", {
+        status,
+        ...(flags.reason ? { reason: String(flags.reason) } : {}),
+      });
+      out("task closed as " + closed.status);
+      break;
+    }
     case "todo list": {
       const todos = (await api("GET", "/api/agent/todos")).todos || [];
       if (!todos.length) { out("punchlist is empty"); break; }
@@ -329,6 +353,7 @@ async function main() {
         "  uai people list",
         "  uai task list",
         "  uai task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]",
+        '  uai task close --status finished|canceled [--reason "final report"]',
         "  uai memory search <query>",
         "  uai memory save <text> [--project id] [--tags a,b]",
         "  uai memory delete <id>",

package/lib/agents/durable-proc.ts

@@ -249,14 +249,28 @@ export class DurableProcess {
     this.exitHandlers.add(handler);
   }
 
-  /** Serialise `value` as one JSONL line appended to the runner's inbox. */
+  /**
+   * Serialise `value` as one JSONL line appended to the runner's inbox.
+   * A runner-filtered metadata line immediately before it supplies the local
+   * timestamp without changing the protocol frame forwarded to the CLI. Old
+   * runners already ignore unknown `__uai` lines, so attached sessions remain
+   * wire-compatible across the host update.
+   *
+   * `__uai` MUST stay the first key of the metadata object. Both runners filter
+   * with `line.startsWith('{"__uai"')` — a byte prefix, not a parse — so
+   * serialising the keys in any other order emits `{"ts":…`, which the runner
+   * then forwards to the CLI's stdin as a user turn. No type in this file
+   * expresses that, and a `toEqual` assertion cannot see it; the raw-prefix
+   * check in `durable-proc.test.ts` is what pins it.
+   */
   writeLine(value: unknown): void {
     if (this.closed || this.detached) return;
     const json = JSON.stringify(value);
+    const inputMeta = JSON.stringify({ __uai: "input", ts: Date.now() });
     if (this.debug) this.log(`-> ${json.slice(0, 1000)}`);
     // Chain appends so concurrent writes can't interleave bytes.
     this.inboxChain = this.inboxChain
-      .then(() => fsp.appendFile(this.inboxPath, `${json}\n`))
+      .then(() => fsp.appendFile(this.inboxPath, `${inputMeta}\n${json}\n`))
       .catch(() => {
         // Disk error — liveness checks will surface a dead session.
       });

package/lib/agents/transport.ts

@@ -22,8 +22,16 @@
  * feature, and each spawn ships the runner version matching this host.
  */
 
-import { copyFileSync, mkdirSync, statSync, promises as fsp } from "node:fs";
-import { join } from "node:path";
+import {
+  copyFileSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  promises as fsp,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 import { and, eq } from "drizzle-orm";
 
@@ -93,6 +101,7 @@ function durableEnabled(): boolean {
 
 export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
   if (!durableEnabled()) {
+    clearCurrentSession(opts.taskId, opts.agentId);
     const { command, args } = dockerExecArgs(
       opts.containerName,
       opts.cli,
@@ -157,6 +166,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
       debugLabel: opts.debugLabel,
     });
     proc.onExit(markClosed);
+    publishCurrentSession(row.sessionDir);
     return claimTail(tailKey, proc);
   }
 
@@ -194,6 +204,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
     console.warn(
       `[transport] runner unavailable (${err instanceof Error ? err.message : err}) — falling back to direct pipes for ${opts.agentId}`,
     );
+    clearCurrentSession(opts.taskId, opts.agentId);
     const { command, args } = dockerExecArgs(
       opts.containerName,
       opts.cli,
@@ -263,9 +274,49 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
     .run();
 
   proc.onExit(markClosed);
+  publishCurrentSession(sessionDir);
   return claimTail(tailKey, proc);
 }
 
+/**
+ * Make the opaque generation directory discoverable from inside the task.
+ * The relative link resolves on both sides of the workspace bind mount. The
+ * pointer is diagnostic only: failure to publish it must not kill a session.
+ */
+function publishCurrentSession(sessionDir: string): void {
+  const parent = dirname(sessionDir);
+  const current = join(parent, "current");
+  const pending = join(parent, `.current-${process.pid}-${Date.now()}`);
+  try {
+    symlinkSync(basename(sessionDir), pending, "dir");
+    renameSync(pending, current);
+  } catch {
+    try {
+      rmSync(pending, { force: true });
+    } catch {
+      // Best-effort navigation aid; the generation path remains authoritative.
+    }
+  }
+}
+
+/** A direct-pipe session must not leave an older durable inbox looking live. */
+function clearCurrentSession(taskId: string, agentId: string): void {
+  try {
+    rmSync(
+      join(
+        taskWorkspaceDir(taskId),
+        ".uai",
+        "sessions",
+        agentId,
+        "current",
+      ),
+      { force: true },
+    );
+  } catch {
+    // Same best-effort rule as publishCurrentSession.
+  }
+}
+
 function heartbeatFresh(sessionDir: string): boolean {
   try {
     return (

package/lib/orchestrator.ts

@@ -2805,9 +2805,10 @@ export function assembleFirstTurnPrompt(
 
 /**
  * Build the system preamble an agent gets on session start. It opens
- * with how uai's channel works — agents must know to hand off via
- * `@mention`, since there is no `peer` command / shared tmux any more
- * (ADR-008) — then appends the project context and the agent's persona.
+ * with how uai's channel works. Open-mode agents hand off via `@mention`
+ * because there is no `peer` command / shared tmux (ADR-008); Secretary-mode
+ * crew report through the designated Secretary instead. It then appends the
+ * project context and the agent's persona.
  *
  * The persona / mission layers (project defaultPrompts, globalContext,
  * agent.defaultPrompt) live in the always-on system prompt so they apply
@@ -2832,6 +2833,12 @@ export function buildSystemPreamble(
       a.id === agent.id ? `@${a.id} (${a.label}, you)` : `@${a.id} (${a.label})`,
     )
     .join(", ");
+  const isSecretary =
+    mode === "secretary" && secretaryAgentId === agent.id;
+  const isSecretaryCrew =
+    mode === "secretary" &&
+    secretaryAgentId !== undefined &&
+    !isSecretary;
   // ADR-049: with several humans in the chat, brief the agent on who they are
   // and how to address one specifically. Single-human tasks keep the original
   // wording byte-identical.
@@ -2839,8 +2846,14 @@ export function buildSystemPreamble(
   const humanList = (humans ?? [])
     .map((h) => `@${h.handle} (${h.name}${h.isOwner ? ", task owner" : ""})`)
     .join(", ");
-  const humanIntro = multiHuman
+  const humanIntro = isSecretaryCrew
     ? [
+        `The human-facing conversation is owned by @${secretaryAgentId}, the`,
+        "designated Secretary. `@you` and human @handles in your replies remain",
+        "visible as routing hints, but they do not notify a human directly.",
+      ]
+    : multiHuman
+      ? [
         `SEVERAL humans share this channel: ${humanList}. Their messages`,
         "arrive prefixed with the sender's name so you can tell them apart.",
         "`@you` still works and reaches the human you're currently talking",
@@ -2855,8 +2868,8 @@ export function buildSystemPreamble(
         "just asked, acknowledgments — post in the channel WITHOUT",
         "@-mentioning; they can read the channel and don't need a ping for",
         "every message.",
-      ]
-    : [
+        ]
+      : [
         "The human you're working with is **@you**. @-mentioning them sends a",
         "NOTIFICATION, so use it sparingly — only when you actually need them: a",
         "decision you can't make, a blocker, an approval, or you've finished your",
@@ -2866,7 +2879,7 @@ export function buildSystemPreamble(
         "something they just asked, acknowledgments — post in the channel WITHOUT",
         "@-mentioning @you; they can read the channel and don't need a ping for",
         "every message. Do NOT reflexively end messages with @you.",
-      ];
+        ];
   const projectLines =
     projects.length === 0
       ? ["(none mounted)"]
@@ -2874,8 +2887,6 @@ export function buildSystemPreamble(
           (p) =>
             `- \`${workspacePath}/${p.slug}\` — git worktree on \`${taskBranch}\``,
         );
-  const isSecretary =
-    mode === "secretary" && secretaryAgentId === agent.id;
   const dispatchActionBrief = [
     "When crew work is needed, run the Secretary CLI action:",
     `\`node ${CONTAINER_CLI_PATH} dispatch @agent [@agent…] \"instruction\"\``,
@@ -2911,6 +2922,22 @@ export function buildSystemPreamble(
             "`/workspace/.uai/chat.md`. Read it whenever you need that context;",
             "it's appended live, so re-read it for the latest.",
           ];
+  const sessionInboxBrief =
+    mode !== "secretary"
+      ? []
+      : isSecretary
+        ? [
+            "When durable sessions are active, their current inboxes are linked at",
+            "`/workspace/.uai/sessions/<agent-id>/current/inbox.jsonl`.",
+            'An epoch-ms `{"__uai":"input","ts":…}` line precedes each',
+            "unchanged CLI frame, so the adjacent pair identifies a wake input.",
+          ]
+        : [
+            "When durable sessions are active, your current runner inbox is at",
+            `\`/workspace/.uai/sessions/${agent.id}/current/inbox.jsonl\`.`,
+            'An epoch-ms `{"__uai":"input","ts":…}` line precedes each',
+            "unchanged CLI frame, so the adjacent pair identifies a wake input.",
+          ];
   const secretaryRoleBrief = isSecretary
     ? [
         "## Secretary role",
@@ -2939,7 +2966,14 @@ export function buildSystemPreamble(
         "instruction for each",
         "crew member you need. Do not merely say that someone else will answer.",
       ]
-    : [
+    : isSecretaryCrew
+      ? [
+          "Handles in your dispatch or the backstage transcript are context,",
+          "not proof that another recipient was notified. Answer only for your",
+          "assigned part. If someone else should act, state who and what is",
+          "needed; the Secretary decides whether to dispatch it.",
+        ]
+      : [
         "When a message already @-mentions several participants at once (the",
         "human asking the whole group, or a peer addressing multiple agents),",
         "it's a group broadcast — this is a GROUP CHAT and everyone named has",
@@ -2949,14 +2983,20 @@ export function buildSystemPreamble(
         "turn`, or `still waiting on @x`. Re-mentioning someone who already got",
         "the message only wakes them again and spirals into duplicate replies.",
         "Say your piece and stop.",
-      ];
+        ];
   const handoffBrief = isSecretary
     ? [
         "When crew work finishes, synthesize the outcome for the human and make",
         "the next decision or blocker explicit. Do not abandon an unresolved",
         "request silently, and do not wake a peer for acknowledgments alone.",
       ]
-    : [
+    : isSecretaryCrew
+      ? [
+          "When you finish, report the result, next decision, or blocker plainly",
+          "to the Secretary; no @mention is needed. Do not assume a named peer",
+          "was woken, and do not wait for a direct reply from one.",
+        ]
+      : [
         "Hand off when you finish your part of the work. When you've made",
         "and committed your changes, or completed a review, end your reply by",
         "@-mentioning the agent who should act next and telling them what you",
@@ -2966,7 +3006,7 @@ export function buildSystemPreamble(
         "peer needs to act, it's fine to stop; only @-mention @you if you need",
         "their input or are handing back finished work for them to act on. Don't",
         "prolong an agent-to-agent exchange just to fill silence.",
-      ];
+        ];
   const checkInTranscriptBrief = isSecretary
     ? [
         "Read both transcript files named above, and speak ONLY if you have",
@@ -2974,11 +3014,13 @@ export function buildSystemPreamble(
         "PASS reply is discarded and never shown to anyone, so it is always a",
         "safe way to decline a turn.",
       ]
-    : [
+    : isSecretaryCrew
+      ? []
+      : [
         "Read the transcript, and speak ONLY if you have something substantive to",
         "add; otherwise reply with exactly `PASS` — a PASS reply is discarded and",
         "never shown to anyone, so it is always a safe way to decline a turn.",
-      ];
+        ];
   const workspaceBrief = isSecretary
     ? [
         "## Workspace layout",
@@ -3028,19 +3070,35 @@ export function buildSystemPreamble(
         "or @-mentioning a crew agent in prose does NOT wake them.",
         "The only way to hand crew work off is the structured `dispatch` action.",
       ]
-    : [
+    : isSecretaryCrew
+      ? [
+          "You are a backstage crew agent in a Secretary-mode task channel.",
+          `@${secretaryAgentId} is the designated Secretary and your sole`,
+          "conversational routing point. Every completed reply you write is",
+          `delivered once to @${secretaryAgentId}, whether it names @you, a`,
+          "human, another crew agent, or nobody. Those names remain visible as",
+          "routing hints, but they do not notify the human or wake a peer.",
+        ]
+      : [
         "You are one agent in a uai task chat channel, shared with the human",
         "and the other agents. To hand work to or ask another agent, mention",
         "it by id at the start of a line — e.g. `@codex please review the",
         "diff`. uai routes that message into that agent's input.",
-      ];
+        ];
   const collaborationBrief = isSecretary
     ? [
         "Collaborate through deliberate dispatches. Each dispatch wakes a crew",
         "agent and costs a turn, so make every instruction concrete, self-contained,",
         "and necessary. Never dispatch greetings, thanks, or acknowledgments.",
       ]
-    : [
+    : isSecretaryCrew
+      ? [
+          `Only a structured dispatch from @${secretaryAgentId} wakes a crew`,
+          "agent. Work on the assignment you received. If someone else should",
+          "act, state who and what is needed; the Secretary decides whether to",
+          "dispatch it.",
+        ]
+      : [
         "An agent only receives a message when it is explicitly @-mentioned",
         "(or addressed by the human) — so always @-mention the agent (or @you)",
         "you mean. There is NO `peer` command and no shared tmux session;",
@@ -3059,7 +3117,7 @@ export function buildSystemPreamble(
         "don't @-mention back. And when there's no active task yet (intros, or",
         "you're waiting on the human), answer briefly and then wait — you don't",
         "need to @-mention anyone (including @you); they can see the channel.",
-      ];
+        ];
   const channelConventionsBrief = isSecretary
     ? [
         "Your prose always goes to the human-facing lane; answer plainly without",
@@ -3068,13 +3126,19 @@ export function buildSystemPreamble(
         "You may occasionally receive a `[channel check-in]` asking you to catch",
         "up on the channel.",
       ]
-    : [
+    : isSecretaryCrew
+      ? [
+          "Every reply returns to the Secretary whether or not it contains",
+          "@mentions. Answer plainly; use names only when they help the",
+          "Secretary understand who should hear or act on the result.",
+        ]
+      : [
         "Two channel conventions (ADR-050): (1) If your reply @-mentions nobody,",
         "uai hands it back to whoever prompted you — so when you're ANSWERING,",
         "just answer plainly; you don't need to re-mention the asker. Mention",
         "someone only to bring them in or hand work off. (2) You may occasionally",
         "receive a `[channel check-in]` asking you to catch up on the channel.",
-      ];
+        ];
   const comms = [
     "## uai task channel",
     "",
@@ -3094,6 +3158,8 @@ export function buildSystemPreamble(
     "",
     ...transcriptBrief,
     "",
+    ...sessionInboxBrief,
+    ...(sessionInboxBrief.length > 0 ? [""] : []),
     ...secretaryRoleBrief,
     ...channelConventionsBrief,
     ...checkInTranscriptBrief,
@@ -3191,6 +3257,9 @@ export function buildSystemPreamble(
             (agent.permissions?.includes("tasks.create")
               ? ", `task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]`"
               : "") +
+            (agent.permissions?.includes("tasks.close")
+              ? ", `task close --status finished|canceled [--reason \"final report\"]`"
+              : "") +
             (agent.permissions?.includes("memory.write")
               ? ", `memory save <text>`"
               : "") +
@@ -3227,6 +3296,17 @@ export function buildSystemPreamble(
                 "`projects list` / `people list`.",
               ]
             : []),
+          ...(agent.permissions?.includes("tasks.close")
+            ? [
+                "**Closing this task:** `task close` is task-wide, not a way to",
+                "say that only your part is done. It stops every agent and",
+                "destroys this container/session. Use it only when the ENTIRE",
+                "task is terminal and the human's instructions authorize that",
+                "outcome. Make it the final action of your turn and put the",
+                "useful final summary in `--reason`, because your normal response",
+                "may not be delivered after the container tears down.",
+              ]
+            : []),
           ...(agent.permissions?.includes("memory.read") ||
           agent.permissions?.includes("memory.write")
             ? [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.9",
+  "version": "0.9.10",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/runner/runner.mjs

@@ -11,9 +11,9 @@
  *   <sessionDir>/runner.json   pid, protocol, argv, startedAt
  *
  * Meta lines are `{"__uai":"spawn"|"exit", ...}`; the host filters them out
- * before handing lines to the protocol adapters. Control lines the host
- * appends to the inbox use the same shape (`{"__uai":"stop"}`); everything
- * else in the inbox goes to the CLI's stdin untouched.
+ * before handing lines to the protocol adapters. Host metadata/control lines
+ * in the inbox use the same shape (`input` timestamps and `stop`); the runner
+ * filters those, while every protocol frame goes to the CLI's stdin untouched.
  *
  * Plain Node ≥18, dependency-free, ESM. Testable outside docker: point it
  * at a tmp dir and any line-oriented fake CLI.

package/src/protocol.ts

@@ -43,6 +43,14 @@ export const MAX_SECRETARY_DISPATCH_ID_CHARS = 256;
 
 export interface CommandContext {
   commandId: string;
+  /**
+   * Cloud-side deadline for this command, in ms. Optional and OFF by default:
+   * most commands (task-up especially) legitimately take minutes, so a blanket
+   * timeout would be wrong. When set, the cloud stops waiting AND forgets the
+   * pending entry — without that second half a silent host accumulates one
+   * dead resolver per retry.
+   */
+  timeoutMs?: number;
 }
 
 export type PermissionDecision = { kind: "accept" } | { kind: "decline" };