@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

package/docs/CLI_SHELL.md

@@ -1,6 +1,6 @@
 # Agent Sam SDK — terminal experience
 
-`agentsam` is the product entrypoint. Users do not choose a renderer or need to know whether a screen is implemented with ANSI, Rich, Clack, or another terminal library.
+`agentsam` is the product entrypoint. Users do not choose a renderer or need to know whether a screen is implemented with ANSI, Clack, or another terminal library.
 
 ## Product entrypoint
 
@@ -8,26 +8,166 @@
 agentsam
 ```
 
-On the first run for a project, Agent Sam opens keyboard-driven setup for the project, runtime, terminal, and model preference. On later runs it shows a short project-aware boot transition and enters the Agent Sam prompt.
+On first use in a project, Agent Sam asks whether the directory is trusted before project-local instructions, hooks, or execution policy can load. The setup flow then uses keyboard-driven selectors for runtime and model policy.
+
+Model policy is explicit and is governed by the normative model-selection SSOT contract in `protocol/models/README.md`:
+
+1. **Provider** — the explicit provider lane selected by the user.
+2. **Model** — the exact provider-verified model; provider-level pseudo-models such as `automatic` or `default` are not substitutes for exact selection.
+3. **Reasoning level** — one of the reasoning efforts declared by that model.
+4. **Processing** — Standard, Fast, Flex, or another tier only when that model declares it.
+
+`/models`, `agentsam models`, exact `-m <model_id>` selection, runtime execution, and usage receipts must all resolve through that same inventory/selection authority. AgentSam may curate and rank a useful first page, but provider availability, capabilities, limits, and pricing retain provider-authoritative provenance.
+
+For models with materially different pricing by reasoning, service tier, or context size, these controls are user-visible policy. They are not hidden prompt hints.
+
+After setup, bare text is an Agent Sam request. Slash commands control the runtime.
+
+```text
+sam ~/project > Find why OAuth callback state is failing
+
+  Model request
+  model       openai:gpt-6-astra
+  reasoning   high
+  processing  default
+  context     ~18,240 input tokens
+  max call    $... conservative ceiling
+
+  Send this request?  Yes / No
+```
+
+The model preflight is shown before the first paid request in a session, and again if a later request raises the previously approved conservative cost ceiling. Current active context remains distinct from cumulative session usage.
+
+## Command picker
+
+Typing `/` opens the scrollable command picker in an interactive terminal. The picker is generated from the implemented command catalog; commands should not be advertised before a handler exists.
+
+Current controls include:
+
+```text
+/model       exact model + reasoning + processing selectors
+/reasoning   change the selected model's reasoning effort
+/fast        request the model's Fast processing tier
+/flex        request Flex processing when supported
+/standard    return to Standard processing
+/context     context economics and current active-context information
+/models      safe credential/provider/model inventory
+/whoami      authenticated IAM identity + safe credential status
+/session     current cumulative token/cost/resume receipt
+/cf          bounded Cloudflare/Workers operations
+/status      local project / DB / Git / PTY health
+/settings    project/runtime/terminal/model preferences
+/pwd         working directory
+/cd          change working directory
+/git         Git operations
+/diff        Git diff
+/db          local SQLite
+/agent       local Agent Sam dev-server request
+/logs        local execution events
+/deploy      intentional deployment flow
+/clear       clear the terminal
+/help        show commands
+/exit        save/pause the session and return to the host terminal
+```
+
+Provider-brand commands such as `/claude` or `/codex` are not the generic shell contract. Model execution stays behind Agent Sam.
+
+## Credentials and identity
+
+A user should not need to manually `source` and `unset` provider keys for every Agent Sam command.
+
+Agent Sam resolves credentials in this order:
+
+1. an explicitly supplied credential where a command contract permits one;
+2. the current process environment;
+3. the user's secure Agent Sam provider files under `~/.agentsam/env.d/`.
+
+Provider files are machine-local and must not be group/world-readable on POSIX systems. Agent Sam parses the expected variable from the file rather than evaluating the file as shell code.
+
+`agentsam models` uses the credential internally for safe provider discovery but never returns the secret. Its public status reports only safe facts such as provider, configured state, source class, and provider-verified model availability.
+
+IAM login is also machine-local rather than repository state. A successful browser authentication may persist the `sdk_` bearer under `~/.agentsam/auth/session.json` with restrictive permissions. `agentsam whoami`, deploy, tunnel, and context detection can reuse that validated session. Project `.agentsam/config.json` remains portable and must not become a second identity database.
+
+```bash
+agentsam whoami
+agentsam whoami --json
+```
+
+`whoami` can show safe identity/account information and whether provider credentials are available. It never prints API-key or SDK-bearer values.
+
+## Execution approval
+
+Model reasoning does not itself authorize host execution.
+
+Read-only/no-side-effect capabilities may execute under the current trusted runtime policy. A model-selected capability with declared side effects must pass a runtime-owned approval boundary before its handler is invoked.
 
 ```text
-$ agentsam
+Agent Sam needs execution permission
 
-  Agent Sam
-  my-project · main · qwen2.5-coder
+  action  cloudflare.wrangler.native:whoami
+  target  local runtime · ~/project
+  effect  local_process
+  input   {"command":"whoami"}
 
-  ✓ project
-  ✓ runtime
-  ✓ model
+  secrets remain runtime-owned and are not included in the model-visible result.
 
-  username ~/path/to/project >
+? Allow cloudflare.wrangler.native:whoami?
+  Allow once
+  Always allow cloudflare.wrangler.native:whoami in this project
+  Deny
 ```
 
-The model stored by the CLI is a **preference only**. It does not replace the connected host/runtime as model-routing authority.
+Persistent approvals are exact-operation and exact-project grants. Approving `wrangler whoami` does not authorize another Wrangler operation or another repository.
 
-Live terminal scenes are automatic product behavior. When Agent Sam is actively handling an `/agent` request, the installed CLI renders the compact thinking/activity panel itself; users never run a renderer or preview command. The same shipped activity seam accepts model, tool, and context-compaction lifecycle events from richer hosts. Pipes and CI remain plain/deterministic.
+Commands whose purpose is to disclose a credential, such as `wrangler auth token`, are not model-visible capabilities. Safe identity/authorization probes are preferred.
 
-Use `/settings` inside Agent Sam to revisit the keyboard choices and `/models` to inspect providers and locally available models.
+## Sessions and resume
+
+Every interactive Agent Sam run receives a provider-neutral session identifier:
+
+```text
+asess_<uuid>
+```
+
+Provider response IDs live beneath the Agent Sam session and are not the public session identity. Session files are machine-local under `~/.agentsam/sessions/` and use restrictive permissions.
+
+The session retains enough runtime state to continue a compatible provider conversation, including selected model policy, provider continuation reference, current usage snapshot, cumulative usage, accumulated catalog-calculated cost, last safe error receipt, cwd, and the last substantive user request/command used as the session title.
+
+Housekeeping actions such as `/exit`, `/help`, and `/session` do not replace that human-readable title.
+
+On Ctrl+C or normal exit, Agent Sam saves the session and prints a compact receipt:
+
+```text
+Token usage: total=21,463 input=21,244 (+ 60,544 cached) output=219 reasoning=...
+Cost: $... · openai:gpt-6-astra · fast
+Active context: ... tokens
+
+To continue this session, run:
+  agentsam resume asess_...
+
+Or run:
+  agentsam resume
+
+and select:
+  Run wrangler whoami
+```
+
+Provider-reported token usage is authoritative when available. Cached input is reported separately rather than added to normal input. Cost is calculated from Agent Sam's active model/pricing authority and is not presented as a provider invoice unless the provider supplied one.
+
+Resume commands:
+
+```bash
+agentsam resume asess_...
+agentsam resume              # scrollable recent-session picker in a TTY
+agentsam resume --list
+agentsam resume --json
+```
+
+Changing model, reasoning effort, or processing tier breaks provider-continuation compatibility for the next turn; Agent Sam starts a fresh provider continuation while retaining cumulative Agent Sam session accounting.
+
+## Error presentation
+
+Errors preserve machine identity instead of becoming generic prose. Where available the terminal should surface HTTP status, provider error type/code, request or Ray ID, retry metadata, requested/resolved service tier, and retry classification. Secrets and authorization headers are redacted before an error receipt enters model-visible output or a persisted session.
 
 ## One-shot commands
 
@@ -36,14 +176,15 @@ Normal commands remain deterministic and scriptable:
 ```bash
 agentsam status
 agentsam models
-agentsam inspect --json
+agentsam whoami --json
+agentsam inspect --match oauth --view files --json
 agentsam deploy
 agentsam --help
 ```
 
-`agentsam shell` remains an explicit/secondary way to enter the slash-command shell. Bare `agentsam` is the normal interactive entrypoint.
+`agentsam shell` remains an explicit/secondary way to enter the same shell. Bare `agentsam` is the normal interactive entrypoint.
 
-For regression tests, one slash command can still be dispatched without opening an interactive terminal:
+For regression tests, a slash command can be dispatched without creating interactive-session clutter:
 
 ```bash
 agentsam shell --command /help
@@ -51,56 +192,25 @@ agentsam shell --command /help
 
 ## Internal UI engine
 
-The renderer is implementation detail:
+Presentation is implementation detail:
 
 ```text
 Agent Sam lifecycle/state
         |
         +--> ANSI / picocolors       semantic color + cursor control
-        +--> Rich renderer           high-fidelity live render experiments
         +--> Clack prompts           arrow-key selects / confirms / text input
-        +--> node-pty                real shell/process/filesystem
-```
-
-SDK developers can preview render experiments from this repository without exposing renderer names as product commands:
-
-```bash
-npm run ui:preview -- tour
-npm run ui:preview -- boot
-npm run ui:preview -- setup
-npm run ui:preview -- thinking
-npm run ui:preview -- ready
-npm run ui:preview -- ansi
-```
-
-These preview commands are a design lab, not part of the installed user vocabulary.
-
-## Slash commands
-
-```text
-/help       show commands
-/status     local project / DB / Git / PTY health
-/context    current repository + revision
-/pwd        working directory
-/cd         change working directory
-/git        Git operations
-/db         local SQLite
-/agent      invoke configured Agent Sam
-/models     inspect available providers and local models
-/settings   choose project/runtime/terminal/model preference
-/logs       local execution events
-/deploy     intentionally add a cloud adapter
-/exit       exit Agent Sam and return to the host terminal
+        +--> runtime activity        thinking/tool/context lifecycle
+        +--> node-pty / host runtime real process/filesystem boundary
 ```
 
-Provider-specific commands such as `/claude` or `/codex` are not part of the generic shell contract. Model execution/routing belongs behind Agent Sam.
+SDK developers can preview rendering experiments from this repository, but those are design-lab commands rather than installed product vocabulary.
 
 ## Local project contract
 
-`agentsam init` creates a local project with Git, `.env`, `.agentsam/config.json`, a committed `.agentsamrules` project-instruction file, local SQLite, and the project runtime files. The setup wizard uses keyboard-driven Clack prompts in an interactive terminal; flags keep non-interactive creation deterministic.
+`agentsam init` owns portable repository/project setup. User identity, provider secrets, session history, execution approvals, and provider continuation state are machine/account runtime state and must not be written into portable project configuration.
 
-Local development requires no Worker or cloud account. Cloud infrastructure is added intentionally at deploy time.
+Local development does not require a cloud account. Cloud infrastructure is added intentionally.
 
 ## Design rule
 
-A CLI operation must remain understandable in plain text and deterministic in CI/pipes. Interactive terminals may enhance that state with color, cursor redraw, prompts, progress, and animation. Presentation does not authorize tools, own execution policy, or silently become model-routing authority.
+A CLI operation must remain understandable in plain text and deterministic in CI/pipes. Interactive terminals may enhance state with color, cursor redraw, selectors, confirmation, progress, and animation. Presentation does not authorize tools, own credentials, or silently become model-routing authority. Runtime contracts do.

package/docs/RELEASES.md

@@ -1,14 +1,22 @@
 # `@inneranimalmedia/agentsam-sdk` release receipts
 
-**2.5.0 is the current release candidate on `main`; it is not published yet.**
-The npm `latest` dist-tag is **2.4.1**. The private identity workspace continues to
+**2.6.0 is the current release candidate on `main`; it is not published yet.**
+The npm `latest` dist-tag is **2.5.0**. The private identity workspace continues to
 ship through root SDK exports and is not published separately.
 
-Release-candidate base: `236afa84b553fb0d0109abe41939488945c4fc74`. The final tagged
-publish commit will be recorded here after release. Publishing remains manual and
-`prepublishOnly` runs `npm run verify:release`.
+Release-candidate base: `2643c164b0a745d0772f1aa9808c03bbe3873c94`. The final tagged publish commit will be recorded
+here after release. Publishing remains manual and `prepublishOnly` runs
+`npm run verify:release`.
 
-## 2.5.0 candidate highlights
+## 2.6.0 candidate highlights
+
+- Interactive AgentSam now has persistent machine-local account/session identity with explicit `login`, `logout`, `whoami`, and `resume` flows.
+- `/models` and model-selection UX bind to the canonical model inventory v2 contract instead of maintaining a second CLI catalog.
+- Provider credentials and account BYOK resolution are scoped, source-aware, and reusable across interactive, deploy, and tunnel flows without storing secrets in project state.
+- Runtime receipts now model account-owned runs, provider usage, approvals, and terminal jobs with stable lineage and no tenant/workspace/user ownership aliases.
+- Cloudflare diagnostics, context economics, repository evidence, and security/indexing contracts accumulated after 2.5.0 are included in the same verified release lineage.
+
+## 2.5.0 highlights
 
 - `agentsam` is the interactive product entrypoint; renderer selection is internal, and live thinking/activity scenes now run automatically around real Agent Sam work.
 - Portable project authority is `.agentsam/config.json` + `.agentsamrules`; local CLI preferences remain non-authoritative.
@@ -23,7 +31,8 @@ publish commit will be recorded here after release. Publishing remains manual an
 
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
-| 2.5.0 | _(pending)_ | _(tag at publish)_ | Release candidate; full verification required immediately before publish. |
+| 2.6.0 | _(pending)_ | _(tag at publish)_ | Release candidate; interactive model/session SSOT and account-scoped runtime receipts. |
+| 2.5.0 | 2026-09-11T21:27:11.516Z | `da28623dc4808025b77605ed09aa16217b1db607` | Published package; registry `gitHead` receipt. |
 | 2.4.1 | 2026-09-11T05:45:03.622Z | `a256ababededd904da555e7898bc8afd753737d2` | Latest published package before 2.5.0. |
 | 2.4.0 | 2026-09-11T05:29:02.811Z | `81c8659977953bed53c2adb0a341ce7382be4794` | Published 2.4 line. |
 | 2.3.0 | 2026-09-11T05:09:40.046Z | `b517a720fb9b90f35c26f9ef87a84abd60d7ee01` | Published 2.3 line. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Portable AgentSam SDK and CLI kits for local scaffolding, repository intelligence, incremental indexing, identity adapters, and verified dependency maintenance.",
   "type": "module",
   "main": "./src/index.js",
@@ -50,6 +50,12 @@
     "./context": "./src/context/index.js",
     "./indexing": "./src/indexing/index.js",
     "./tools": "./src/tools/index.js",
+    "./models": "./src/models/index.js",
+    "./telemetry": "./src/telemetry/index.js",
+    "./providers": "./src/providers/index.js",
+    "./errors": "./src/errors/index.js",
+    "./cloudflare": "./src/cloudflare/index.js",
+    "./eval": "./src/eval/index.js",
     "./context/result-policy-schema": "./protocol/context/result-policy.schema.json",
     "./context/budget-schema": "./protocol/context/context-budget.schema.json",
     "./context/pack-schema": "./protocol/context/resolved-context-pack.schema.json",
@@ -57,14 +63,15 @@
     "./skills/catalog": "./skills/catalog.json"
   },
   "bin": {
-    "agentsam": "src/cli.js",
-    "agentsam-sdk": "src/cli.js",
+    "agentsam": "bin/agentsam",
+    "agentsam-sdk": "bin/agentsam",
     "agentsam-scaffold": "bin/scaffold.mjs",
     "agentsam-auth-portal": "packages/identity/scripts/preview-auth-portal.mjs"
   },
   "files": [
     "src",
     "packages/identity",
+    "packages/connectors/cloudflare",
     "templates",
     "docs",
     "examples",
@@ -79,7 +86,8 @@
     "bin",
     "README.md",
     "LICENSE",
-    "DEVELOPMENT.md"
+    "DEVELOPMENT.md",
+    "AGENTSAM.md"
   ],
   "workspaces": [
     "packages/agentsam-shell-kit",
@@ -88,7 +96,7 @@
     "packages/agentsam-workbench"
   ],
   "scripts": {
-    "test": "node test/smoke.mjs && node --test test/*.test.mjs && npm --prefix packages/identity test",
+    "test": "node test/smoke.mjs && node --test test/*.test.mjs && npm --prefix packages/identity test && npm run test:connectors",
     "test:identity": "npm --prefix packages/identity test",
     "smoke": "node test/smoke.mjs",
     "verify:package": "node scripts/verify-package.mjs",
@@ -105,10 +113,13 @@
     "prepublishOnly": "npm run verify:release",
     "security:check": "node src/security/cli.mjs scan",
     "security:repair": "node src/security/cli.mjs repair",
-    "ui:preview": "node scripts/ui-preview.mjs"
+    "ui:preview": "node scripts/ui-preview.mjs",
+    "test:connectors": "node --test packages/connectors/cloudflare/tests/**/*.test.mjs",
+    "verify:npm10-lock": "node apps/local-studio/scripts/verify-npm10-lock.mjs"
   },
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22 <25",
+    "npm": ">=10 <12"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
@@ -146,5 +157,6 @@
   "devDependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9"
-  }
+  },
+  "packageManager": "npm@10.9.2"
 }

package/packages/connectors/cloudflare/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@inneranimalmedia/agentsam-connector-cloudflare",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  }
+}

package/packages/connectors/cloudflare/src/index.js

@@ -0,0 +1,127 @@
+/**
+ * Cloudflare account connector (not an identity provider).
+ * Answers: what Cloudflare account has this authenticated AgentSam user authorized?
+ */
+
+export const CLOUDFLARE_OAUTH_AUTHORIZE_URL = 'https://dash.cloudflare.com/oauth2/auth';
+export const CLOUDFLARE_OAUTH_TOKEN_URL = 'https://dash.cloudflare.com/oauth2/token';
+export const CLOUDFLARE_CALLBACK_PATH = '/api/connections/cloudflare/callback';
+export const CLOUDFLARE_FIXTURE_CLIENT_ID = 'sillynotreal';
+export const CLOUDFLARE_FIXTURE_CLIENT_SECRET = 'sillynotreal-secret';
+
+export const CLOUDFLARE_OAUTH_REVOKE_URL = 'https://dash.cloudflare.com/oauth2/revoke';
+
+/** Smallest useful scopes mapped to Cloudflare API token permission names. */
+export const CLOUDFLARE_CAPABILITY_SCOPES = Object.freeze({
+  workers_deploy: {
+    scopes: ['workers-scripts.write'],
+    why: 'Deploy Workers for the connected account (Workers Scripts Edit).',
+  },
+  d1_inspect: {
+    scopes: ['d1.read'],
+    why: 'Inspect D1 databases bound to the deployable.',
+  },
+  r2_inspect: {
+    scopes: ['workers-r2-storage.read'],
+    why: 'Inspect R2 buckets bound to the deployable.',
+  },
+  worker_logs: {
+    scopes: ['workers-scripts.read'],
+    why: 'Read Worker script metadata/logs for postdeploy health.',
+  },
+});
+
+export function requestedCloudflareScopes() {
+  const set = new Set();
+  for (const cap of Object.values(CLOUDFLARE_CAPABILITY_SCOPES)) {
+    for (const scope of cap.scopes) set.add(scope);
+  }
+  return [...set];
+}
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function isFixtureCloudflareCredential(value) {
+  const v = clean(value);
+  return v === CLOUDFLARE_FIXTURE_CLIENT_ID || v === CLOUDFLARE_FIXTURE_CLIENT_SECRET;
+}
+
+export function resolveCloudflareOAuthClient(env = {}) {
+  const clientId = clean(env.CLOUDFLARE_OAUTH_CLIENT_ID);
+  const clientSecret = clean(env.CLOUDFLARE_OAUTH_CLIENT_SECRET);
+  const present = Boolean(clientId && clientSecret);
+  const fixture = isFixtureCloudflareCredential(clientId) || isFixtureCloudflareCredential(clientSecret);
+  if (!present) {
+    return {
+      configured: false,
+      productionReady: false,
+      fixture: false,
+      status: 'not_configured',
+      clientIdConfigured: Boolean(clientId),
+      secretConfigured: Boolean(clientSecret),
+    };
+  }
+  return {
+    configured: true,
+    productionReady: !fixture,
+    fixture,
+    status: fixture ? 'fixture' : 'ready',
+    clientIdConfigured: true,
+    secretConfigured: true,
+  };
+}
+
+export function cloudflareConnectionSafeStatus(env = {}, connection = null, ownerId = '') {
+  const client = resolveCloudflareOAuthClient(env);
+  const record = connection && connection.ownerId === ownerId ? connection : null;
+  return {
+    provider: 'cloudflare',
+    status: record ? 'connected' : client.status === 'ready' ? 'ready' : client.status,
+    configured: client.configured && client.productionReady,
+    fixture: client.fixture,
+    clientId: client.clientIdConfigured ? 'configured' : 'missing',
+    secret: client.secretConfigured ? 'configured' : 'missing',
+    callbackPath: CLOUDFLARE_CALLBACK_PATH,
+    connection: record
+      ? {
+          connection_id: record.connectionId,
+          owner: record.ownerId,
+          cloudflare_account_id: record.cloudflareAccountId || null,
+          scopes: record.scopes || [],
+          status: record.status,
+          created_at: record.createdAt,
+          updated_at: record.updatedAt,
+          expires_at: record.expiresAt || null,
+        }
+      : null,
+  };
+}
+
+export function assertConnectionOwner(connection, ownerId) {
+  if (!ownerId) {
+    const err = new Error('unauthenticated');
+    err.code = 'unauthenticated';
+    throw err;
+  }
+  if (!connection || connection.ownerId !== ownerId) {
+    const err = new Error('cloudflare_connection_forbidden');
+    err.code = 'cloudflare_connection_forbidden';
+    throw err;
+  }
+  return connection;
+}
+
+export function buildAuthorizeUrl({ clientId, redirectUri, state, codeChallenge, scopes }) {
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+    scope: (scopes || requestedCloudflareScopes()).join(' '),
+  });
+  return `${CLOUDFLARE_OAUTH_AUTHORIZE_URL}?${params}`;
+}

package/packages/connectors/cloudflare/src/owner.js

@@ -0,0 +1,76 @@
+/**
+ * Cloudflare connection ownership is derived from authenticated AgentSam session.
+ * Browser-submitted account_id / user_id / owner_id / X-User-Id are never authority.
+ */
+
+const UNTRUSTED = new Set(['account_id', 'user_id', 'owner_id', 'workspace_id']);
+
+export function extractSessionToken(request) {
+  const auth = request.headers.get('authorization') || '';
+  if (/^bearer\s+/i.test(auth)) {
+    const token = auth.replace(/^bearer\s+/i, '').trim();
+    if (token && !token.startsWith('cf_') && token !== 'sillynotreal-secret') return token;
+  }
+  const cookie = request.headers.get('cookie') || '';
+  const match = cookie.match(/(?:^|;\s*)agentsam_session=([^;]+)/);
+  return match ? decodeURIComponent(match[1]).trim() : '';
+}
+
+export function rejectUntrustedOwnerHints(request, url, body = {}) {
+  const headerUser = (request.headers.get('x-user-id') || '').trim();
+  for (const key of UNTRUSTED) {
+    if (url.searchParams.get(key)) {
+      const err = new Error('untrusted_owner_hint');
+      err.code = 'untrusted_owner_hint';
+      throw err;
+    }
+    if (body && body[key]) {
+      const err = new Error('untrusted_owner_hint');
+      err.code = 'untrusted_owner_hint';
+      throw err;
+    }
+  }
+  // X-User-Id is vault v1 compatibility only and is never connector authority.
+  return { ignoredXUserId: Boolean(headerUser) };
+}
+
+export async function resolveAuthenticatedOwner(request, env, url, body) {
+  rejectUntrustedOwnerHints(request, url, body);
+  const sessionToken = extractSessionToken(request);
+  if (!sessionToken) {
+    const err = new Error('unauthenticated');
+    err.code = 'unauthenticated';
+    throw err;
+  }
+  if (env?.sessions instanceof Map) {
+    const owner = env.sessions.get(sessionToken);
+    if (!owner) {
+      const err = new Error('unauthenticated');
+      err.code = 'unauthenticated';
+      throw err;
+    }
+    return String(owner);
+  }
+  if (env?.DB?.prepare) {
+    const tables = [
+      ['agentsam_sessions', 'session_token', 'user_id'],
+      ['sessions', 'id', 'user_id'],
+      ['identity_sessions', 'session_token', 'user_id'],
+    ];
+    for (const [table, tokenCol, userCol] of tables) {
+      try {
+        const row = await env.DB.prepare(
+          `SELECT ${userCol} AS user_id FROM ${table} WHERE ${tokenCol} = ? LIMIT 1`,
+        )
+          .bind(sessionToken)
+          .first();
+        if (row?.user_id) return String(row.user_id);
+      } catch {
+        // table may not exist yet
+      }
+    }
+  }
+  const err = new Error('unauthenticated');
+  err.code = 'unauthenticated';
+  throw err;
+}