privateer-agent 0.1.1 → 0.3.0

package/src/providers/genModelsJson.ts

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { agentDir } from "../config/paths.ts";
+import { providersToGenerate, type ProviderEntry } from "./catalog.ts";
+
+// Emit models.json entries for the config-only providers Pi doesn't ship and
+// pi-privacy doesn't register (today: just `qwen`). Built-ins come from pi-ai's
+// static catalogs; privacy providers from the pi-privacy extension; the privateer
+// account channel from code. See catalog.ts for the full accounting.
+//
+// Model metadata defaults follow the migration plan Appendix A.4 (used until a live
+// listing refines them): contextWindow 128000, maxTokens 16384, zero cost, text-only.
+
+export interface ModelsJsonModel {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ("text" | "image")[];
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  contextWindow: number;
+  maxTokens: number;
+  compat?: Record<string, unknown>;
+}
+
+export interface ModelsJsonProvider {
+  name: string;
+  baseUrl: string;
+  api: string;
+  apiKey?: string;
+  authHeader?: boolean;
+  compat?: Record<string, unknown>;
+  models: ModelsJsonModel[];
+}
+
+export interface ModelsJson {
+  providers: Record<string, ModelsJsonProvider>;
+}
+
+function seedModel(id: string, compat?: Record<string, unknown>): ModelsJsonModel {
+  return {
+    id,
+    name: id,
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    ...(compat ? { compat } : {}),
+  };
+}
+
+function providerConfig(p: ProviderEntry): ModelsJsonProvider {
+  return {
+    name: p.id,
+    baseUrl: p.baseUrl!,
+    api: p.api ?? "openai-completions",
+    // Env-template key (Pi resolves ${...}; auth.json takes precedence when present).
+    // Never a literal key — and never emitted for the account/venice providers.
+    ...(p.keyEnv ? { apiKey: p.keyEnv, authHeader: true } : {}),
+    ...(p.compat ? { compat: p.compat } : {}),
+    models: (p.seedModels ?? []).map((id) => seedModel(id, p.compat)),
+  };
+}
+
+// Build the models.json object for all `generate`-sourced providers.
+export function generateModelsJson(providers: ProviderEntry[] = providersToGenerate()): ModelsJson {
+  const out: ModelsJson = { providers: {} };
+  for (const p of providers) {
+    if (p.source !== "generate" || !p.baseUrl) continue;
+    out.providers[p.id] = providerConfig(p);
+  }
+  return out;
+}
+
+// Merge generated providers into an existing models.json WITHOUT clobbering
+// user-added or extension-registered providers. Generated ids are refreshed; every
+// other provider in the file is preserved. Writes to $PRIVATEER_HOME/agent/models.json
+// by default. Returns the merged object.
+export function writeModelsJson(
+  generated: ModelsJson = generateModelsJson(),
+  path: string = join(agentDir(), "models.json"),
+): ModelsJson {
+  let existing: ModelsJson = { providers: {} };
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (parsed && typeof parsed === "object" && parsed.providers) existing = parsed;
+    } catch {
+      // Unreadable/corrupt file → treat as empty rather than throwing; we only add
+      // our generated providers and never drop the user's.
+    }
+  }
+  const merged: ModelsJson = { providers: { ...existing.providers, ...generated.providers } };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  return merged;
+}

package/src/remote/relayClient.ts

@@ -54,8 +54,17 @@ 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;
+  // The app toggled no-quarter (unattended) mode: remote turns auto-approve like
+  // bypass mode instead of relaying every action, so the agent runs to completion.
+  // Dangerous/destructive actions still relay — they sit above bypass locally too.
+  onNoQuarter?: (on: boolean) => 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
@@ -63,6 +72,8 @@ export interface RelayCallbacks {
   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;
@@ -71,6 +82,9 @@ const RECONNECT_MS = 3000;
 // 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;
 
@@ -125,9 +139,12 @@ 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<
@@ -135,7 +152,13 @@ export class RelayClient {
     { 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;
@@ -182,6 +205,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
@@ -230,6 +254,7 @@ export class RelayClient {
       size?: number;
       seq?: number;
       data?: string;
+      on?: boolean;
     };
     try {
       frame = JSON.parse(data.toString());
@@ -247,9 +272,15 @@ export class RelayClient {
       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 "no_quarter":
+        this.cb.onNoQuarter?.(frame.on === true);
+        break;
       case "controller_attached":
         this.cb.onControllerAttached();
         break;
@@ -320,6 +351,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);
@@ -335,6 +383,45 @@ 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 };
+  }
+
+  // Echo the no-quarter (unattended auto-approve) state up to the controller so
+  // its toggle reflects what this terminal is actually doing. Sent on every
+  // change (ack) and on controller attach (a re-attaching app resyncs).
+  sendNoQuarter(on: boolean): void {
+    this.rawSend({ type: "no_quarter", on });
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",

package/src/remote/remoteBridge.ts

@@ -0,0 +1,152 @@
+// The wiring between the relay and the rest of the agent — NEW code for the Pi
+// rewrite. It connects three things that were built to meet here:
+//   - the Phase-1 adapter's EngineEvents  → up to the app (relay.sendEvent)
+//   - the Phase-2 gate's remote branch    → each tool relayed to the app for
+//     allow/deny via `remoteAsk` + `getRemote` (the slots makePermissionGate stubbed)
+//   - the app's prompts/interrupts        → down into the turn loop (cfg callbacks)
+//
+// The RelayClient itself is KEEP (verbatim 0.2); this bridge is the only new part,
+// so it's what the tests exercise (against a fake relay). Fail-closed throughout:
+// no controller, a disconnect, or an aborted turn all resolve a pending approval
+// to "deny".
+
+import { randomUUID } from "node:crypto";
+import type { EngineEvent } from "../engine/events.ts";
+import type { PermissionRequest } from "../permissions/gate.ts";
+import type { AskOutcome } from "../permissions/modeGate.ts";
+import type { RelayCallbacks } from "./relayClient.ts";
+
+// The outbound surface the bridge needs; RelayClient implements all of it.
+export interface RelayLike {
+  requestApproval(id: string, req: PermissionRequest): void;
+  sendEvent(ev: EngineEvent): void;
+  isConnected(): boolean;
+  sendNoQuarter(on: boolean): void;
+  sendFile(file: { name: string; mediaType: string; base64: string; size: number }): Promise<{ ok: boolean; reason?: string }>;
+}
+
+export interface RemoteAttachment {
+  name: string;
+  mediaType: string;
+  base64: string;
+}
+
+export interface RemoteBridgeConfig {
+  // A prompt arrived from the app — drive the turn loop (tagged remote). Any files
+  // the app sent ahead of the prompt ride along.
+  onPrompt: (text: string, attachments: RemoteAttachment[]) => void;
+  onInterrupt?: () => void;
+  onTerminate?: () => void;
+  // A controller (re)attached — the owner should push a transcript snapshot.
+  onControllerAttached?: () => void;
+  onStatus?: (text: string) => void;
+  // A file finished transferring down from the app. The owner registers it (e.g. into
+  // an AttachmentStore) so the save_attachment tool can persist it.
+  onAttachment?: (file: RemoteAttachment) => void;
+}
+
+export class RemoteBridge {
+  private relay?: RelayLike;
+  private remote = false;
+  private noQuarter = false;
+  private readonly pending = new Map<string, (d: AskOutcome) => void>();
+  private pendingAttachments: RemoteAttachment[] = [];
+
+  constructor(private readonly cfg: RemoteBridgeConfig) {}
+
+  // Wire the outbound relay once it's constructed (RelayClient needs `callbacks`
+  // at construction, so the relay is attached right after).
+  attachRelay(relay: RelayLike): void {
+    this.relay = relay;
+  }
+
+  // Hand this to `new RelayClient(bridge.callbacks)`. Typed Required so every hook
+  // (including the ones RelayCallbacks marks optional) is defined — the bridge wires
+  // them all.
+  readonly callbacks: Required<RelayCallbacks> = {
+    onPrompt: (text) => {
+      this.remote = true; // a remote turn is now in flight → gate relays each action
+      const attachments = this.pendingAttachments;
+      this.pendingAttachments = [];
+      this.cfg.onPrompt(text, attachments);
+    },
+    onInterrupt: () => this.cfg.onInterrupt?.(),
+    onTerminate: () => this.cfg.onTerminate?.(),
+    onApprovalResponse: (id, decision) => {
+      const resolve = this.pending.get(id);
+      if (resolve) resolve(decision);
+    },
+    onNoQuarter: (on) => {
+      this.noQuarter = on;
+      this.relay?.sendNoQuarter(on); // echo the ack back so the app's toggle syncs
+    },
+    onControllerAttached: () => this.cfg.onControllerAttached?.(),
+    onAttachment: (file) => {
+      this.pendingAttachments.push(file);
+      this.cfg.onAttachment?.(file);
+    },
+    onStatus: (text) => this.cfg.onStatus?.(text),
+    onDisconnected: () => {
+      this.remote = false;
+      // Any approval waiting on a now-gone controller fails closed.
+      this.rejectAllPending();
+    },
+  };
+
+  // ── gate hooks (passed into the GateController) ─────────────────────────────
+
+  getRemote = (): boolean => this.remote;
+  getNoQuarter = (): boolean => this.noQuarter;
+
+  // The gate's remote approver: relay the request to the app and await its
+  // allow/deny. Fail closed if no controller, on abort, or on disconnect. (The gate
+  // also wraps this in its own timeout, so a silent app can't wedge the turn.)
+  remoteAsk = (req: PermissionRequest, signal?: AbortSignal): Promise<AskOutcome> => {
+    if (!this.relay || !this.relay.isConnected()) return Promise.resolve("deny");
+    const id = randomUUID();
+    return new Promise<AskOutcome>((resolve) => {
+      const onAbort = () => settle("deny");
+      const settle = (d: AskOutcome) => {
+        this.pending.delete(id);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(d);
+      };
+      this.pending.set(id, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      this.relay!.requestApproval(id, req);
+    });
+  };
+
+  // ── turn lifecycle + event forwarding ───────────────────────────────────────
+
+  // Mark the end of a turn so the next (possibly local) turn isn't treated as
+  // remote. Call after each driven turn completes.
+  settleTurn(): void {
+    this.remote = false;
+  }
+
+  // Forward an EngineEvent up to the app. Safe to call for every event of every
+  // turn (local included) — the relay only sends when a socket is open.
+  forwardEvent(ev: EngineEvent): void {
+    this.relay?.sendEvent(ev);
+  }
+
+  // Is a controller actually reachable right now? (Relay socket open.)
+  isConnected(): boolean {
+    return !!this.relay?.isConnected();
+  }
+
+  // Stream a file up to the connected app (the send_file_to_client tool).
+  async sendFile(file: { name: string; mediaType: string; base64: string; size: number }): Promise<{ ok: boolean; reason?: string }> {
+    if (!this.relay) return { ok: false, reason: "remote access is not enabled" };
+    return this.relay.sendFile(file);
+  }
+
+  private rejectAllPending(): void {
+    for (const resolve of this.pending.values()) resolve("deny");
+    this.pending.clear();
+  }
+}

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;
+}