privateer-agent 0.1.0 → 0.2.1

package/src/remote/relayClient.ts

@@ -54,15 +54,33 @@ export interface RelayCallbacks {
   onPrompt: (text: string) => void;
   // The app asked to interrupt the in-flight turn.
   onInterrupt: () => void;
+  // The app asked to turn remote access OFF entirely (the in-app "End remote
+  // access" action). The owner should disable /remote-access — i.e. stop this
+  // client and not reconnect. Optional: the routines daemon handles it too, but
+  // callbacks that predate it keep compiling.
+  onTerminate?: () => void;
   // The app answered a relayed approval request.
   onApprovalResponse: (id: string, decision: "allow" | "deny") => void;
   // A controller attached — push a transcript snapshot so it can catch up.
   onControllerAttached: () => void;
+  // A file finished transferring from the app (reassembled from chunks). Held to
+  // ride along with the next remote prompt.
+  onAttachment: (file: { name: string; mediaType: string; base64: string }) => void;
   // Surface a one-line status/notice in the TUI.
   onStatus?: (text: string) => void;
+  // The relay socket closed (controller no longer reachable until reconnect).
+  onDisconnected?: () => void;
 }
 
 const RECONNECT_MS = 3000;
+// File-transfer ceilings for app→CLI attachments. The app enforces its own caps
+// before sending; these are a defensive backstop so a controller can't exhaust
+// memory with a lying `size` or a flood of concurrent transfers.
+const MAX_ATTACH_BYTES = 10 * 1024 * 1024; // 10 MB per file
+const MAX_INFLIGHT_ATTACH = 8; // simultaneous transfers
+// Base64 chars per file_chunk frame for agent→app sends (~135 KB decoded), kept
+// under the relay's 256 KB per-frame cap. Mirrors the app's CHUNK_CHARS.
+const FILE_CHUNK_CHARS = 180_000;
 // Coalesce streaming deltas so we don't emit one WS frame per token.
 const TEXT_FLUSH_MS = 60;
 
@@ -117,11 +135,26 @@ export class RelayClient {
   private bufKind: "text" | "reasoning" | null = null;
   private buf = "";
   private flushTimer: ReturnType<typeof setTimeout> | undefined;
-  // Stable for this process so reconnects keep the same terminal identity.
-  private readonly termId = randomUUID();
-  private readonly label = terminalLabel();
+  // Stable for this process so reconnects keep the same terminal identity. Callers
+  // may pass a persisted id/label (e.g. the routines daemon, so it shows up as one
+  // recognizable "Privateer Routines" terminal across restarts instead of a fresh
+  // random one each time).
+  private readonly termId: string;
+  private readonly label: string;
+  // In-progress file transfers from the app, keyed by the controller's attachment
+  // id. Reassembled from attach_begin/chunk/end frames, then handed to onAttachment.
+  private readonly incoming = new Map<
+    string,
+    { name: string; mediaType: string; chunks: string[]; received: number }
+  >();
 
-  constructor(private readonly cb: RelayCallbacks) {}
+  constructor(
+    private readonly cb: RelayCallbacks,
+    opts?: { termId?: string; label?: string },
+  ) {
+    this.termId = opts?.termId ?? randomUUID();
+    this.label = opts?.label ?? terminalLabel();
+  }
 
   async start(): Promise<void> {
     this.closed = false;
@@ -134,6 +167,7 @@ export class RelayClient {
     if (this.flushTimer) { clearTimeout(this.flushTimer); this.flushTimer = undefined; }
     this.bufKind = null;
     this.buf = "";
+    this.incoming.clear();
     try { this.ws?.close(); } catch (_) { /* ignore */ }
     this.ws = null;
   }
@@ -167,6 +201,7 @@ export class RelayClient {
       ws.on("message", (data) => this.handle(data));
       ws.on("close", () => {
         if (this.ws === ws) this.ws = null;
+        this.cb.onDisconnected?.();
         if (!this.closed) {
           this.cb.onStatus?.(
             opened
@@ -205,7 +240,17 @@ export class RelayClient {
   }
 
   private handle(data: WebSocket.RawData): void {
-    let frame: { type?: string; text?: string; id?: string; decision?: string };
+    let frame: {
+      type?: string;
+      text?: string;
+      id?: string;
+      decision?: string;
+      name?: string;
+      mediaType?: string;
+      size?: number;
+      seq?: number;
+      data?: string;
+    };
     try {
       frame = JSON.parse(data.toString());
     } catch (_) {
@@ -214,18 +259,79 @@ export class RelayClient {
     this.debug(`recv ${frame.type}`);
     switch (frame.type) {
       case "prompt":
-        if (typeof frame.text === "string" && frame.text.trim()) this.cb.onPrompt(frame.text);
+        // Forward even an empty/whitespace prompt: a file-only send carries no text,
+        // and the app folds any pending attachments in on the prompt frame. App.tsx
+        // no-ops a blank prompt that has no attachments, so this stays safe.
+        if (typeof frame.text === "string") this.cb.onPrompt(frame.text);
         break;
       case "interrupt":
         this.cb.onInterrupt();
         break;
+      case "terminate":
+        this.cb.onTerminate?.();
+        break;
       case "approval_response":
         if (frame.id) this.cb.onApprovalResponse(frame.id, frame.decision === "deny" ? "deny" : "allow");
         break;
       case "controller_attached":
         this.cb.onControllerAttached();
         break;
+      case "attach_begin":
+        this.beginAttachment(frame);
+        break;
+      case "attach_chunk":
+        this.appendAttachmentChunk(frame);
+        break;
+      case "attach_end":
+        this.endAttachment(frame);
+        break;
+    }
+  }
+
+  // ── app → agent file transfer (chunked) ─────────────────────────────────────
+  // Files are streamed as attach_begin → attach_chunk* → attach_end so each WS
+  // frame stays under the relay's 256 KB cap. We reassemble here and hand the
+  // completed file up via onAttachment; App.tsx folds it into the next prompt.
+
+  private beginAttachment(frame: { id?: string; name?: string; mediaType?: string; size?: number }): void {
+    const { id } = frame;
+    if (!id || typeof frame.name !== "string" || typeof frame.mediaType !== "string") return;
+    if (this.incoming.size >= MAX_INFLIGHT_ATTACH) {
+      this.cb.onStatus?.(`Dropped attachment "${frame.name}" — too many transfers in flight.`);
+      return;
+    }
+    if (typeof frame.size === "number" && frame.size > MAX_ATTACH_BYTES) {
+      this.cb.onStatus?.(`Dropped attachment "${frame.name}" — exceeds ${Math.round(MAX_ATTACH_BYTES / (1024 * 1024))} MB.`);
+      return;
+    }
+    this.incoming.set(id, { name: frame.name, mediaType: frame.mediaType, chunks: [], received: 0 });
+  }
+
+  private appendAttachmentChunk(frame: { id?: string; data?: string }): void {
+    const { id } = frame;
+    if (!id || typeof frame.data !== "string") return;
+    const entry = this.incoming.get(id);
+    if (!entry) return; // begin was dropped or never seen
+    entry.received += frame.data.length;
+    // base64 inflates by ~4/3, so received*0.75 ≈ decoded bytes. Bound it in case
+    // `size` was absent or lied at begin time.
+    if (entry.received * 0.75 > MAX_ATTACH_BYTES + 64 * 1024) {
+      this.incoming.delete(id);
+      this.cb.onStatus?.(`Dropped attachment "${entry.name}" — stream exceeded size limit.`);
+      return;
     }
+    entry.chunks.push(frame.data);
+  }
+
+  private endAttachment(frame: { id?: string }): void {
+    const { id } = frame;
+    if (!id) return;
+    const entry = this.incoming.get(id);
+    if (!entry) return;
+    this.incoming.delete(id);
+    const base64 = entry.chunks.join("");
+    if (!base64) return;
+    this.cb.onAttachment({ name: entry.name, mediaType: entry.mediaType, base64 });
   }
 
   private rawSend(frame: unknown): void {
@@ -237,6 +343,23 @@ export class RelayClient {
 
   // ── agent → controller ──────────────────────────────────────────────────────
 
+  // Is the relay socket currently open? (Not the same as "a controller is
+  // attached" — the server forwards to a controller only when one is present.)
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  // Push a finished routine result to any attached controller as a text event, so
+  // it renders in the app's live feed. Returns whether the socket was open to send
+  // on; a durable channel (file/notice) still backs this up, since we can't know
+  // for certain a controller was attached.
+  sendRoutineResult(name: string, content: string): boolean {
+    if (!this.isConnected()) return false;
+    this.flushDeltas();
+    this.rawSend({ type: "event", event: { type: "text", text: safe(`⏺ Routine "${name}"\n\n${content}`, 8000) } });
+    return true;
+  }
+
   sendEvent(ev: EngineEvent): void {
     if (ev.type === "text") return this.bufferDelta("text", ev.text);
     if (ev.type === "reasoning") return this.bufferDelta("reasoning", ev.text);
@@ -252,6 +375,38 @@ export class RelayClient {
     this.rawSend({ type: "snapshot", entries: trimmed });
   }
 
+  // ── agent → app file transfer (chunked) ─────────────────────────────────────
+  // Reverse of the attach_* path: file_begin → file_chunk* → file_end, each frame
+  // under the relay's 256 KB cap. Fire-and-forget past the socket — the server
+  // drops frames when no controller is attached and there is no ack, so "ok" means
+  // "handed to an open socket", not "the app received it". The payload is base64
+  // binary, so no redactSecrets (it would corrupt the bytes) — the caller decides
+  // what's safe to send.
+  async sendFile(file: {
+    name: string;
+    mediaType: string;
+    base64: string;
+    size: number;
+  }): Promise<{ ok: boolean; reason?: string }> {
+    if (!this.isConnected()) return { ok: false, reason: "relay socket not connected" };
+    if (file.size > MAX_ATTACH_BYTES) {
+      return { ok: false, reason: `exceeds the ${Math.round(MAX_ATTACH_BYTES / (1024 * 1024))} MB relay limit` };
+    }
+    this.flushDeltas(); // land the file in order relative to buffered text
+    const id = randomUUID();
+    this.rawSend({ type: "file_begin", id, name: file.name, mediaType: file.mediaType, size: file.size });
+    for (let off = 0, seq = 0; off < file.base64.length; off += FILE_CHUNK_CHARS, seq++) {
+      if (!this.isConnected()) return { ok: false, reason: "connection lost mid-transfer" };
+      this.rawSend({ type: "file_chunk", id, seq, data: file.base64.slice(off, off + FILE_CHUNK_CHARS) });
+      // Yield between frames of a multi-chunk file so a big send doesn't starve
+      // the event loop (ws buffers internally; no drain dance needed at ≤10 MB).
+      if (file.base64.length > FILE_CHUNK_CHARS) await new Promise((r) => setImmediate(r));
+    }
+    if (!this.isConnected()) return { ok: false, reason: "connection lost mid-transfer" };
+    this.rawSend({ type: "file_end", id });
+    return { ok: true };
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",

package/src/routines/cron.ts

@@ -0,0 +1,109 @@
+// A minimal standard 5-field cron parser: "minute hour day-of-month month day-of-week".
+// Supports `*`, single numbers, comma lists (`1,15`), ranges (`1-5`), and steps
+// (`*/2`, `0-30/10`). Month (1-12) and day-of-week (0-6, Sunday=0) also accept the
+// usual three-letter names (jan…dec, sun…sat). Kept dependency-free on purpose.
+
+interface CronFields {
+  minute: Set<number>;
+  hour: Set<number>;
+  dom: Set<number>; // day of month
+  month: Set<number>;
+  dow: Set<number>; // day of week, 0=Sun
+  domRestricted: boolean; // field was not "*"
+  dowRestricted: boolean;
+}
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+
+function nameToNum(token: string, names: string[]): string {
+  const i = names.indexOf(token.toLowerCase());
+  return i >= 0 ? String(i + (names === MONTHS ? 1 : 0)) : token;
+}
+
+// Expand one field into the set of matching integers, validating against [min,max].
+function parseField(field: string, min: number, max: number, names?: string[]): Set<number> {
+  const out = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) throw new Error(`invalid step in "${part}"`);
+
+    let lo: number;
+    let hi: number;
+    if (rangePart === "*") {
+      lo = min;
+      hi = max;
+    } else {
+      const bounds = rangePart.split("-").map((t) => (names ? nameToNum(t, names) : t));
+      lo = Number(bounds[0]);
+      hi = bounds.length > 1 ? Number(bounds[1]) : lo;
+      if (!Number.isInteger(lo) || !Number.isInteger(hi)) throw new Error(`invalid range "${rangePart}"`);
+      // Allow Sunday as both 0 and 7 for day-of-week.
+      if (max === 6) {
+        if (lo === 7) lo = 0;
+        if (hi === 7) hi = 0;
+      }
+      if (lo < min || hi > max || lo > hi) throw new Error(`out-of-range field "${rangePart}"`);
+    }
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  if (out.size === 0) throw new Error(`empty field "${field}"`);
+  return out;
+}
+
+export function parseCron(expr: string): CronFields {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`cron expression must have 5 fields (got ${parts.length}): "${expr}"`);
+  }
+  const [minute, hour, dom, month, dow] = parts;
+  return {
+    minute: parseField(minute, 0, 59),
+    hour: parseField(hour, 0, 23),
+    dom: parseField(dom, 1, 31),
+    month: parseField(month, 1, 12, MONTHS),
+    dow: parseField(dow, 0, 6, DAYS),
+    domRestricted: dom !== "*",
+    dowRestricted: dow !== "*",
+  };
+}
+
+// Validate an expression, returning an error message or null if it parses.
+export function cronError(expr: string): string | null {
+  try {
+    parseCron(expr);
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+function matches(f: CronFields, d: Date): boolean {
+  if (!f.minute.has(d.getMinutes())) return false;
+  if (!f.hour.has(d.getHours())) return false;
+  if (!f.month.has(d.getMonth() + 1)) return false;
+  // Standard cron: when BOTH day-of-month and day-of-week are restricted, a match
+  // on EITHER is sufficient. When only one is restricted, it alone must match.
+  const domOk = f.dom.has(d.getDate());
+  const dowOk = f.dow.has(d.getDay());
+  if (f.domRestricted && f.dowRestricted) return domOk || dowOk;
+  if (f.domRestricted) return domOk;
+  if (f.dowRestricted) return dowOk;
+  return true;
+}
+
+// The next fire time strictly after `from` (local time), or null if none within a
+// ~4-year horizon (e.g. Feb 30). Seconds/millis are cleared; we scan minute by minute.
+export function nextRun(expr: string, from: Date = new Date()): Date | null {
+  const fields = parseCron(expr);
+  const d = new Date(from.getTime());
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1); // strictly after `from`
+  const limit = 366 * 4 * 24 * 60; // minutes in ~4 years
+  for (let i = 0; i < limit; i++) {
+    if (matches(fields, d)) return d;
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  return null;
+}

package/src/routines/delivery.ts

@@ -0,0 +1,75 @@
+import type { Routine } from "./schema.ts";
+import { writeRoutineOutput, addNotice } from "./store.ts";
+
+// A relay pusher, injected by the daemon. Given the finished result it either
+// forwards it to an attached controller immediately ("live") or persists it to the
+// pending-relay queue to flush when the app next attaches ("queued"). Either way the
+// result is durably accounted for, so delivery doesn't add a notice backstop for it.
+export type RelayPusher = (routine: Routine, content: string) => "live" | "queued";
+
+export interface DeliveryContext {
+  pushRelay?: RelayPusher;
+}
+
+export interface DeliveryReport {
+  // Channels that actually delivered (email is handled inside the agent run, so it
+  // never appears here — see the daemon).
+  delivered: string[];
+  // Absolute path to latest.md when file delivery ran.
+  filePath?: string;
+}
+
+function previewOf(content: string): string {
+  return content.replace(/\s+/g, " ").trim().slice(0, 120) || "(no output)";
+}
+
+// Deliver a routine's result to its configured channels. `file` and `notice` are
+// deterministic and on-box. `relay` pushes to an attached controller in real time
+// (best-effort — the socket may be up with no controller attached), so we ALSO keep
+// a durable record when the routine has no other on-box channel, guaranteeing the
+// result is never silently lost. `email` is intentionally not handled here: it is
+// fulfilled inside the agent turn (the daemon adds the Gmail tool + an instruction
+// to the prompt) so plaintext egress stays an explicit, gated action.
+export function deliver(
+  routine: Routine,
+  content: string,
+  status: "ok" | "error",
+  ctx: DeliveryContext = {},
+): DeliveryReport {
+  const delivered: string[] = [];
+  const wants = new Set(routine.delivery);
+  let filePath: string | undefined;
+  let noticed = false;
+
+  const leaveNotice = () => {
+    if (noticed) return;
+    addNotice({ routine: routine.name, at: new Date().toISOString(), status, preview: previewOf(content), path: filePath });
+    noticed = true;
+  };
+
+  // On-box copy.
+  if (wants.has("file")) {
+    filePath = writeRoutineOutput(routine.name, content);
+    delivered.push("file");
+  }
+
+  // Relay: pushed live to an attached controller, or queued to flush when the app
+  // next attaches (the daemon persists that queue, so it's durable either way). Only
+  // when no pusher is wired at all do we fall back to a notice so it isn't lost.
+  if (wants.has("relay")) {
+    const status = ctx.pushRelay?.(routine, content);
+    if (status === "live") delivered.push("relay");
+    else if (status === "queued") delivered.push("relay(queued)");
+    else if (!wants.has("file") && !wants.has("notice")) {
+      leaveNotice();
+      delivered.push("notice(backstop)");
+    }
+  }
+
+  if (wants.has("notice")) {
+    leaveNotice();
+    delivered.push("notice");
+  }
+
+  return { delivered, filePath };
+}

package/src/routines/schema.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+// Where a routine's result is delivered after it runs. Everything except `email`
+// stays inside the user's trust boundary; `email` crosses it (hands plaintext to a
+// third-party mail provider via the Gmail MCP tool), so it is opt-in and labeled.
+export const DELIVERY_CHANNELS = ["file", "relay", "notice", "email"] as const;
+export type DeliveryChannel = (typeof DELIVERY_CHANNELS)[number];
+
+// A saved, unattended agent task. Persisted in routines.json and executed by the
+// daemon when its trigger comes due. A routine's trigger is EITHER recurring (a
+// cron expression) or one-off (`at`, a specific datetime) — exactly one is set.
+export const Routine = z
+  .object({
+    // Stable id ("r-" + mint time), used as the key for updates/removal.
+    id: z.string(),
+    // Human label, unique across routines; used by /routine and as the output dir.
+    name: z.string(),
+    // Recurring trigger: a standard 5-field cron expression, e.g. "0 8 * * *".
+    cron: z.string().optional(),
+    // One-off trigger: an ISO-8601 datetime, e.g. "2026-07-02T15:00:00". Fires once,
+    // then the routine disables itself.
+    at: z.string().optional(),
+    // The instruction handed to the agent each time the routine fires.
+    prompt: z.string(),
+    // Working directory the run executes in (file tools are confined here).
+    cwd: z.string(),
+    // Optional "provider:model" override; falls back to config.defaultModel.
+    model: z.string().optional(),
+    // Where to deliver the result. Defaults to on-box file output.
+    delivery: z.array(z.enum(DELIVERY_CHANNELS)).default(["file"]),
+    // Optional tool allow-subset. Unset → the safe read/web set (see daemon). Entries
+    // may be builtin names ("read") or MCP selectors — "<server>__<tool>" exact or
+    // "<server>__*" for a whole server (see routines/toolSelect.ts). Selected MCP
+    // tools run unattended under the auto-approve gate, so grant the minimum needed.
+    tools: z.array(z.string()).optional(),
+    // Paused routines stay in the file but never fire.
+    enabled: z.boolean().default(true),
+    // Bookkeeping, updated by the daemon after each run.
+    lastRun: z.string().optional(),
+    lastStatus: z.enum(["ok", "error"]).optional(),
+    lastError: z.string().optional(),
+    nextRun: z.string().optional(),
+  })
+  // Exactly one trigger: recurring (cron) or one-off (at).
+  .refine((r) => Boolean(r.cron) !== Boolean(r.at), {
+    message: "set exactly one of `cron` (recurring) or `at` (one-off)",
+    path: ["cron"],
+  });
+export type Routine = z.infer<typeof Routine>;
+
+// True when the routine repeats (cron) rather than firing once (at).
+export function isRecurring(r: Pick<Routine, "cron" | "at">): boolean {
+  return Boolean(r.cron);
+}
+
+// The on-disk shape of routines.json.
+export const RoutineFile = z.object({
+  routines: z.array(Routine).default([]),
+});
+export type RoutineFile = z.infer<typeof RoutineFile>;
+
+// A time-ordered routine id minted once at creation.
+export function newRoutineId(): string {
+  return `r-${Date.now()}`;
+}