@saadnvd1/agent-os 0.3.715 → 0.3.723

package/lib/export/summary.ts

@@ -0,0 +1,86 @@
+import { addHits, noHits } from "../share/redact";
+import type { Counts, ExportDoc, ExportTurn } from "./build";
+import { inRange, resolveRange } from "./turns";
+import {
+  maskedList,
+  type ExportMode,
+  type ExportRange,
+  type ExportRedact,
+  type Hits,
+} from "./view";
+
+export interface Selected {
+  doc: ExportDoc;
+  turns: ExportTurn[];
+  sel: { from: number; to: number; of: number };
+  hits: Hits;
+  omissions: Counts;
+  truncations: Counts;
+}
+
+export interface ExportInfo {
+  mode: ExportMode;
+  redact: ExportRedact;
+  generatedAt: string;
+}
+
+const sum = (parts: Counts[]) => {
+  const out: Counts = {};
+  for (const p of parts)
+    for (const [k, v] of Object.entries(p)) out[k] = (out[k] ?? 0) + v;
+  return out;
+};
+
+/** The turns a range means, with the counts for just those. */
+export function selectTurns(doc: ExportDoc, range?: ExportRange): Selected {
+  const sel = resolveRange(doc.turns, range);
+  const turns = doc.turns.filter((t) => inRange(t.n, sel));
+  return {
+    doc,
+    turns,
+    sel,
+    hits: turns.reduce((h, t) => addHits(h, t.hits), doc.metaHits),
+    omissions: sum(turns.map((t) => t.omitted)),
+    truncations: sum(turns.map((t) => t.truncated)),
+  };
+}
+
+const plural = (n: number, what: string) => `${n} ${what}${n === 1 ? "" : "s"}`;
+
+export const countList = (c: Counts) =>
+  Object.entries(c)
+    .filter(([, n]) => n > 0)
+    .map(([what, n]) => plural(n, what))
+    .join(", ");
+
+const NOTHING = noHits();
+export { NOTHING };
+
+/** The lines every format prints under "Export notes". */
+export function exportNotes(s: Selected, info: ExportInfo) {
+  const { from, to, of } = s.sel;
+  const n = s.turns.filter((t) => t.n > 0).length;
+  const first = s.turns[0]?.startedAt.slice(0, 16).replace("T", " ");
+  const last = s.turns[s.turns.length - 1]?.endedAt
+    .slice(0, 16)
+    .replace("T", " ");
+  const whole = from <= 1 && to >= of;
+  const range = whole
+    ? `Whole session, ${plural(of, "turn")}${first ? `, ${first} to ${last}` : ""}`
+    : `Turns ${from}–${to} of ${of} (${plural(n, "turn")}), ${first} to ${last}`;
+  const masked = maskedList(s.hits);
+  return {
+    range,
+    detail:
+      info.mode === "compact"
+        ? "Compact: thinking dropped; tool output cut to its first 10 and last 20 lines; file changes reduced to counts"
+        : "Full: nothing dropped except what the notes below list",
+    redaction:
+      (info.redact === "all"
+        ? "Credentials, home paths, addresses, machine names and emails are masked"
+        : "Credentials are masked; paths, machine names and emails are included") +
+      (masked ? `. Masked: ${masked}` : ""),
+    omitted: countList(s.omissions) || "nothing",
+    truncated: countList(s.truncations) || "nothing",
+  };
+}

package/lib/export/turns.ts

@@ -0,0 +1,63 @@
+import type { ChatItem } from "../chat/events";
+import { BadShare } from "../share/service";
+import type { ExportRange } from "./view";
+
+export interface Turn {
+  /** 1-based; 0 is whatever came before the first message. */
+  n: number;
+  items: ChatItem[];
+}
+
+/**
+ * Items (already `visible()`, in stored order) as turns. A turn is a user
+ * message and everything until the next one; a message sent while the agent
+ * was working stays inside the turn it landed in.
+ */
+export function groupTurns(items: ChatItem[]): Turn[] {
+  const turns: Turn[] = [];
+  let n = 0;
+  for (const item of items) {
+    const starts = item.kind === "user" && !item.midTurn;
+    if (starts) {
+      n++;
+      turns.push({ n, items: [] });
+    } else if (turns.length === 0) {
+      turns.push({ n: 0, items: [] });
+    }
+    turns[turns.length - 1].items.push(item);
+  }
+  return turns;
+}
+
+type Numbered = { n: number; items: { kind: string }[] };
+
+export const turnCount = (turns: Numbered[]) =>
+  turns.filter((t) => t.n > 0).length;
+
+/** The inclusive turn numbers a range means, within 1..of. Throws BadShare. */
+export function resolveRange(
+  turns: Numbered[],
+  range: ExportRange | undefined
+): { from: number; to: number; of: number } {
+  const of = turnCount(turns);
+  if (!range || of === 0) return { from: 1, to: Math.max(of, 1), of };
+  if ("last" in range) {
+    const k = Math.max(1, Math.min(of, Math.floor(range.last)));
+    return { from: of - k + 1, to: of, of };
+  }
+  if ("sinceCompaction" in range) {
+    let at = 0;
+    for (const t of turns)
+      if (t.items.some((i) => i.kind === "compacted")) at = Math.max(t.n, 1);
+    return { from: at || 1, to: of, of };
+  }
+  const { from, to } = range;
+  if (from < 1 || from > of)
+    throw new BadShare(`range starts at turn ${from}, there are ${of}`, 400);
+  if (to < from) throw new BadShare("range ends before it starts", 400);
+  return { from, to: Math.min(to, of), of };
+}
+
+/** Turn 0 (the start) rides along with a range that begins at turn 1. */
+export const inRange = (n: number, sel: { from: number; to: number }) =>
+  n === 0 ? sel.from <= 1 : n >= sel.from && n <= sel.to;

package/lib/export/view.ts

@@ -0,0 +1,173 @@
+// Wire types and helpers for session export. Imports nothing outside itself
+// (bar the share helpers it reuses) so the sheet and the native app can use it.
+
+import { fileName, formatBytes } from "../share/view";
+
+export { formatBytes };
+
+export type ExportFormat = "md" | "json" | "html";
+export type ExportMode = "full" | "compact";
+/** "all": mask paths, hosts and emails too. "secrets": credentials only. */
+export type ExportRedact = "all" | "secrets";
+
+export type ExportRange =
+  { from: number; to: number } | { last: number } | { sinceCompaction: true };
+
+export interface ExportRequest {
+  format: ExportFormat;
+  mode: ExportMode;
+  range?: ExportRange;
+  redact: ExportRedact;
+}
+
+export const DEFAULT_REQUEST: ExportRequest = {
+  format: "md",
+  mode: "compact",
+  redact: "all",
+};
+
+export const EXPORT_FORMATS: {
+  id: ExportFormat;
+  label: string;
+  hint: string;
+  ext: string;
+  mime: string;
+}[] = [
+  {
+    id: "md",
+    label: "Markdown",
+    hint: "Best for pasting into a chat",
+    ext: "md",
+    mime: "text/markdown; charset=utf-8",
+  },
+  {
+    id: "json",
+    label: "JSON",
+    hint: "For scripts and tools",
+    ext: "json",
+    mime: "application/json",
+  },
+  {
+    id: "html",
+    label: "HTML",
+    hint: "To read or upload as a page",
+    ext: "html",
+    mime: "text/html; charset=utf-8",
+  },
+];
+
+export const formatInfo = (f: ExportFormat) =>
+  EXPORT_FORMATS.find((x) => x.id === f)!;
+
+export const MAX_EXPORT_BYTES = 25 * 1024 * 1024;
+export const WARN_TOKENS = 100_000;
+export const DANGER_TOKENS = 1_000_000;
+export const TOO_BIG =
+  "That export is over 25 MB. Narrow the range or use Compact.";
+
+export type Hits = Record<"secret" | "path" | "ip" | "host" | "email", number>;
+
+export interface ExportTurnInfo {
+  /** 0 is the part before the first message. */
+  n: number;
+  at: string;
+  /** The message that began the turn. */
+  id?: string;
+  excerpt: string;
+  items: number;
+  tokens: number;
+}
+
+export interface ExportWarning {
+  level: "info" | "warn" | "danger";
+  code:
+    | "sensitive"
+    | "paths-included"
+    | "full-output"
+    | "secrets-found"
+    | "large"
+    | "huge"
+    | "too-big";
+  text: string;
+}
+
+export interface Size {
+  bytes: number;
+  tokens: number;
+}
+
+export interface ExportEstimate {
+  title: string;
+  turns: ExportTurnInfo[];
+  selected: {
+    from: number;
+    to: number;
+    of: number;
+    turns: number;
+    startedAt: string | null;
+    endedAt: string | null;
+  };
+  /** The chosen format, in each mode. */
+  estimate: { full: Size; compact: Size };
+  hits: Hits;
+  omissions: Record<string, number>;
+  truncations: Record<string, number>;
+  warnings: ExportWarning[];
+  tooBig: boolean;
+}
+
+/** "all", "turn-12", "turns-12-18" for a file name. */
+export function rangeSlug(sel: { from: number; to: number; of: number }) {
+  if (sel.from <= 1 && sel.to >= sel.of) return "all";
+  return sel.from === sel.to
+    ? `turn-${sel.from}`
+    : `turns-${sel.from}-${sel.to}`;
+}
+
+export function exportFileName(
+  title: string,
+  slug: string,
+  format: ExportFormat
+): string {
+  const ext = formatInfo(format).ext;
+  const base = fileName(title, "md").replace(/\.md$/, "");
+  return `${base}-${slug}.${ext}`;
+}
+
+/** "about 24k tokens" */
+export function tokenLabel(tokens: number): string {
+  if (tokens < 1000) return `about ${tokens} tokens`;
+  if (tokens < 1_000_000) return `about ${Math.round(tokens / 1000)}k tokens`;
+  return `about ${(tokens / 1_000_000).toFixed(1)}M tokens`;
+}
+
+const KINDS: Record<keyof Hits, [string, string]> = {
+  secret: ["credential", "credentials"],
+  path: ["home path", "home paths"],
+  ip: ["address", "addresses"],
+  host: ["machine name", "machine names"],
+  email: ["email", "emails"],
+};
+
+/** "3 credentials, 88 home paths", or "" when nothing was masked. */
+export function maskedList(hits: Hits): string {
+  return (Object.keys(KINDS) as (keyof Hits)[])
+    .filter((k) => hits[k] > 0)
+    .map((k) => `${hits[k]} ${KINDS[k][hits[k] === 1 ? 0 : 1]}`)
+    .join(", ");
+}
+
+export function redactionStatus(hits: Hits): string {
+  const list = maskedList(hits);
+  return list ? `Masked ${list}` : "Nothing needed masking";
+}
+
+export const COMPACT_RULES = [
+  "Thinking blocks are dropped (counted).",
+  "Tool and command output keeps the first 10 and last 20 lines, 2,000 characters at most.",
+  "Tool input is clipped to 300 characters; a shell command to 1,000.",
+  "File changes become the path and +added −removed.",
+  "Only the last to-do list of each turn is kept.",
+  "Pages the agent showed keep their title only.",
+  "A pasted block over 8,000 characters keeps its start and end.",
+];

package/lib/models/agent-binding.ts

@@ -0,0 +1,102 @@
+/**
+ * Starting a session in an agent role: which model its binding gives it,
+ * whether that model's server answers, and what to run it on. A local model
+ * that's down never turns into a cloud one by itself: only a fallback the
+ * user set for the role, and only when the start asks for it.
+ */
+
+import { AGENT_ROLE_DEFS, type AgentRole } from "./agent-roles";
+import { modelAvailability, choiceFor } from "./catalog";
+import { savedModelSettings } from "./config";
+import { PI } from "./providers";
+import { resolveRole, type RoleSource, type RoutedModel } from "./resolve";
+
+export interface RoleBinding {
+  role: AgentRole;
+  routed: RoutedModel;
+  // The user's fallback for the role, if set.
+  fallback?: string;
+}
+
+export function bindingFor(
+  role: AgentRole,
+  opts: {
+    workspaceId?: string | null;
+    projectId?: string | null;
+    // The model picked for this one session.
+    override?: string | null;
+  } = {}
+): RoleBinding {
+  const modelRole = AGENT_ROLE_DEFS[role].modelRole;
+  const routed = resolveRole(modelRole, { ...opts, allowPi: true });
+  return {
+    role,
+    routed,
+    fallback: savedModelSettings().fallbacks?.[modelRole],
+  };
+}
+
+export class ModelUnavailableError extends Error {
+  readonly code = "model_unavailable";
+  constructor(
+    readonly role: AgentRole,
+    readonly ref: string,
+    readonly detail: string,
+    readonly fallback?: string
+  ) {
+    super(
+      `${AGENT_ROLE_DEFS[role].label}'s model ${ref} isn't answering${detail ? ` (${detail})` : ""}`
+    );
+  }
+}
+
+export interface RoleStart {
+  role: AgentRole;
+  routed: RoutedModel;
+  // "pi" runs the Pi agent on the model; "claude" runs Claude Code.
+  agentType: "claude" | "pi";
+  // What the agent CLI is given as its model.
+  model: string;
+  source: RoleSource | "fallback";
+}
+
+const startFrom = (
+  role: AgentRole,
+  routed: RoutedModel,
+  source: RoleStart["source"]
+): RoleStart =>
+  routed.provider.id === PI
+    ? {
+        role,
+        routed,
+        agentType: "pi",
+        model: routed.ref.slice(PI.length + 1),
+        source,
+      }
+    : { role, routed, agentType: "claude", model: routed.model, source };
+
+// The model a session started in `role` runs on, after checking its server.
+export async function prepareRoleStart(
+  role: AgentRole,
+  opts: Parameters<typeof bindingFor>[1] & { useFallback?: boolean }
+): Promise<RoleStart> {
+  const binding = bindingFor(role, opts);
+  const state = await modelAvailability(binding.routed.ref);
+  if (state.state !== "down")
+    return startFrom(role, binding.routed, binding.routed.source);
+  if (opts.useFallback && binding.fallback) {
+    const alt = bindingFor(role, { ...opts, override: binding.fallback });
+    const altState = await modelAvailability(alt.routed.ref);
+    if (altState.state !== "down")
+      return startFrom(role, alt.routed, "fallback");
+  }
+  throw new ModelUnavailableError(
+    role,
+    binding.routed.ref,
+    state.error ?? "",
+    binding.fallback &&
+      choiceFor(binding.fallback)?.availability.state !== "down"
+      ? binding.fallback
+      : undefined
+  );
+}

package/lib/models/agent-roles-view.ts

@@ -0,0 +1,157 @@
+/**
+ * What the Agent roles screen and the native app show: each role, the model
+ * saved at a scope, the model in force there and where it came from, and
+ * what the server knows of that model (local or cloud, answering or not).
+ * Saving checks what a role may run on.
+ */
+
+import {
+  AGENT_ROLES,
+  AGENT_ROLE_DEFS,
+  INTERNAL_MODEL_ROLES,
+  type AgentRole,
+} from "./agent-roles";
+import { choiceFor, type ModelChoice } from "./catalog";
+import {
+  effectiveModels,
+  projectModels,
+  savedModelSettings,
+  setModelSettings,
+  setProjectModels,
+  setWorkspaceModels,
+  workspaceModels,
+  type RoleMap,
+} from "./config";
+import { PI } from "./providers";
+import { resolveRole, type RoleSource } from "./resolve";
+import {
+  DEFAULT_ROLE_MODELS,
+  GATE_ROLES,
+  MODEL_ROLES,
+  ROLE_LABELS,
+  parseModelRef,
+  type ModelRole,
+} from "./roles";
+
+export type RoleScope = "settings" | "workspace" | "project";
+export interface ScopeRef {
+  scope: RoleScope;
+  id?: string | null;
+}
+
+export interface RoleView {
+  modelRole: ModelRole;
+  label: string;
+  hint: string;
+  // Saved at this scope, or null when it inherits.
+  value: string | null;
+  binding: { ref: string; source: RoleSource } | null;
+  fallback: string | null;
+  choice: ModelChoice | null;
+  // Why the binding can't be used (a provider turned off).
+  error?: string;
+  default: string;
+}
+
+export interface AgentRoleView extends RoleView {
+  id: AgentRole;
+  purpose: string;
+  brief: string;
+  edits: boolean;
+}
+
+function savedAt({ scope, id }: ScopeRef): RoleMap {
+  if (scope === "workspace" && id) return workspaceModels(id).roles ?? {};
+  if (scope === "project" && id) return projectModels(id).roles ?? {};
+  return savedModelSettings().roles ?? {};
+}
+
+function viewOf(modelRole: ModelRole, at: ScopeRef, ctx: ContextIds): RoleView {
+  const effective = effectiveModels();
+  let binding: RoleView["binding"] = null;
+  let error: string | undefined;
+  try {
+    const r = resolveRole(modelRole, { ...ctx, allowPi: true }, effective);
+    binding = { ref: r.ref, source: r.source };
+  } catch (e) {
+    error = e instanceof Error ? e.message : String(e);
+  }
+  return {
+    modelRole,
+    label: ROLE_LABELS[modelRole].label,
+    hint: ROLE_LABELS[modelRole].hint,
+    value: savedAt(at)[modelRole] ?? null,
+    binding,
+    fallback: savedModelSettings().fallbacks?.[modelRole] ?? null,
+    choice: binding ? (choiceFor(binding.ref, effective) ?? null) : null,
+    ...(error ? { error } : {}),
+    default: DEFAULT_ROLE_MODELS[modelRole],
+  };
+}
+
+interface ContextIds {
+  workspaceId?: string | null;
+  projectId?: string | null;
+}
+
+const contextOf = ({ scope, id }: ScopeRef): ContextIds =>
+  scope === "workspace"
+    ? { workspaceId: id }
+    : scope === "project"
+      ? { projectId: id }
+      : {};
+
+export function agentRolesView(at: ScopeRef, ctx?: ContextIds) {
+  const ids = ctx ?? contextOf(at);
+  return {
+    roles: AGENT_ROLES.map((id): AgentRoleView => ({
+      ...viewOf(AGENT_ROLE_DEFS[id].modelRole, at, ids),
+      id,
+      label: AGENT_ROLE_DEFS[id].label,
+      hint: AGENT_ROLE_DEFS[id].purpose,
+      purpose: AGENT_ROLE_DEFS[id].purpose,
+      brief: AGENT_ROLE_DEFS[id].brief,
+      edits: AGENT_ROLE_DEFS[id].edits,
+    })),
+    internal: INTERNAL_MODEL_ROLES(MODEL_ROLES).map((r) => viewOf(r, at, ids)),
+  };
+}
+
+// The models a role can be bound to: a Pi model runs a role session only,
+// never a task, a gate or the orchestrator.
+const PI_ROLES: readonly ModelRole[] = ["implement", "analyze", "advise"];
+
+function checkRoles(roles: RoleMap): void {
+  for (const [role, ref] of Object.entries(roles) as [ModelRole, string][]) {
+    if (parseModelRef(ref).provider !== PI) continue;
+    if (!PI_ROLES.includes(role))
+      throw new Error(
+        `${ROLE_LABELS[role].label} can't run on a Pi model (${GATE_ROLES.includes(role) ? "a merge gate needs Claude Code" : "only the Developer, Analyst and Reviewer can"})`
+      );
+  }
+}
+
+export function saveAgentRoles(
+  at: ScopeRef,
+  roles: RoleMap,
+  fallbacks?: RoleMap
+): void {
+  checkRoles(roles);
+  if (fallbacks) {
+    for (const ref of Object.values(fallbacks))
+      if (ref && parseModelRef(ref).provider === PI)
+        throw new Error("A fallback must be a cloud or Claude Code model");
+  }
+  if (at.scope === "settings") {
+    const saved = savedModelSettings();
+    setModelSettings({
+      ...saved,
+      roles,
+      ...(fallbacks ? { fallbacks } : {}),
+    });
+    return;
+  }
+  if (!at.id) throw new Error(`${at.scope} needs an id`);
+  if (at.scope === "workspace") setWorkspaceModels(at.id, { roles });
+  else setProjectModels(at.id, { roles });
+}

package/lib/models/agent-roles.ts

@@ -0,0 +1,87 @@
+/**
+ * The roles a person assigns models to: Developer, Analyst, Reviewer and
+ * Supervisor. Each binds one of the model roles in ./roles, so there is one
+ * routing system: Developer is `implement`, Supervisor is `orchestrator`,
+ * and Analyst and Reviewer have a model role of their own. Imported by the
+ * browser too, so no Node modules here.
+ */
+
+import type { ModelRole } from "./roles";
+
+export const AGENT_ROLES = [
+  "developer",
+  "analyst",
+  "reviewer",
+  "supervisor",
+] as const;
+
+export type AgentRole = (typeof AGENT_ROLES)[number];
+
+export interface AgentRoleDef {
+  id: AgentRole;
+  label: string;
+  // The one line shown beside its model.
+  purpose: string;
+  modelRole: ModelRole;
+  // Appended to the instructions of a session started in the role.
+  brief: string;
+  // Whether it may change files.
+  edits: boolean;
+}
+
+export const AGENT_ROLE_DEFS: Record<AgentRole, AgentRoleDef> = {
+  developer: {
+    id: "developer",
+    label: "Developer",
+    purpose: "Writes the code: tasks, and sessions started as Developer",
+    modelRole: "implement",
+    edits: true,
+    brief:
+      "You are the Developer in this crew. You write and change the code. When your work is ready, tell the Reviewer with `aos send @reviewer`; answer the Analyst's questions with `aos send @analyst`.",
+  },
+  analyst: {
+    id: "analyst",
+    label: "Analyst",
+    purpose:
+      "Reads code, logs and the Developer's work; explains and proposes; doesn't commit",
+    modelRole: "analyze",
+    edits: false,
+    brief:
+      "You are the Analyst in this crew. You read code, logs and data, and the Developer's transcript (`aos read @developer`), then explain what you find and propose changes. You don't edit files, commit or open pull requests; send proposals to the Developer with `aos send @developer`.",
+  },
+  reviewer: {
+    id: "reviewer",
+    label: "Reviewer",
+    purpose:
+      "Reviews another role's diff and suggests improvements. Advice only: not the merge gate",
+    modelRole: "advise",
+    edits: false,
+    brief:
+      "You are the Reviewer in this crew. Read the Developer's diff (`git diff` in its worktree, `aos read @developer`) and send concrete suggestions with `aos send @developer`. You don't edit files or open pull requests. Your review is advice; the merge gate is separate.",
+  },
+  supervisor: {
+    id: "supervisor",
+    label: "Supervisor",
+    purpose:
+      "Watches a crew, sequences work, unblocks and reports. The workspace orchestrator",
+    modelRole: "orchestrator",
+    edits: false,
+    brief:
+      "You are the Supervisor in this crew. Watch the other roles (`aos peers`, `aos read @developer`), unblock them, sequence the work and report to the user. You don't write the code yourself.",
+  },
+};
+
+export const isAgentRole = (v: unknown): v is AgentRole =>
+  typeof v === "string" && (AGENT_ROLES as readonly string[]).includes(v);
+
+export const agentRoleOf = (modelRole: ModelRole): AgentRole | undefined =>
+  AGENT_ROLES.find((r) => AGENT_ROLE_DEFS[r].modelRole === modelRole);
+
+// The model roles under the four above, shown as "internal" roles.
+export const INTERNAL_MODEL_ROLES = (all: readonly ModelRole[]) =>
+  all.filter((r) => !agentRoleOf(r));
+
+// A session's brief for its role, or "" with none.
+export function roleBrief(role: string | null | undefined): string {
+  return isAgentRole(role) ? AGENT_ROLE_DEFS[role].brief : "";
+}

package/lib/models/availability-refs.ts

@@ -0,0 +1,17 @@
+import { modelCatalog } from "./catalog";
+import { modelAvailability as probeRef } from "./catalog";
+import type { Availability } from "./availability";
+
+// Every local model's availability by ref, probing the stale or all of them.
+export async function modelAvailability(
+  refresh = false
+): Promise<Record<string, Availability>> {
+  const local = modelCatalog().filter((c) => c.locality === "local");
+  const out: Record<string, Availability> = {};
+  await Promise.all(
+    local.map(async (c) => {
+      out[c.ref] = await probeRef(c.ref, undefined, refresh);
+    })
+  );
+  return out;
+}