@saadnvd1/agent-os 0.3.700 → 0.3.723

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

package/lib/models/availability.ts

@@ -0,0 +1,91 @@
+/**
+ * Whether a model's server answers. Only endpoints on the local networks
+ * are probed (a cloud provider's key isn't proof and a probe costs), one
+ * short GET, cached for a while. Any HTTP answer means the server is up;
+ * what's down is a refused connection or no answer in time.
+ */
+
+export type AvailabilityState = "up" | "down" | "unknown";
+
+export interface Availability {
+  state: AvailabilityState;
+  checkedAt: string | null;
+  error?: string;
+}
+
+const TTL_MS = 30_000;
+const TIMEOUT_MS = 1_500;
+
+interface Entry extends Availability {
+  at: number;
+}
+const cache = new Map<string, Entry>();
+const probing = new Map<string, Promise<Entry>>();
+
+const UNKNOWN: Availability = { state: "unknown", checkedAt: null };
+
+// What a server of that API lists its models at.
+export const probeUrl = (baseUrl: string, api: "anthropic" | "openai") => {
+  const base = baseUrl.replace(/\/+$/, "");
+  return api === "anthropic" && !/\/v1$/.test(base)
+    ? `${base}/v1/models`
+    : `${base}/models`;
+};
+
+async function probe(url: string): Promise<Entry> {
+  const at = Date.now();
+  try {
+    await fetch(url, {
+      method: "GET",
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      redirect: "manual",
+    });
+    return { state: "up", checkedAt: new Date(at).toISOString(), at };
+  } catch (error) {
+    const cause = (error as { cause?: { code?: string } }).cause?.code;
+    const timedOut = (error as Error).name === "TimeoutError";
+    return {
+      state: "down",
+      checkedAt: new Date(at).toISOString(),
+      at,
+      error: timedOut
+        ? `no answer in ${TIMEOUT_MS / 1000}s`
+        : (cause ?? (error as Error).message),
+    };
+  }
+}
+
+const strip = ({ at: _at, ...rest }: Entry): Availability => rest;
+
+// The last check of a URL, probing in the background when it's stale: a
+// request handler never waits on a probe.
+export function cachedAvailability(url: string): Availability {
+  const hit = cache.get(url);
+  if (!hit || Date.now() - hit.at >= TTL_MS) void checkAvailability(url);
+  return hit ? strip(hit) : UNKNOWN;
+}
+
+// A fresh enough answer, waiting for the probe if there isn't one.
+export async function checkAvailability(
+  url: string,
+  refresh = false
+): Promise<Availability> {
+  const hit = cache.get(url);
+  if (!refresh && hit && Date.now() - hit.at < TTL_MS) return strip(hit);
+  let running = probing.get(url);
+  if (!running) {
+    running = probe(url)
+      .then((e) => {
+        cache.set(url, e);
+        return e;
+      })
+      .finally(() => probing.delete(url));
+    probing.set(url, running);
+  }
+  return strip(await running);
+}
+
+export function clearAvailability(): void {
+  cache.clear();
+  probing.clear();
+}

package/lib/models/catalog.ts

@@ -0,0 +1,156 @@
+/**
+ * The one list of models every picker shows, built on the server: each
+ * enabled provider's models, and the models Pi reaches (local servers in its
+ * models.json). Nothing about a model, provider or its locality is decided
+ * in the browser.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { effectiveModels, type EffectiveModels } from "./config";
+import { ANTHROPIC } from "./roles";
+import { PI, type ModelProvider } from "./providers";
+import { hostLocality, type Locality } from "./locality";
+import {
+  cachedAvailability,
+  checkAvailability,
+  probeUrl,
+  type Availability,
+} from "./availability";
+
+export interface ModelChoice {
+  // "anthropic/claude-opus-5-5", "pi/local/qwen3-27b"
+  ref: string;
+  label: string;
+  // The provider's name: "Anthropic", "DeepSeek", "Pi · local".
+  group: string;
+  // What runs it: Claude Code, or the Pi agent.
+  agent: "claude" | "pi";
+  locality: Locality;
+  availability: Availability;
+  // May serve a merge gate: Claude Code can run it.
+  gateCapable: boolean;
+  // Where the server is (never a key).
+  endpoint?: string;
+}
+
+interface PiProvider {
+  id: string;
+  baseUrl: string;
+  models: { id: string; name?: string }[];
+}
+
+const piModelsFile = () =>
+  process.env.AGENTOS_PI_MODELS_FILE ||
+  path.join(os.homedir(), ".pi", "agent", "models.json");
+
+// The providers in Pi's own config. A missing or unreadable file means Pi
+// has no servers of ours to list.
+export function piProviders(file = piModelsFile()): PiProvider[] {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+  const providers = (raw as { providers?: Record<string, unknown> })?.providers;
+  if (!providers || typeof providers !== "object") return [];
+  const out: PiProvider[] = [];
+  for (const [id, p] of Object.entries(providers)) {
+    const q = p as { baseUrl?: unknown; models?: unknown };
+    if (typeof q?.baseUrl !== "string" || !Array.isArray(q.models)) continue;
+    const models = q.models
+      .map((m) =>
+        typeof m === "string"
+          ? { id: m }
+          : {
+              id: (m as { id?: unknown })?.id,
+              name: (m as { name?: unknown })?.name,
+            }
+      )
+      .filter(
+        (m): m is { id: string; name?: string } => typeof m.id === "string"
+      )
+      .map((m) => ({
+        id: m.id,
+        ...(typeof m.name === "string" ? { name: m.name } : {}),
+      }));
+    out.push({ id, baseUrl: q.baseUrl, models });
+  }
+  return out;
+}
+
+const providerEndpoint = (p: ModelProvider) =>
+  p.baseUrl ? probeUrl(p.baseUrl, p.api) : undefined;
+
+export function modelCatalog(
+  effective: EffectiveModels = effectiveModels(),
+  pi: PiProvider[] = piProviders()
+): ModelChoice[] {
+  const out: ModelChoice[] = [];
+  for (const p of effective.providers.filter((x) => x.enabled)) {
+    const endpoint = providerEndpoint(p);
+    const locality = hostLocality(p.baseUrl);
+    const availability: Availability =
+      p.id === ANTHROPIC
+        ? { state: "up", checkedAt: null }
+        : locality === "local" && endpoint
+          ? cachedAvailability(endpoint)
+          : { state: "unknown", checkedAt: null };
+    for (const m of p.models)
+      out.push({
+        ref: `${p.id}/${m}`,
+        label: m,
+        group: p.label,
+        agent: "claude",
+        locality,
+        availability,
+        gateCapable: p.api === "anthropic",
+        endpoint: p.baseUrl,
+      });
+  }
+  for (const p of pi) {
+    const locality = hostLocality(p.baseUrl);
+    const endpoint = probeUrl(p.baseUrl, "openai");
+    const availability: Availability =
+      locality === "local"
+        ? cachedAvailability(endpoint)
+        : { state: "unknown", checkedAt: null };
+    for (const m of p.models)
+      out.push({
+        ref: `${PI}/${p.id}/${m.id}`,
+        label: m.name ?? m.id,
+        group: `Pi · ${p.id}`,
+        agent: "pi",
+        locality,
+        availability,
+        gateCapable: false,
+        endpoint: p.baseUrl,
+      });
+  }
+  return out;
+}
+
+export const choiceFor = (
+  ref: string,
+  effective?: EffectiveModels
+): ModelChoice | undefined =>
+  modelCatalog(effective).find((c) => c.ref === ref);
+
+// Whether the model's server answers now, waiting for a probe. Cloud and
+// unlisted models aren't probed: they count as available.
+export async function modelAvailability(
+  ref: string,
+  effective?: EffectiveModels,
+  refresh = false
+): Promise<Availability> {
+  const choice = choiceFor(ref, effective);
+  if (!choice || choice.locality !== "local" || !choice.endpoint)
+    return { state: "unknown", checkedAt: null };
+  const url =
+    choice.agent === "pi"
+      ? probeUrl(choice.endpoint, "openai")
+      : probeUrl(choice.endpoint, "anthropic");
+  return checkAvailability(url, refresh);
+}

package/lib/models/config.ts

@@ -138,25 +138,35 @@ const subagentMap = z
         });
   });
 
+// A role may name a model to start on when its own can't be reached.
+const fallbackMap = z.partialRecord(z.enum(MODEL_ROLES), roleRef);
+
 export const modelSettingsSchema = z.strictObject({
   roles: roleMap.optional(),
   subagents: subagentMap.optional(),
   providers: z.array(providerSchema).optional(),
   prices: z.record(z.string().regex(REF_PATTERN), price).optional(),
   planStep: z.boolean().optional(),
+  fallbacks: fallbackMap.optional(),
 });
 
 export const workspaceModelsSchema = z.strictObject({
   roles: roleMap.optional(),
 });
 
+export const projectModelsSchema = z.strictObject({
+  roles: roleMap.optional(),
+});
+
 export type ModelSettings = z.infer<typeof modelSettingsSchema>;
 export type WorkspaceModels = z.infer<typeof workspaceModelsSchema>;
+export type ProjectModels = z.infer<typeof projectModelsSchema>;
 export type RoleMap = Partial<Record<ModelRole, string>>;
 export const roleMapSchema = roleMap;
 
 const GLOBAL_KEY = "models";
 const workspaceKey = (id: string) => `models.workspace.${id}`;
+const projectKey = (id: string) => `models.project.${id}`;
 
 function read<T>(key: string, schema: z.ZodType<T>): T | null {
   const row = db
@@ -221,6 +231,23 @@ export function setWorkspaceModels(
   return saved;
 }
 
+// Set in Settings, never in the repo, so work can't choose its own models.
+export const projectModels = (projectId: string): ProjectModels =>
+  read(projectKey(projectId), projectModelsSchema) ?? {};
+
+export function setProjectModels(
+  projectId: string,
+  value: unknown
+): ProjectModels {
+  const saved = write(projectKey(projectId), projectModelsSchema, value);
+  if (!Object.keys(saved.roles ?? {}).length) clearProjectModels(projectId);
+  return saved;
+}
+
+export const clearProjectModels = (projectId: string): void => {
+  db.prepare(`DELETE FROM settings WHERE key = ?`).run(projectKey(projectId));
+};
+
 // The settings in force: the presets with any saved edits laid over them
 // (by id), saved providers that aren't presets, and every role filled.
 export interface EffectiveModels {

package/lib/models/locality.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether a model endpoint is on this machine's own networks (local) or
+ * out on the internet (cloud), read from its host, never from a name.
+ * Imported by the browser too.
+ */
+
+export type Locality = "local" | "cloud";
+
+const PRIVATE_V4 = [
+  /^127\./,
+  /^10\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^169\.254\./,
+  // The tailnet: 100.64.0.0/10.
+  /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+];
+
+export function hostLocality(url: string | null | undefined): Locality {
+  if (!url) return "cloud";
+  let host: string;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return "cloud";
+  }
+  host = host.replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host === "::1" || host.endsWith(".localhost"))
+    return "local";
+  if (host.endsWith(".local") || host.endsWith(".ts.net")) return "local";
+  if (/^f[cd][0-9a-f]{2}:/.test(host)) return "local";
+  return PRIVATE_V4.some((re) => re.test(host)) ? "local" : "cloud";
+}

package/lib/models/providers.ts

@@ -63,6 +63,17 @@ export const ANTHROPIC_PROVIDER: ModelProvider = {
   enabled: true,
 };
 
+// Pi's own models ("pi/<its provider>/<model>"): local servers Pi reaches,
+// run by the Pi agent rather than through Claude Code's endpoint variables.
+export const PI = "pi";
+export const PI_PROVIDER: ModelProvider = {
+  id: PI,
+  label: "Pi",
+  api: "openai",
+  models: [],
+  enabled: true,
+};
+
 // Checked against each provider's docs on 2026-10-11: DeepSeek
 // (api-docs.deepseek.com/guides/anthropic_api) and Z.ai
 // (docs.z.ai/devpack/tool/claude). Off until a key reference is set.

package/lib/models/resolve.ts

@@ -12,11 +12,17 @@ import {
   effectiveModels,
   roleMapSchema,
   savedModelSettings,
+  projectModels,
   workspaceModels,
   type EffectiveModels,
   type RoleMap,
 } from "./config";
-import { ANTHROPIC_PROVIDER, type ModelProvider } from "./providers";
+import {
+  ANTHROPIC_PROVIDER,
+  PI,
+  PI_PROVIDER,
+  type ModelProvider,
+} from "./providers";
 import {
   ANTHROPIC,
   DEFAULT_ROLE_MODELS,
@@ -33,7 +39,14 @@ import {
   type SecretCommand,
 } from "./secrets";
 
-export type RoleSource = "task" | "workspace" | "settings" | "env" | "default";
+export type RoleSource =
+  | "task"
+  | "project"
+  | "workspace"
+  | "settings"
+  | "env"
+  | "inherited"
+  | "default";
 
 // The server's own environment can still stand in for a role's default:
 // what AgentOS read before model routing existed.
@@ -87,9 +100,15 @@ const overrideFor = (o: ModelOverride | null | undefined, role: ModelRole) =>
 // The provider by id, or throws why it can't be used.
 export function providerFor(
   id: string,
-  models: EffectiveModels = effectiveModels()
+  models: EffectiveModels = effectiveModels(),
+  allowPi = false
 ): ModelProvider {
   if (id === ANTHROPIC) return ANTHROPIC_PROVIDER;
+  if (id === PI) {
+    if (!allowPi)
+      throw new Error("Pi models run only in a session started in a role");
+    return PI_PROVIDER;
+  }
   const p = models.providers.find((x) => x.id === id);
   if (!p) throw new Error(`No model provider "${id}" (Settings > Models)`);
   if (!p.enabled) throw new Error(`The ${p.label} provider is turned off`);
@@ -104,10 +123,19 @@ export function providerFor(
 
 export function resolveRole(
   role: ModelRole,
-  opts: { workspaceId?: string | null; override?: ModelOverride | null } = {},
+  opts: {
+    workspaceId?: string | null;
+    projectId?: string | null;
+    override?: ModelOverride | null;
+    // A role session runs Pi models; a task or gate can't.
+    allowPi?: boolean;
+  } = {},
   models: EffectiveModels = effectiveModels()
 ): RoutedModel {
   const task = overrideFor(opts.override, role);
+  const proj = opts.projectId
+    ? projectModels(opts.projectId).roles?.[role]
+    : undefined;
   const ws = opts.workspaceId
     ? workspaceModels(opts.workspaceId).roles?.[role]
     : undefined;
@@ -117,20 +145,30 @@ export function resolveRole(
     saved === DEFAULT_ROLE_MODELS[role] && !savedModelSettings().roles?.[role]
       ? envModel(role)
       : undefined;
+  // The reviewer's advice follows the gate's model until it's set.
+  const named = !!savedModelSettings().roles?.[role];
+  const inherited =
+    role === "advise" && !env && !named
+      ? resolveRole("review", { ...opts, override: null }, models)
+      : null;
   const [ref, source]: [string, RoleSource] = task
     ? [task, "task"]
-    : ws
-      ? [ws, "workspace"]
-      : saved !== DEFAULT_ROLE_MODELS[role]
-        ? [saved, "settings"]
-        : env
-          ? [env, "env"]
-          : [saved, "default"];
+    : proj
+      ? [proj, "project"]
+      : ws
+        ? [ws, "workspace"]
+        : saved !== DEFAULT_ROLE_MODELS[role] || (role === "advise" && named)
+          ? [saved, "settings"]
+          : env
+            ? [env, "env"]
+            : inherited
+              ? [inherited.ref, "inherited"]
+              : [saved, "default"];
   const parsed = parseModelRef(ref);
   return {
     role,
     ref: formatModelRef(parsed),
-    provider: providerFor(parsed.provider, models),
+    provider: providerFor(parsed.provider, models, opts.allowPi),
     model: parsed.model,
     source,
   };

package/lib/models/roles.ts

@@ -9,6 +9,8 @@
 export const MODEL_ROLES = [
   "plan",
   "implement",
+  "analyze",
+  "advise",
   "orchestrator",
   "review",
   "scope",
@@ -28,6 +30,14 @@ export const ROLE_LABELS: Record<ModelRole, { label: string; hint: string }> = {
     label: "Task implementation",
     hint: "A task's agent, following the plan in its worktree",
   },
+  analyze: {
+    label: "Analyst",
+    hint: "Reads code, logs and a developer's work; explains and proposes",
+  },
+  advise: {
+    label: "Reviewer",
+    hint: "Advises on another role's diff. Not the merge gate",
+  },
   orchestrator: { label: "Orchestrator", hint: "A workspace's orchestrator" },
   review: {
     label: "Gate review",
@@ -58,6 +68,8 @@ export const DEFAULT_ROLE_MODELS: Record<ModelRole, string> = {
   plan: OPUS,
   review: OPUS,
   implement: SONNET,
+  analyze: OPUS,
+  advise: OPUS,
   orchestrator: OPUS,
   scope: SONNET,
   interactive: OPUS,

package/lib/needs-you.ts

@@ -17,7 +17,7 @@ export function markSeen(sessionId: string): void {
   notifyStatusChanged();
 }
 
-function latestChatItem(sessionId: string): ChatItem | null {
+export function latestChatItem(sessionId: string): ChatItem | null {
   const row = getDb()
     .prepare(
       `SELECT data FROM chat_items WHERE session_id = ? ORDER BY seq DESC LIMIT 1`

package/lib/orchestration.ts

@@ -19,6 +19,7 @@ import { UNSET_SERVER_ENV } from "./agents/server-env";
 import { runInBackground } from "./async-operations";
 import { tmux } from "./tmux/exec";
 import { endTmuxSession } from "./tmux/end";
+import { inheritGroup } from "@/lib/session-groups/assignSessions";
 
 export interface SpawnWorkerOptions {
   conductorSessionId: string;
@@ -146,6 +147,7 @@ export async function spawnWorker(
     agentType,
     "uncategorized" // project_id
   );
+  inheritGroup(conductorSessionId, sessionId);
 
   // Update worktree info if created
   if (worktreePath) {