@standardagents/builder 0.29.2 → 0.30.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { getProviderModelPricing } from '@standardagents/provider-pricing';
 import { jsonPathReader } from '@formkit/jsonreader';
-import { ProviderError, mapReasoningLevel, THREAD_STREAM_REASONING_PARAM } from '@standardagents/spec';
+import { ProviderError, mapReasoningLevel, THREAD_STREAM_REASONING_PARAM, isUserEndpoint } from '@standardagents/spec';
 export { ProviderError, belongsToPackage, defineAgent, defineHook, defineModel, definePrompt, defineProvider, defineTool, isPacked, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue } from '@standardagents/spec';
 import 'virtual:@standardagents-providers';
 import { z } from 'zod';
@@ -14098,10 +14098,35 @@ var init_ThreadStateImpl = __esm({
         return { parentThreadId, parentStub };
       }
       _getAgentBuilderStub() {
-        const env = this._threadInstance.env;
+        const env = this._getRuntimeEnv();
         const agentBuilderId = env.AGENT_BUILDER.idFromName("singleton");
         return env.AGENT_BUILDER.get(agentBuilderId);
       }
+      /**
+       * Environment bindings for this state. In-DO construction uses the thread
+       * instance's own env; stub-backed states (thread endpoints, the user
+       * scope's `thread()`) have no `instance.env` over RPC and use the env the
+       * dispatcher recorded in the runtime context instead.
+       */
+      _getRuntimeEnv() {
+        const instanceEnv = this._threadInstance.env;
+        const env = instanceEnv?.AGENT_BUILDER ? instanceEnv : this._runtimeContext.env;
+        if (!env?.AGENT_BUILDER) {
+          throw new Error(
+            "No runtime environment available on this ThreadState. Stub-backed states must be constructed with runtimeContext.env."
+          );
+        }
+        return env;
+      }
+      /** The per-user hub stub for this thread's user (user-scope surfaces). */
+      _getUserHubStub(userId) {
+        const env = this._getRuntimeEnv();
+        const namespace = env.AGENT_BUILDER_USER_HUB;
+        if (!namespace) {
+          throw new Error("User scope unavailable: AGENT_BUILDER_USER_HUB binding is missing.");
+        }
+        return namespace.get(namespace.idFromName(userId));
+      }
       // ─────────────────────────────────────────────────────────────────────────
       // Skills — instance-global Agent Skills library, backed by the
       // DurableAgentBuilder singleton (skills are never stored per-thread or on
@@ -14118,7 +14143,67 @@ var init_ThreadStateImpl = __esm({
         const stub = this._getAgentBuilderStub();
         const user = await stub.getUserById(userId).catch(() => null);
         if (!user) return null;
+        const inUserScope = this._runtimeContext.inUserScope === true;
+        const agentId = this._metadata.agent_id;
+        const hub = () => this._getUserHubStub(userId);
+        const capabilities = {
+          call: async (endpoint, payload) => {
+            if (inUserScope) {
+              throw new Error(
+                "Reentrant user-scope call: this ThreadState was raised from user-scope code; state.user().call() is unavailable here."
+              );
+            }
+            const path20 = endpoint.replace(/^\/+/, "");
+            return hub().fetch(
+              new Request(`https://user-hub/users/${encodeURIComponent(userId)}/endpoints/${path20}`, {
+                method: "POST",
+                headers: {
+                  "Content-Type": "application/json",
+                  // Runtime-internal caller channel — the public routes overwrite
+                  // this header, so only thread-scope code can present "thread".
+                  "X-Standard-Agents-Caller": "thread"
+                },
+                body: payload === void 0 ? void 0 : JSON.stringify(payload)
+              })
+            );
+          },
+          getValue: async (key) => {
+            return await stub.getUserValue?.(userId, key);
+          },
+          setValue: async (key, value) => {
+            await stub.setUserValue?.(userId, key, value);
+          },
+          emit: (event, data) => {
+            const delivery = hub().broadcastUserEvent(userId, event, data).catch(() => {
+            });
+            this._pendingEventDeliveries.add(delivery);
+            void delivery.finally(
+              () => this._pendingEventDeliveries.delete(delivery)
+            );
+          },
+          fetch: async (grant, input, init) => {
+            const body = init?.body;
+            if (body !== void 0 && body !== null && typeof body !== "string") {
+              throw new Error("Grant fetch bodies must be strings in this runtime.");
+            }
+            return hub().fetch(
+              new Request(`https://user-hub/users/${encodeURIComponent(userId)}/grant-fetch`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                  grant,
+                  url: String(input),
+                  method: init?.method ?? "GET",
+                  headers: init?.headers ? Object.fromEntries(new Headers(init.headers)) : {},
+                  body: body ?? null,
+                  caller: { kind: "agent", name: agentId }
+                })
+              })
+            );
+          }
+        };
         return {
+          ...capabilities,
           id: user.id,
           username: user.username,
           role: user.role,
@@ -15476,8 +15561,9 @@ function createHmrReloader() {
       const isPromptFile = file.startsWith(dirs.promptsDir) && file.endsWith(".ts");
       const isAgentFile = file.startsWith(dirs.agentsDir) && file.endsWith(".ts");
       const isEffectFile = file.startsWith(dirs.effectsDir) && file.endsWith(".ts");
+      const isUserEndpointFile = file.startsWith(dirs.usersDir) && file.endsWith(".ts");
       const isConfigFile = isModelFile || isProviderFile || isPromptFile || isAgentFile || isEffectFile;
-      if (!isToolFile && !isThreadApiFile && !isHookFile && !isConfigFile) return;
+      if (!isToolFile && !isThreadApiFile && !isHookFile && !isConfigFile && !isUserEndpointFile) return;
       reloader.invalidateSourceFileModule(server, file);
       if (isConfigFile || isToolFile) regenerateTypes();
       if (isToolFile) await reloader.reloadToolsModule(server);
@@ -17503,6 +17589,35 @@ function parseRequestBody(req) {
     req.on("error", reject);
   });
 }
+function scanUsersDirectory(dir) {
+  const results = [];
+  if (!fs8__default.existsSync(dir)) return results;
+  const walk = (current, prefix) => {
+    let entries;
+    try {
+      entries = fs8__default.readdirSync(current, { withFileTypes: true });
+    } catch (error) {
+      console.error(`Error scanning users directory ${current}:`, error);
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path8__default.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath, prefix ? `${prefix}/${entry.name}` : entry.name);
+        continue;
+      }
+      if (!entry.name.endsWith(".ts") || entry.name.endsWith(".d.ts")) continue;
+      const base = entry.name.slice(0, -3);
+      const key = prefix ? `${prefix}/${base}` : base;
+      results.push({
+        key,
+        importPath: "./" + path8__default.relative(process.cwd(), fullPath).replace(/\\/g, "/")
+      });
+    }
+  };
+  walk(dir, "");
+  return results;
+}
 
 // src/plugin/agent-api-middleware.ts
 async function handleAgentApiRequest(context) {
@@ -21100,9 +21215,10 @@ function createDevMiddleware(server, context) {
   });
 }
 async function loadBuilderVirtualModule(context) {
-  const { toolsDir, hooksDir, modelsDir, promptsDir, agentsDir, effectsDir, hmr } = context;
+  const { toolsDir, hooksDir, modelsDir, promptsDir, agentsDir, effectsDir, usersDir, hmr } = context;
   const tools = await scanToolsDirectory(toolsDir);
   const hooks = await scanHooksDirectory(hooksDir);
+  const userEndpoints = scanUsersDirectory(usersDir);
   const models = await scanModelsDirectory(modelsDir);
   const prompts = await scanPromptsDirectory(promptsDir);
   const agents = await scanAgentsDirectory(agentsDir);
@@ -21204,6 +21320,17 @@ async function loadBuilderVirtualModule(context) {
   },`;
     }
   }).join("\n");
+  const userEndpointsCode = userEndpoints.map(({ key, importPath }) => {
+    const absPath = toAbsolutePath(importPath);
+    return `  "${key}": async () => {
+    try {
+      return (await import("${absPath}")).default;
+    } catch (error) {
+      console.error('Failed to import user endpoint ${key}:', error);
+      throw error;
+    }
+  },`;
+  }).join("\n");
   return `// Consolidated virtual module: virtual:@standardagents/builder /* v${hmr.versions.builder} */
 // Provides DurableThread, DurableAgentBuilder, ThreadWatchdog, and router
 import { DurableThread as _BaseDurableThread } from '@standardagents/builder/runtime';
@@ -21249,6 +21376,10 @@ const _effects = {
 ${effectsCode}
 };
 
+const _userEndpoints = {
+${userEndpointsCode}
+};
+
 /**
  * DurableThread with all virtual module methods already implemented.
  * Exported by the generated AgentBuilder Worker entry; user projects do not
@@ -21338,10 +21469,21 @@ export class CodeExecutionBridge extends _BaseCodeExecutionBridge {}
 export class ThreadWatchdog extends _BaseThreadWatchdog {}
 
 /**
- * Per-user hub companion. Coordination only (persistent daemon socket, wake
- * signal, sharded account KV); needs no virtual-module registries.
+ * Per-user hub companion: persistent daemon socket, wake signal, sharded
+ * account KV \u2014 and the USER SCOPE (spec: Users): packaged user endpoints from
+ * the users/ directory executed under per-user serialization, the user event
+ * stream, and user lifecycle hooks (filtered from the shared hooks registry
+ * by hook type at dispatch).
  */
-export class DurableUserHub extends _BaseDurableUserHub {}
+export class DurableUserHub extends _BaseDurableUserHub {
+  userEndpoints() {
+    return _userEndpoints;
+  }
+
+  userHooks() {
+    return _hooks;
+  }
+}
 `;
 }
 async function loadRegistryVirtualModule(context) {
@@ -22397,6 +22539,7 @@ function agentbuilder(options = {}) {
   const promptsDir = options.promptsDir ? path8__default.resolve(process.cwd(), options.promptsDir) : path8__default.resolve(process.cwd(), "agents/prompts");
   const agentsDir = options.agentsDir ? path8__default.resolve(process.cwd(), options.agentsDir) : path8__default.resolve(process.cwd(), "agents/agents");
   const effectsDir = options.effectsDir ? path8__default.resolve(process.cwd(), options.effectsDir) : path8__default.resolve(process.cwd(), "agents/effects");
+  const usersDir = options.usersDir ? path8__default.resolve(process.cwd(), options.usersDir) : path8__default.resolve(process.cwd(), "agents/users");
   const outputDir = path8__default.resolve(process.cwd(), ".agents");
   const generatedWorkerEntry = path8__default.join(outputDir, "worker.ts");
   const isProviderPackageInstalled = (packageName) => {
@@ -22459,6 +22602,7 @@ export { CodeExecutionBridge, DurableAgentBuilder, DurableThread, ThreadWatchdog
     toolsDir,
     hooksDir,
     threadApiDir,
+    usersDir,
     modelsDir,
     providersDir,
     promptsDir,
@@ -22469,6 +22613,7 @@ export { CodeExecutionBridge, DurableAgentBuilder, DurableThread, ThreadWatchdog
     toolsDir,
     hooksDir,
     threadApiDir,
+    usersDir,
     modelsDir,
     providersDir,
     promptsDir,
@@ -22556,6 +22701,7 @@ export { CodeExecutionBridge, DurableAgentBuilder, DurableThread, ThreadWatchdog
       this.addWatchFile(promptsDir);
       this.addWatchFile(agentsDir);
       this.addWatchFile(effectsDir);
+      this.addWatchFile(usersDir);
     },
     configureServer(server) {
       createDevMiddleware(server, devMiddlewareContext);
@@ -22660,7 +22806,9 @@ function createThreadEndpointHandler(handler) {
       const durableId = env.AGENT_BUILDER_THREAD.idFromName(threadId);
       const stub = env.AGENT_BUILDER_THREAD.get(durableId);
       const instance = stub;
-      const threadState = ThreadStateImpl.fromThreadInstance(instance, metadata);
+      const threadState = ThreadStateImpl.fromThreadInstance(instance, metadata, {
+        env
+      });
       const endpointParams = {};
       for (const [key, value] of Object.entries(params)) {
         if (key === "threadId" || key === "id" && !params.threadId) {
@@ -34540,6 +34688,232 @@ function formatMs(ms) {
   const minutes = Math.floor(seconds / 60);
   return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
 }
+
+// src/users/route-match.ts
+var METHOD_SUFFIXES = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete"]);
+function parseUserRouteKey(key) {
+  const parts = key.split("/");
+  let file = parts.pop() ?? "";
+  let method = "GET";
+  const dot = file.lastIndexOf(".");
+  if (dot >= 0) {
+    const suffix = file.slice(dot + 1).toLowerCase();
+    if (METHOD_SUFFIXES.has(suffix)) {
+      method = suffix.toUpperCase();
+      file = file.slice(0, dot);
+    }
+  }
+  const segments = [...parts];
+  if (file !== "index") segments.push(file);
+  let dynamism = 0;
+  for (const segment of segments) {
+    if (segment === "[*]") dynamism = 2;
+    else if (dynamism < 2 && segment.startsWith("[") && segment.endsWith("]")) dynamism = 1;
+  }
+  return { key, method, segments, dynamism };
+}
+function matchSegments(route, path20) {
+  const params = {};
+  for (let i = 0; i < route.length; i++) {
+    const seg = route[i];
+    if (seg === "[*]") {
+      if (i !== route.length - 1) return null;
+      params["*"] = path20.slice(i).join("/");
+      return params;
+    }
+    const value = path20[i];
+    if (value === void 0) return null;
+    if (seg.startsWith("[") && seg.endsWith("]")) {
+      params[seg.slice(1, -1)] = value;
+    } else if (seg !== value) {
+      return null;
+    }
+  }
+  return path20.length === route.length ? params : null;
+}
+function matchUserRoute(keys, method, endpointPath) {
+  const path20 = endpointPath.split("/").filter((s) => s.length > 0);
+  const wanted = method.toUpperCase();
+  let best = null;
+  for (const key of keys) {
+    const route = parseUserRouteKey(key);
+    if (route.method !== wanted) continue;
+    const params = matchSegments(route.segments, path20);
+    if (!params) continue;
+    if (!best || route.dynamism < best.route.dynamism) {
+      best = { route, params };
+    }
+  }
+  return best ? { key: best.route.key, params: best.params } : null;
+}
+
+// src/users/UserStateImpl.ts
+init_ThreadStateImpl();
+var UserStateImpl = class {
+  userId;
+  host;
+  /** Caller descriptor for grant `allow` policy checks. */
+  caller;
+  constructor(userId, host, caller) {
+    this.userId = userId;
+    this.host = host;
+    this.caller = caller;
+  }
+  singleton() {
+    const ns = this.host.env.AGENT_BUILDER;
+    if (!ns) throw new Error("AGENT_BUILDER binding unavailable in the user scope.");
+    return ns.get(ns.idFromName("singleton"));
+  }
+  async identity() {
+    const user = await this.singleton().getUserById(this.userId);
+    if (!user) throw new Error(`Unknown user: ${this.userId}`);
+    return {
+      id: user.id,
+      username: user.username,
+      role: user.role,
+      permissions: user.permissions ?? null,
+      email: user.email ?? null,
+      display_name: user.display_name ?? null,
+      avatar_url: user.avatar_url ?? null
+    };
+  }
+  async getValue(key) {
+    return await this.host.getUserValue(this.userId, key);
+  }
+  async setValue(key, value) {
+    await this.host.setUserValue(this.userId, key, value);
+  }
+  async listValues(options) {
+    const { entries, total } = await this.host.listUserValues(this.userId, options);
+    return { entries, total };
+  }
+  async env(name) {
+    const values = await this.singleton().getUserEnv(this.userId);
+    const value = values[name];
+    if (value === void 0) throw new Error(`Environment variable not found: ${name}`);
+    return value;
+  }
+  emit(event, data) {
+    this.host.broadcastUserEvent(this.userId, event, data);
+  }
+  async listThreads(options) {
+    const { threads, total } = await this.singleton().listThreads({
+      user_id: this.userId,
+      agent_name: options?.agentId,
+      limit: options?.limit,
+      offset: options?.offset
+    });
+    return {
+      threads: threads.map((t) => ({
+        id: t.id,
+        agent_id: t.agent_id ?? t.agent_name ?? "",
+        tags: t.tags ?? [],
+        created_at: t.created_at
+      })),
+      total
+    };
+  }
+  async fetch(grant, input, init) {
+    const body = init?.body;
+    if (body !== void 0 && body !== null && typeof body !== "string") {
+      throw new Error("Grant fetch bodies must be strings in this runtime.");
+    }
+    return this.host.grantFetch(this.userId, grant, {
+      url: String(input),
+      method: init?.method ?? "GET",
+      headers: init?.headers ? Object.fromEntries(new Headers(init.headers)) : {},
+      body: body ?? null,
+      caller: this.caller
+    });
+  }
+  /**
+   * Raise one of this user's threads at rest — the same stub-backed
+   * materialization thread endpoints receive. `inUserScope` marks the state
+   * so a reentrant `state.user().call()` fails instead of deadlocking the
+   * serialized user execution (spec: Users §2.2.3).
+   */
+  async thread(threadId) {
+    const metadata = await this.singleton().getThread(threadId);
+    if (!metadata) throw new Error(`Thread not found: ${threadId}`);
+    if (metadata.user_id !== this.userId) {
+      throw new Error(`Thread ${threadId} does not belong to user ${this.userId}.`);
+    }
+    const meta = metadata;
+    if (!meta.agent_id && meta.agent_name) meta.agent_id = meta.agent_name;
+    const ns = this.host.env.AGENT_BUILDER_THREAD;
+    if (!ns) throw new Error("AGENT_BUILDER_THREAD binding unavailable in the user scope.");
+    const instance = ns.get(ns.idFromName(threadId));
+    return ThreadStateImpl.fromThreadInstance(instance, meta, {
+      env: this.host.env,
+      inUserScope: true
+    });
+  }
+};
+
+// src/users/serialize.ts
+function createExecutionChain() {
+  let tail2 = Promise.resolve();
+  return {
+    run(fn) {
+      const next = tail2.then(fn, fn);
+      tail2 = next.catch(() => {
+      });
+      return next;
+    }
+  };
+}
+
+// src/users/grants.ts
+function originAllowed(origins, target) {
+  if (!Array.isArray(origins)) return false;
+  for (const allowed of origins) {
+    if (allowed.startsWith("*.")) {
+      const suffix = allowed.slice(1);
+      if (target.protocol === "https:" && target.hostname.endsWith(suffix)) return true;
+    } else {
+      try {
+        if (new URL(allowed).origin === target.origin) return true;
+      } catch {
+      }
+    }
+  }
+  return false;
+}
+function callerAllowed(allow, caller) {
+  if (!allow) return false;
+  const lists = {
+    tool: allow.tools,
+    endpoint: allow.endpoints,
+    userEndpoint: allow.userEndpoints,
+    userHook: allow.userEndpoints,
+    agent: allow.agents
+  };
+  const list = lists[caller.kind];
+  if (!list) return false;
+  const bare = caller.name.replace(/\.(get|post|put|patch|delete)$/i, "");
+  return list.includes(caller.name) || list.includes(bare);
+}
+function injectGrantCredential(config, secret, target, headers) {
+  const format = config.inject?.format ?? "SECRET";
+  switch (config.kind) {
+    case "bearer":
+      headers.set("Authorization", `Bearer ${secret}`);
+      return true;
+    case "header":
+      headers.set(config.inject?.header ?? "Authorization", format.replace(/SECRET/g, secret));
+      return true;
+    case "query":
+      target.searchParams.set(config.inject?.query ?? "key", secret);
+      return true;
+    case "basic":
+      headers.set("Authorization", `Basic ${btoa(secret)}`);
+      return true;
+    default:
+      return false;
+  }
+}
+
+// src/durable-objects/DurableUserHub.ts
 var DurableUserHub = class extends DurableObject {
   /** Persistent client (daemon) sockets, restored across hibernation. */
   clientSockets = /* @__PURE__ */ new Set();
@@ -34547,11 +34921,9 @@ var DurableUserHub = class extends DurableObject {
   migrated = false;
   constructor(ctx, env) {
     super(ctx, env);
-    if (typeof WebSocketRequestResponsePair !== "undefined") {
-      ctx.setWebSocketAutoResponse(
-        new WebSocketRequestResponsePair("stream_ping", "stream_pong")
-      );
-    }
+    ctx.blockConcurrencyWhile(async () => {
+      this.ensureMigrated();
+    });
     for (const ws of ctx.getWebSockets()) {
       const attachment = ws.deserializeAttachment();
       if (attachment?.type === "hub_client") {
@@ -34579,8 +34951,38 @@ var DurableUserHub = class extends DurableObject {
     this.ctx.storage.sql.exec(
       `CREATE INDEX IF NOT EXISTS idx_user_values_user ON user_values(user_id)`
     );
+    this.ctx.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS user_grants (
+        user_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        secret TEXT NOT NULL,
+        config TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (user_id, name)
+      )
+    `);
     this.migrated = true;
   }
+  // ─── User scope: registries (overridden by the generated virtual module) ──
+  /**
+   * Returns the user endpoints registry for lazy-loading `users/` files.
+   * Keys are endpoint file paths relative to `users/` with the extension
+   * stripped except the method suffix (e.g. `standardcode/lease_acquire.post`).
+   * Implemented when DurableUserHub is imported from
+   * 'virtual:@standardagents/builder'.
+   */
+  userEndpoints() {
+    return {};
+  }
+  /**
+   * Returns the hooks registry (same registry the thread runtime uses). The
+   * hub filters it to user-scope hook types at dispatch time. Implemented
+   * when DurableUserHub is imported from 'virtual:@standardagents/builder'.
+   */
+  userHooks() {
+    return {};
+  }
   // ─── Persistent client socket ──────────────────────────────────────────────
   /**
    * Accept the user's persistent client (daemon) WebSocket. The daemon holds
@@ -34589,6 +34991,16 @@ var DurableUserHub = class extends DurableObject {
    */
   async fetch(request) {
     const url = new URL(request.url);
+    const scopeMatch = /^\/users\/([^/]+)\/(stream|endpoints|grant-fetch)(?:\/(.*))?$/.exec(
+      url.pathname
+    );
+    if (scopeMatch) {
+      const userId = decodeURIComponent(scopeMatch[1]);
+      const kind = scopeMatch[2];
+      if (kind === "stream") return this.acceptUserStream(request, url, userId);
+      if (kind === "grant-fetch") return this.handleGrantFetch(request, userId);
+      return this.runUserEndpoint(request, userId, scopeMatch[3] ?? "");
+    }
     if (request.headers.get("Upgrade") === "websocket") {
       const pair = new WebSocketPair();
       const [client, server] = [pair[0], pair[1]];
@@ -34597,6 +35009,7 @@ var DurableUserHub = class extends DurableObject {
         clientName: url.searchParams.get("client_name"),
         clientKind: url.searchParams.get("client_kind")
       };
+      this.ensureHeartbeatAutoResponse();
       this.ctx.acceptWebSocket(server);
       server.serializeAttachment({ type: "hub_client", ...info });
       this.clientSockets.add(server);
@@ -34609,16 +35022,265 @@ var DurableUserHub = class extends DurableObject {
     }
     return new Response("Not found", { status: 404 });
   }
-  async webSocketMessage(ws, _message) {
-    if (!this.clientSockets.has(ws)) this.clientSockets.add(ws);
+  // ─── User scope: event stream (spec: Users §4) ─────────────────────────────
+  /** Idle sockets answer heartbeats at the edge without waking the object.
+   *  Registered at accept time rather than in the constructor so a hub that
+   *  never accepts a socket stays fully evictable (this also keeps
+   *  vitest-pool-workers' isolated storage able to pop the DO's frame). */
+  ensureHeartbeatAutoResponse() {
+    if (typeof WebSocketRequestResponsePair !== "undefined") {
+      this.ctx.setWebSocketAutoResponse(
+        new WebSocketRequestResponsePair("stream_ping", "stream_pong")
+      );
+    }
+  }
+  /** Sockets attached to the user event stream, restored after hibernation. */
+  streamSockets() {
+    return this.ctx.getWebSockets().filter((ws) => ws.deserializeAttachment()?.type === "user_stream");
+  }
+  acceptUserStream(request, url, userId) {
+    if (request.headers.get("Upgrade") !== "websocket") {
+      return Response.json({ error: "WebSocket upgrade required" }, { status: 426 });
+    }
+    const pair = new WebSocketPair();
+    const [client, server] = [pair[0], pair[1]];
+    const clientId = url.searchParams.get("client_id") ?? crypto.randomUUID();
+    const clientKind = url.searchParams.get("client_kind");
+    this.ensureHeartbeatAutoResponse();
+    this.ctx.acceptWebSocket(server);
+    server.serializeAttachment({ type: "user_stream", userId, clientId, clientKind });
+    try {
+      server.send(JSON.stringify({ event: "stream_ready", data: { client_id: clientId } }));
+    } catch {
+    }
+    this.dispatchUserHooks(userId, "user_client_attached", [
+      { id: clientId, kind: clientKind ?? void 0 }
+    ]);
+    return new Response(null, { status: 101, webSocket: client });
+  }
+  /**
+   * Deliver an event frame to every socket attached to this user's stream.
+   * At-most-once, live-only (spec: Users §4) — no history, no acks.
+   */
+  broadcastUserEvent(userId, event, data) {
+    const frame = JSON.stringify({ event, data });
+    for (const ws of this.streamSockets()) {
+      const attachment = ws.deserializeAttachment();
+      if (attachment?.userId !== userId) continue;
+      try {
+        ws.send(frame);
+      } catch {
+      }
+    }
+  }
+  // ─── User scope: serialized endpoint execution (spec: Users §2.1, §3) ─────
+  /** Per-user execution chain (spec: Users §2.1) — see users/serialize.ts. */
+  executionChain = createExecutionChain();
+  scopeHost() {
+    return {
+      getUserValue: (userId, key) => this.getUserValue(userId, key),
+      setUserValue: (userId, key, value) => this.setUserValue(userId, key, value),
+      listUserValues: (userId, options) => this.listUserValues(userId, options ?? {}),
+      broadcastUserEvent: (userId, event, data) => this.broadcastUserEvent(userId, event, data),
+      grantFetch: (userId, grant, req) => this.grantFetch(userId, grant, req),
+      env: this.env
+    };
+  }
+  async runUserEndpoint(request, userId, endpointPath) {
+    const registry = this.userEndpoints();
+    const match = matchUserRoute(Object.keys(registry), request.method, endpointPath);
+    if (!match) return Response.json({ error: "Not found" }, { status: 404 });
+    let loaded;
+    try {
+      loaded = await registry[match.key]();
+    } catch (error) {
+      return Response.json(
+        { error: `Failed to load user endpoint: ${match.key}` },
+        { status: 500 }
+      );
+    }
+    const module = loaded;
+    const handler = module.default ?? loaded;
+    if (!isUserEndpoint(handler)) {
+      return Response.json(
+        { error: `${match.key} is not a defineUserEndpoint export` },
+        { status: 500 }
+      );
+    }
+    return this.executionChain.run(async () => {
+      const user = new UserStateImpl(userId, this.scopeHost(), {
+        kind: "userEndpoint",
+        name: match.key
+      });
+      try {
+        return await handler.__handler(request, user, match.params);
+      } catch (error) {
+        return Response.json(
+          { error: error instanceof Error ? error.message : "User endpoint failed" },
+          { status: 500 }
+        );
+      }
+    });
+  }
+  // ─── User scope: lifecycle hooks (spec: Users §7) ──────────────────────────
+  /**
+   * Fire every definition of a user hook type. Observational and best-effort:
+   * failures are swallowed and dispatch never blocks the triggering
+   * operation. Nested dispatch is suppressed so a `user_value_changed` hook
+   * writing values cannot recurse.
+   */
+  inUserHookDispatch = false;
+  dispatchUserHooks(userId, hookType, args) {
+    if (this.inUserHookDispatch) return;
+    const registry = this.userHooks();
+    const names = Object.keys(registry);
+    if (names.length === 0) return;
+    const run = async () => {
+      const user = new UserStateImpl(userId, this.scopeHost(), {
+        kind: "userHook",
+        name: hookType
+      });
+      for (const name of names) {
+        try {
+          const loaded = await registry[name]();
+          const definition = loaded.default ?? loaded;
+          if (definition?.hook !== hookType || typeof definition.execute !== "function") {
+            continue;
+          }
+          this.inUserHookDispatch = true;
+          try {
+            await definition.execute(user, ...args);
+          } finally {
+            this.inUserHookDispatch = false;
+          }
+        } catch {
+        }
+      }
+    };
+    this.ctx.waitUntil(run());
   }
   async webSocketClose(ws) {
+    const attachment = ws.deserializeAttachment();
+    if (attachment?.type === "user_stream") {
+      this.dispatchUserHooks(String(attachment.userId), "user_client_detached", [
+        {
+          id: typeof attachment.clientId === "string" ? attachment.clientId : "unknown",
+          kind: typeof attachment.clientKind === "string" ? attachment.clientKind : void 0
+        }
+      ]);
+      return;
+    }
     this.clientSockets.delete(ws);
     this.clientInfo.delete(ws);
   }
+  // ─── User scope: credential grants (spec: Users §6) ───────────────────────
+  /**
+   * Store or replace a grant. `secret` is write-only from this point on.
+   * Policy (`CredentialGrant` minus the secret) is kept as JSON config.
+   */
+  async setGrant(userId, grant, secret) {
+    this.ensureMigrated();
+    const { name, ...config } = grant;
+    const now = Date.now();
+    await this.ctx.storage.sql.exec(
+      `INSERT INTO user_grants (user_id, name, secret, config, created_at, updated_at)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?5)
+       ON CONFLICT(user_id, name) DO UPDATE SET
+         secret = excluded.secret, config = excluded.config, updated_at = excluded.updated_at`,
+      userId,
+      name,
+      secret,
+      JSON.stringify(config),
+      now
+    );
+  }
+  async deleteGrant(userId, name) {
+    this.ensureMigrated();
+    await this.ctx.storage.sql.exec(
+      `DELETE FROM user_grants WHERE user_id = ? AND name = ?`,
+      userId,
+      name
+    );
+  }
+  /** Metadata-only listing — never returns secret material. */
+  async listGrants(userId) {
+    this.ensureMigrated();
+    const cursor = await this.ctx.storage.sql.exec(
+      `SELECT name, config FROM user_grants WHERE user_id = ? ORDER BY name ASC`,
+      userId
+    );
+    return cursor.toArray().map((row) => {
+      let config = {};
+      try {
+        config = JSON.parse(row.config);
+      } catch {
+      }
+      return { name: row.name, ...config };
+    });
+  }
+  /** Perform a privileged fetch with the grant's credential injected. */
+  async grantFetch(userId, grantName, req) {
+    this.ensureMigrated();
+    const cursor = await this.ctx.storage.sql.exec(
+      `SELECT secret, config FROM user_grants WHERE user_id = ? AND name = ? LIMIT 1`,
+      userId,
+      grantName
+    );
+    const row = cursor.toArray()[0];
+    if (!row) {
+      return Response.json({ error: "grant_not_found", grant: grantName }, { status: 404 });
+    }
+    let config;
+    try {
+      config = JSON.parse(row.config);
+    } catch {
+      return Response.json({ error: "grant_config_invalid" }, { status: 500 });
+    }
+    let target;
+    try {
+      target = new URL(req.url);
+    } catch {
+      return Response.json({ error: "grant_target_invalid" }, { status: 400 });
+    }
+    if (!originAllowed(config.origins, target)) {
+      return Response.json({ error: "grant_origin_denied" }, { status: 403 });
+    }
+    if (!callerAllowed(config.allow, req.caller)) {
+      return Response.json({ error: "grant_caller_denied" }, { status: 403 });
+    }
+    const headers = new Headers(req.headers);
+    if (!injectGrantCredential(config, row.secret, target, headers)) {
+      return Response.json({ error: "grant_kind_unsupported" }, { status: 501 });
+    }
+    try {
+      const response = await fetch(target.toString(), {
+        method: req.method,
+        headers,
+        body: req.body ?? void 0
+      });
+      return new Response(response.body, { status: response.status, headers: response.headers });
+    } catch {
+      return Response.json({ error: "grant_fetch_failed" }, { status: 502 });
+    }
+  }
+  async handleGrantFetch(request, userId) {
+    const body = await request.json().catch(() => null);
+    if (!body?.grant || !body.url) {
+      return Response.json({ error: "grant and url required" }, { status: 400 });
+    }
+    return this.grantFetch(userId, body.grant, {
+      url: body.url,
+      method: body.method ?? "GET",
+      headers: body.headers ?? {},
+      body: body.body ?? null,
+      caller: body.caller ?? { kind: "unknown", name: "unknown" }
+    });
+  }
+  async webSocketMessage(ws, _message) {
+    if (!this.clientSockets.has(ws)) this.clientSockets.add(ws);
+  }
   async webSocketError(ws) {
-    this.clientSockets.delete(ws);
-    this.clientInfo.delete(ws);
+    await this.webSocketClose(ws);
   }
   /** Whether a persistent client (daemon) is connected right now. */
   async hasClient() {
@@ -34678,6 +35340,7 @@ var DurableUserHub = class extends DurableObject {
         userId,
         key
       );
+      this.dispatchUserHooks(userId, "user_value_changed", [key]);
       return;
     }
     const serialized = JSON.stringify(value);
@@ -34693,6 +35356,7 @@ var DurableUserHub = class extends DurableObject {
       serialized,
       now
     );
+    this.dispatchUserHooks(userId, "user_value_changed", [key]);
   }
   async listUserValues(userId, options = {}) {
     this.ensureMigrated();