Merge remote-tracking branch 'origin/deploy' into deploy

Author: patel-lyzr

CLAUDE.md

@@ -92,7 +92,7 @@ Optional GitHub repo **variables** (build-time baked into the SPA bundle):
 The Mongo cluster is the source of truth for AgentOS. **Only the `agentos-server` connects to Mongo.** As of the post-0.2.1 dev build, the Python SDK no longer writes Mongo directly — it POSTs telemetry to the server's ingest endpoint (`AgentOSHttpSink` → `POST /agentos/api/ingest/events`), and the server owns all writes. (The old `AgentRegistrySink` + `MongoMessageSink` and the `motor` dep were removed — see the Python SDK history below.)
 
 **Collections (database = the server's `MONGO_DATABASE`):**
-- `agent_registry` — one doc per registered agent (the server writes `source.type="library"` for harness-mode agents → AgentOS UI hides the chat-sandbox button for those, see commit `8d829b8`). Also carries **ownership** (`ownerGroup`/`ownerUser`, see §2.6b) and **GAP source sync** (`sourceSha`/`sourceSyncedAt` — the commit SHA the SDK last loaded; the `session_started` projection updates it and logs drift, see §2.6c).
+- `agent_registry` — one doc per registered agent (the server writes `source.type="library"` for harness-mode agents → AgentOS UI hides the chat-sandbox button for those, see commit `8d829b8`). Also carries **ownership** (`ownerGroup`/`ownerUser`, see §2.6b) and **GAP source sync** (`sourceSha`/`sourceSyncedAt` — the commit SHA the SDK last loaded; the `session_started` projection updates it and logs drift, see §2.6c). **Identity key:** when the SDK supplies a stable `agent_id` (sparse-unique `agentId` field) the registry + per-agent joins (`sessions`/`chat_sessions`/`agent_logs`) key on it and `name` becomes a mutable display label — so renaming an agent doesn't re-register it. A legacy name-keyed doc is *adopted* (not duplicated) on the first run that carries an id; absent → keyed on `name` as before. Dashboard reads join `{$or:[{agentId},{name}]}` for back-compat.
 - `agent_logs` — one doc per conversation (one `ComputerAgent` instance = one log row, multi-turn collapses correctly since the 0.2.0 session-id refactor)
 - `sessions` — ordered chat transcript (one doc per session_id, entries appended in order; **`session_started` is the sole creator** of the doc, so a dropped/reordered start can't stub it)
 - `chat_sessions` — the session-index row (`{_id, agent, createdAt, lastMessageAt}`) the dashboard's session list + per-agent `sessionCount`/`lastActivity` read. The server projection writes this so library-mode sessions show up (the old Python sink omitted it).
@@ -405,7 +405,7 @@ pnpm build && pnpm start                  # node dist/index.js
 | `MONGO_URL` | `mongodb+srv://user:pass@cluster/...` — required, server refuses to start without it |
 | `MONGO_DATABASE` | Default `computeragent-test`. Set to `computeragent` / `computeragent-prod` per env |
 | `CA_BASE` | URL of the harness-server. Default `http://127.0.0.1:8787`. In Docker, use `http://host.docker.internal:8787` (Mac/Win) or the harness container hostname (compose / k8s) |
-| `ANTHROPIC_API_KEY` | Powers the `/completion` route (the "agent-less" chat from the SPA home page) |
+| `ANTHROPIC_API_KEY` | Powers the `/completion` route (the "agent-less" chat from the SPA home page) **and** the `POST /agentos/api/v1/messages` **Anthropic gateway** (`routes/messages.ts`) — a cak_-authed (`completion:run`) transparent reverse proxy to Anthropic. Lets a local SDK consumer point `ANTHROPIC_BASE_URL=<host>/agentos/api` + `ANTHROPIC_AUTH_TOKEN=cak_…` so the upstream key lives only on the server (see smoke #07). |
 
 **Optional env**
 
@@ -586,6 +586,8 @@ kustomize edit set image \
 | AgentOS auth / OIDC / BFF + refresh | `packages/agentos-server/src/auth/{oidc,authenticate,authorize,ownership,keycloak-admin}.ts`, `routes/auth.ts` |
 | Permission catalog + role seeds | `packages/agentos-server/src/auth/permissions.ts`, `stores/role-store.ts` |
 | Route composition / trust boundaries | `packages/agentos-server/src/app.ts`, `routes/dashboard.ts` |
+| Anthropic model gateway (cak_-authed proxy) | `packages/agentos-server/src/routes/messages.ts` (`POST /agentos/api/v1/messages`); smoke `computeragent-smoke/scripts/07_local_via_agentos_gateway.py` |
+| Run-an-agent-by-id (resolve handle) | `packages/agentos-server/src/routes/agents.ts` (`POST /agentos/api/v1/agents/resolve`, by `agentId`, group-scoped); SDK `computeragent-py/src/computeragent/harness/agent_resolve_client.py`; smoke `…/scripts/08_*.py` |
 | Git-credential store + resolve endpoint | `packages/agentos-server/src/crypto/secret-box.ts`, `stores/git-credential-store.ts`, `routes/git-credentials.ts` |
 | SDK private-repo clone (PAT + SHA) | `computeragent-py/src/computeragent/harness/git_credential_client.py`, `substrates/local.py` |
 | Keycloak provisioning script | `packages/agentos-server/scripts/provision-keycloak.mjs` (`pnpm provision:keycloak`) |

agentos/src/api.ts

@@ -2,6 +2,12 @@
 // and handles auth (the subdomain is gated by Caddy basic_auth). In dev, Vite
 // proxies /api with an injected Basic Auth header. So the bundle never holds creds.
 
+// Reactive token refresh (single-flight + replay) lives in lib/auth-fetch, shared
+// with obs-api + sse so every surface refreshes. Re-export setAuthLostHandler so
+// AuthContext keeps its existing import path.
+import { authedFetch, setAuthLostHandler } from "./lib/auth-fetch.ts";
+export { setAuthLostHandler };
+
 /** Mirrors the protocol's IdentitySource zod schema. The server narrows on
  *  read; the dashboard renders the structured form when present. */
 export type IdentitySource =
@@ -306,64 +312,13 @@ export interface GroupMember {
   roles: string[];
 }
 
-// ── Auth: reactive token refresh ─────────────────────────────────────────────
-// The BFF session cookie is short-lived (it tracks the Keycloak access-token
-// expiry, ~5 min). When a dashboard request 401s we silently POST /auth/refresh
-// (which rotates the server-held refresh token and re-signs the cookie) and
-// replay the original request once. All concurrent 401s share ONE in-flight
-// refresh — refresh tokens rotate and can be spent only once, so a stampede
-// would invalidate itself. On a hard refresh failure the session is truly gone:
-// we notify AuthContext (→ SSO sign-in screen).
-
-let refreshInFlight: Promise<boolean> | null = null;
-let onAuthLost: (() => void) | null = null;
-
-/** AuthContext registers a callback here to flip to the anonymous/login state
- *  when the refresh token is dead (idle timeout / revocation / logout). */
-export function setAuthLostHandler(fn: (() => void) | null): void {
-  onAuthLost = fn;
-}
-
-function tryRefresh(): Promise<boolean> {
-  if (!refreshInFlight) {
-    refreshInFlight = fetch(`/api/v1/auth/refresh`, {
-      method: "POST",
-      headers: { accept: "application/json" },
-      credentials: "include",
-    })
-      .then((r) => r.ok)
-      .catch(() => false)
-      .finally(() => {
-        refreshInFlight = null;
-      });
-  }
-  return refreshInFlight;
-}
-
-/** fetch against the dashboard API with credentials. On 401, refresh once and
- *  replay; if refresh fails, signal auth-lost and return the 401 response. */
-async function authedFetch(path: string, init: RequestInit): Promise<Response> {
-  const url = `/api/v1${path}`;
-  const opts: RequestInit = { credentials: "include", ...init };
-  let r = await fetch(url, opts);
-  if (r.status === 401) {
-    const ok = await tryRefresh();
-    if (ok) {
-      r = await fetch(url, opts);
-    } else {
-      onAuthLost?.();
-    }
-  }
-  return r;
-}
-
 async function getJSON<T>(path: string): Promise<T> {
-  const r = await authedFetch(path, { headers: { accept: "application/json" } });
+  const r = await authedFetch(`/api/v1${path}`, { headers: { accept: "application/json" } });
   if (!r.ok) throw new Error(`${path} → ${r.status}`);
   return r.json() as Promise<T>;
 }
 async function postJSON<T>(path: string, body: unknown): Promise<T> {
-  const r = await authedFetch(path, {
+  const r = await authedFetch(`/api/v1${path}`, {
     method: "POST",
     headers: { "content-type": "application/json", accept: "application/json" },
     body: JSON.stringify(body),
@@ -372,7 +327,7 @@ async function postJSON<T>(path: string, body: unknown): Promise<T> {
   return r.json() as Promise<T>;
 }
 async function reqJSON<T>(method: string, path: string, body?: unknown): Promise<T> {
-  const r = await authedFetch(path, {
+  const r = await authedFetch(`/api/v1${path}`, {
     method,
     headers: { "content-type": "application/json", accept: "application/json" },
     ...(body !== undefined ? { body: JSON.stringify(body) } : {}),

agentos/src/lib/auth-fetch.ts

@@ -0,0 +1,55 @@
+// Centralized auth-aware fetch — the SPA's "interceptor" for the BFF session.
+//
+// The session cookie is short-lived (it tracks the Keycloak access-token expiry,
+// ~5 min). When ANY request 401s we silently POST /auth/refresh — which rotates
+// the server-held refresh token and re-signs the cookie — then replay the
+// request once. All concurrent 401s share ONE in-flight refresh: refresh tokens
+// rotate and can be spent only once, so a stampede would invalidate itself.
+// On a hard refresh failure the session is truly gone → notify AuthContext
+// (which flips to the SSO sign-in screen).
+//
+// Every network surface routes through here: the dashboard client (api.ts), the
+// observability reads (obs-api.ts), and the SSE streams (sse.ts). `authedFetch`
+// takes a FULL url (not a prefix) so each caller keeps its own base.
+
+let refreshInFlight: Promise<boolean> | null = null;
+let onAuthLost: (() => void) | null = null;
+
+/** AuthContext registers a callback here to flip to the anonymous/login state
+ *  when the refresh token is dead (idle timeout / revocation / logout). */
+export function setAuthLostHandler(fn: (() => void) | null): void {
+  onAuthLost = fn;
+}
+
+/** Single-flight refresh. Returns true if the session was renewed. */
+export function refreshOnce(): Promise<boolean> {
+  if (!refreshInFlight) {
+    refreshInFlight = fetch(`/api/v1/auth/refresh`, {
+      method: "POST",
+      headers: { accept: "application/json" },
+      credentials: "include",
+    })
+      .then((r) => r.ok)
+      .catch(() => false)
+      .finally(() => {
+        refreshInFlight = null;
+      });
+  }
+  return refreshInFlight;
+}
+
+/** fetch with credentials. On 401: refresh once and replay; if refresh fails,
+ *  signal auth-lost and return the (final) 401 response to the caller. */
+export async function authedFetch(url: string, init: RequestInit = {}): Promise<Response> {
+  const opts: RequestInit = { credentials: "include", ...init };
+  let r = await fetch(url, opts);
+  if (r.status === 401) {
+    const ok = await refreshOnce();
+    if (ok) {
+      r = await fetch(url, opts);
+    } else {
+      onAuthLost?.();
+    }
+  }
+  return r;
+}

agentos/src/obs-api.ts

@@ -2,6 +2,7 @@
 // hits the local Express service via Vite's /obs-api proxy.
 
 import type { Operator } from "./obs-fields.ts";
+import { authedFetch } from "./lib/auth-fetch.ts";
 
 // Per-trace aggregate — one row per TraceId in /v1/traces and /v1/traces/search.
 export interface TraceSummary {
@@ -93,12 +94,12 @@ export interface DashboardData {
 }
 
 async function getJSON<T>(path: string): Promise<T> {
-  const r = await fetch(`/obs-api${path}`, { headers: { accept: "application/json" } });
+  const r = await authedFetch(`/obs-api${path}`, { headers: { accept: "application/json" } });
   if (!r.ok) throw new Error(`${path} → ${r.status} ${await r.text().catch(() => "")}`);
   return r.json() as Promise<T>;
 }
 async function postJSON<T>(path: string, body: unknown): Promise<T> {
-  const r = await fetch(`/obs-api${path}`, {
+  const r = await authedFetch(`/obs-api${path}`, {
     method: "POST",
     headers: { "content-type": "application/json", accept: "application/json" },
     body: JSON.stringify(body),

agentos/src/sse.ts

@@ -1,6 +1,12 @@
 // SSE chat streaming + multi-dialect event parser, ported from test.html.
 // Handles claude-agent-sdk (nested), gitagent (flat), and deepagents (LangGraph)
 // payload shapes. Surfaces tool-call progress + the final assistant text.
+//
+// Streams go through `authedFetch` (lib/auth-fetch): the session check happens
+// on the OPENING response, so a 401 there triggers the shared single-flight
+// refresh + one replay before the body stream is read.
+
+import { authedFetch } from "./lib/auth-fetch.ts";
 
 export interface ChatStreamHandlers {
   onTool?: (name: string, count: number) => void;
@@ -30,10 +36,9 @@ export async function streamCompletion(
   handlers: ChatStreamHandlers,
   signal?: AbortSignal,
 ): Promise<void> {
-  const res = await fetch("/api/completion", {
+  const res = await authedFetch("/api/completion", {
     method: "POST",
     headers: { "content-type": "application/json", accept: "text/event-stream" },
-    credentials: "include",
     body: JSON.stringify({ messages }),
     signal,
   });
@@ -84,7 +89,7 @@ export async function streamChat(
   handlers: ChatStreamHandlers,
   signal?: AbortSignal,
 ): Promise<void> {
-  const res = await fetch(url, {
+  const res = await authedFetch(url, {
     method: "POST",
     headers: { "content-type": "application/json", accept: "text/event-stream" },
     body: JSON.stringify({ message }),

packages/agentos-server/src/agent-defs.ts

@@ -19,6 +19,10 @@ export interface AgentDef {
   /** Surrogate key — the registry doc's ObjectId, stringified. The public
    *  API + frontend address agents by this. */
   id: string;
+  /** Stable caller-supplied agent id (when present). The per-agent join key
+   *  for sessions/logs that survives a `name` change. `null` for legacy/UI
+   *  agents that predate it. */
+  agentId?: string | null;
   name: string;
   label: string;
   harness: string;
@@ -177,6 +181,7 @@ export function registryDocToAgentDef(doc: RegistryDoc): AgentDef {
 
   return {
     id: doc._id.toString(),
+    agentId: doc.agentId ?? null,
     name: doc.name,
     label: doc.label ?? doc.name,
     harness: doc.harness ?? "claude-agent-sdk",

packages/agentos-server/src/app.smoke.test.ts

@@ -51,6 +51,16 @@ describe("app routing + auth gate", () => {
     expect(j.error.code).toBe("UNAUTHENTICATED");
   });
 
+  it("401s on the agent-resolve gateway when unauthenticated (cak_-gated)", async () => {
+    delete process.env["AGENTOS_DEV_AUTH"];
+    const r = await fetch(`${base}/agentos/api/v1/agents/resolve`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ agentId: "x" }),
+    });
+    expect(r.status).toBe(401);
+  });
+
   it("401s on /me when unauthenticated (the SPA's signal to show SSO sign-in)", async () => {
     delete process.env["AGENTOS_DEV_AUTH"];
     const r = await fetch(`${base}/agentos/api/v1/me`);

packages/agentos-server/src/mongo.ts

@@ -65,7 +65,8 @@ export async function pingMongo(): Promise<boolean> {
 
 export interface ChatSessionDoc {
   _id: string;             // sessionId
-  agent: string;           // owning agent name
+  agent: string;           // owning agent name (display label)
+  agentId?: string | null; // stable owning-agent id (when the SDK supplies one)
   createdAt?: Date;
   lastMessageAt?: Date;
 }
@@ -80,6 +81,7 @@ export interface SessionDoc {
   // reader normalizes both, and these extra fields are simply ignored there.
   createdAt?: Date;
   agentName?: string;
+  agentId?: string | null; // stable owning-agent id (when the SDK supplies one)
   source?: string;
   model?: string | null;
   // `meta.prompt` persists the opening prompt so session_ended can recover it
@@ -93,7 +95,9 @@ export interface SessionDoc {
 
 export interface RegistryDoc {
   _id: ObjectId;           // surrogate key (Mongo-minted)
-  name: string;            // the agent's human identifier (unique index)
+  name: string;            // the agent's human display name (unique index)
+  agentId?: string | null; // stable caller-supplied id; when present, the
+  // business key (sparse-unique). Renaming `name` keeps the same agentId/doc.
   label?: string;
   harness?: string;
   source?: unknown;        // string OR IdentitySource shape
@@ -264,6 +268,9 @@ export async function migrateRegistryObjectIds(): Promise<{ registry: number; pi
 export async function ensureRegistryIndexes(): Promise<void> {
   const db = await getDb();
   await db.collection("agent_registry").createIndex({ name: 1 }, { unique: true });
+  // Sparse-unique: the stable agent id is the business key when present; docs
+  // without one (legacy/UI-registered) are simply not indexed here.
+  await db.collection("agent_registry").createIndex({ agentId: 1 }, { unique: true, sparse: true });
   await db.collection("chat_pins").createIndex({ agentName: 1 }, { unique: true });
   await db.collection("agent_policies").createIndex({ agentName: 1 }, { unique: true });
 }