@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/packages/agentsam-vault/src/contracts/credential.js

@@ -0,0 +1,132 @@
+/**
+ * Portable AgentSam credential / vault contracts.
+ * Secrets never live on CredentialRecord — only credential_ref.
+ */
+
+/**
+ * @typedef {'user'|'account'|'app'} CredentialOwnerType
+ * @typedef {'provider_api_key'|'oauth_connection'|'agentsam_api_key'|'app_secret'} CredentialKind
+ * @typedef {'active'|'expired'|'revoked'|'invalid'} CredentialStatus
+ */
+
+/**
+ * @typedef {object} CredentialRecord
+ * @property {string} id
+ * @property {CredentialOwnerType} owner_type
+ * @property {string} owner_id
+ * @property {CredentialKind} kind
+ * @property {string} [provider]
+ * @property {string} label
+ * @property {string} credential_ref
+ * @property {CredentialStatus} status
+ * @property {string[]} [capabilities]
+ * @property {string[]} [granted_scopes]
+ * @property {string|null} [expires_at]
+ * @property {string|null} [validated_at]
+ * @property {string|null} [last_used_at]
+ * @property {string|null} [rotated_at]
+ * @property {string} [last4]
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} CredentialProviderField
+ * @property {string} id
+ * @property {'secret'|'text'|'url'} type
+ * @property {boolean} [required]
+ * @property {string} [label]
+ */
+
+/**
+ * @typedef {object} CredentialProviderDefinition
+ * @property {string} id
+ * @property {string} label
+ * @property {{ kind: CredentialKind, sensitive?: boolean }} credential
+ * @property {CredentialProviderField[]} fields
+ * @property {string[]} [capabilities]
+ * @property {{ test?: boolean, rotate?: boolean, revoke?: boolean }} [operations]
+ */
+
+export const CREDENTIAL_KINDS = Object.freeze({
+  PROVIDER_API_KEY: 'provider_api_key',
+  OAUTH_CONNECTION: 'oauth_connection',
+  AGENTSAM_API_KEY: 'agentsam_api_key',
+  APP_SECRET: 'app_secret',
+});
+
+export const CREDENTIAL_STATUSES = Object.freeze({
+  ACTIVE: 'active',
+  EXPIRED: 'expired',
+  REVOKED: 'revoked',
+  INVALID: 'invalid',
+});
+
+/**
+ * Authority lanes — do not conflate.
+ *
+ * VAULT_MASTER_KEY     encrypts BYOK / app secrets at rest (per Worker/app)
+ * AGENTSAM_API_KEY     aak_* delegated account API credential (IAM verifies hash)
+ * AGENTSAM_BRIDGE_KEY  machine↔Worker service auth (not a user credential)
+ * browser_oauth        interactive session cookie (not reusable API key)
+ */
+export const CREDENTIAL_AUTHORITY = Object.freeze({
+  vaultMasterKey: 'VAULT_MASTER_KEY',
+  agentsamApiKey: 'AGENTSAM_API_KEY',
+  agentsamApiKeyPrefix: 'aak_',
+  agentsamApiKeyStore: 'agentsam_api_credentials',
+  bridgeKey: 'AGENTSAM_BRIDGE_KEY',
+});
+
+/**
+ * @param {Partial<CredentialRecord> & Pick<CredentialRecord,'id'|'owner_type'|'owner_id'|'kind'|'label'|'credential_ref'|'status'|'created_at'|'updated_at'>} input
+ * @returns {CredentialRecord}
+ */
+export function normalizeCredentialRecord(input) {
+  if (!input?.id || !input.credential_ref) {
+    throw new Error('credential_record_requires_id_and_ref');
+  }
+  if (typeof input.credential_ref === 'string' && /^(sk-|sk_live_|AIza|ghp_|cf_|aak_)/i.test(input.credential_ref)) {
+    throw new Error('credential_ref_must_not_be_plaintext_secret');
+  }
+  return Object.freeze({
+    id: String(input.id),
+    owner_type: input.owner_type,
+    owner_id: String(input.owner_id),
+    kind: input.kind,
+    provider: input.provider ? String(input.provider) : undefined,
+    label: String(input.label || input.provider || input.kind),
+    credential_ref: String(input.credential_ref),
+    status: input.status || CREDENTIAL_STATUSES.ACTIVE,
+    capabilities: Array.isArray(input.capabilities) ? [...input.capabilities] : undefined,
+    granted_scopes: Array.isArray(input.granted_scopes) ? [...input.granted_scopes] : undefined,
+    expires_at: input.expires_at ?? null,
+    validated_at: input.validated_at ?? null,
+    last_used_at: input.last_used_at ?? null,
+    rotated_at: input.rotated_at ?? null,
+    last4: input.last4 || undefined,
+    created_at: String(input.created_at),
+    updated_at: String(input.updated_at),
+  });
+}
+
+/**
+ * @param {CredentialProviderDefinition} def
+ */
+export function defineCredentialProvider(def) {
+  if (!def?.id || !def?.label || !def?.credential?.kind) {
+    throw new Error('invalid_credential_provider');
+  }
+  return Object.freeze({
+    id: def.id,
+    label: def.label,
+    credential: Object.freeze({ ...def.credential }),
+    fields: Object.freeze((def.fields || []).map((f) => Object.freeze({ ...f }))),
+    capabilities: Object.freeze([...(def.capabilities || [])]),
+    operations: Object.freeze({
+      test: def.operations?.test !== false,
+      rotate: Boolean(def.operations?.rotate),
+      revoke: def.operations?.revoke !== false,
+    }),
+  });
+}

package/packages/agentsam-vault/src/crypto/aes-gcm.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Type declarations for `@inneranimalmedia/agentsam-vault/crypto`.
+ * Runtime stays plain JS (Workers + Node); this file is for TS consumers only.
+ */
+
+export function parseVaultMasterKeyBytes(rawMasterKey: string): Uint8Array;
+
+export function importVaultMasterKey(rawMasterKey: string): Promise<CryptoKey>;
+
+/** Mint `v1.<base64-32-bytes>` for wrangler secret put. */
+export function mintVaultMasterKeyV1(): string;
+
+export function encryptVaultSecret(
+  key: CryptoKey,
+  plaintext: string,
+  aad: string,
+): Promise<string>;
+
+export function decryptVaultSecret(
+  key: CryptoKey,
+  packedB64: string,
+  aad: string,
+): Promise<string>;
+
+export function last4(value: unknown): string;
+
+export function makeCredentialRef(input: {
+  backend?: string;
+  id: string;
+}): string;

package/packages/agentsam-vault/src/crypto/aes-gcm.js

@@ -0,0 +1,107 @@
+/**
+ * AES-256-GCM vault crypto.
+ * VAULT_MASTER_KEY must be an explicit versioned 32-byte key:
+ *   v1.<base64|base64url of exactly 32 bytes>
+ *
+ * No silent truncate / hash of arbitrary strings.
+ */
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+function b64ToBytes(b64) {
+  const normalized = String(b64).replace(/-/g, '+').replace(/_/g, '/');
+  const pad = normalized.length % 4 === 0 ? '' : '='.repeat(4 - (normalized.length % 4));
+  const bin = atob(normalized + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function bytesToB64(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+/**
+ * Parse VAULT_MASTER_KEY into raw 32 bytes.
+ * @param {string} rawMasterKey
+ * @returns {Uint8Array}
+ */
+export function parseVaultMasterKeyBytes(rawMasterKey) {
+  const raw = String(rawMasterKey || '').trim();
+  if (!raw) throw new Error('VAULT_MASTER_KEY_MISSING');
+  if (!raw.startsWith('v1.')) {
+    throw new Error(
+      'VAULT_MASTER_KEY_INVALID_FORMAT: expected v1.<base64-32-bytes> (generate: openssl rand -base64 32 | sed "s|^|v1.|")',
+    );
+  }
+  const payload = raw.slice(3);
+  let keyBytes;
+  try {
+    keyBytes = b64ToBytes(payload);
+  } catch {
+    throw new Error('VAULT_MASTER_KEY_INVALID_BASE64');
+  }
+  if (keyBytes.byteLength !== 32) {
+    throw new Error(
+      `VAULT_MASTER_KEY_INVALID_LENGTH: got ${keyBytes.byteLength} bytes, need exactly 32`,
+    );
+  }
+  return keyBytes;
+}
+
+/**
+ * @param {string} rawMasterKey
+ */
+export async function importVaultMasterKey(rawMasterKey) {
+  const keyBytes = parseVaultMasterKeyBytes(rawMasterKey);
+  return crypto.subtle.importKey('raw', keyBytes, { name: 'AES-GCM' }, false, [
+    'encrypt',
+    'decrypt',
+  ]);
+}
+
+/**
+ * Mint a new versioned master key string for wrangler secret put.
+ */
+export function mintVaultMasterKeyV1() {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return `v1.${bytesToB64(bytes)}`;
+}
+
+export async function encryptVaultSecret(key, plaintext, aad) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cipher = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(aad) },
+    key,
+    enc.encode(plaintext),
+  );
+  const packed = new Uint8Array(iv.byteLength + cipher.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(cipher), iv.byteLength);
+  return bytesToB64(packed);
+}
+
+export async function decryptVaultSecret(key, packedB64, aad) {
+  const packed = b64ToBytes(packedB64);
+  const iv = packed.slice(0, 12);
+  const data = packed.slice(12);
+  const plain = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(aad) },
+    key,
+    data,
+  );
+  return dec.decode(plain);
+}
+
+export function last4(value) {
+  const v = String(value ?? '');
+  if (!v) return '';
+  return v.length <= 4 ? '••••' : v.slice(-4);
+}
+
+export function makeCredentialRef({ backend = 'vault', id }) {
+  return `${backend}:${id}`;
+}

package/packages/agentsam-vault/src/crypto/oauth-envelope.js

@@ -0,0 +1,150 @@
+/**
+ * Portable OAuth-token envelope for user_oauth_tokens.
+ *
+ * Compatibility contract:
+ * - Key derivation exactly matches IAM backend/credentials/crypto-vault.js:
+ *   HKDF-SHA256, 16 zero-byte salt, info "iam-vault-v1", AES-256-GCM.
+ * - New rows are v2:<kid>:<base64(iv12 || ciphertext)> and REQUIRE AAD.
+ * - Unprefixed rows are legacy IAM ciphertext (same KDF, no AAD).
+ *
+ * This is intentionally separate from the app-secret vault format. App-local
+ * secrets and PKCE state do not need to be readable by another runtime.
+ */
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const HKDF_INFO = 'iam-vault-v1';
+const V2_PREFIX = 'v2:';
+
+function bytesToB64(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+function b64ToBytes(value) {
+  try {
+    const normalized = String(value || '').replace(/-/g, '+').replace(/_/g, '/');
+    const pad = normalized.length % 4 === 0 ? '' : '='.repeat(4 - (normalized.length % 4));
+    const bin = atob(normalized + pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i += 1) out[i] = bin.charCodeAt(i);
+    return out;
+  } catch {
+    throw vaultError('vault_unseal_failed', 'Invalid OAuth vault base64 payload');
+  }
+}
+
+function vaultError(code, message, extra = {}) {
+  const error = new Error(message || code);
+  error.code = code;
+  Object.assign(error, extra);
+  return error;
+}
+
+async function deriveOauthKey(material, usage = ['encrypt', 'decrypt']) {
+  const raw = String(material || '').trim();
+  if (!raw) throw vaultError('vault_required', 'VAULT_MASTER_KEY is required');
+  const base = await crypto.subtle.importKey('raw', enc.encode(raw), 'HKDF', false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array(16),
+      info: enc.encode(HKDF_INFO),
+    },
+    base,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    usage,
+  );
+}
+
+async function decryptPacked(key, packedB64, aad) {
+  const packed = b64ToBytes(packedB64);
+  if (packed.byteLength < 13) throw vaultError('vault_unseal_failed', 'invalid encrypted payload');
+  const iv = packed.slice(0, 12);
+  const ciphertext = packed.slice(12);
+  const params = { name: 'AES-GCM', iv };
+  if (aad != null) params.additionalData = enc.encode(String(aad));
+  try {
+    const plain = await crypto.subtle.decrypt(params, key, ciphertext);
+    return dec.decode(plain);
+  } catch {
+    throw vaultError('vault_unseal_failed', 'OAuth vault authentication failed');
+  }
+}
+
+export async function oauthKeyId(material) {
+  const raw = String(material || '').trim();
+  if (!raw) throw vaultError('vault_required', 'VAULT_MASTER_KEY is required');
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(raw)));
+  const hex = Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `k1-${hex.slice(0, 16)}`;
+}
+
+export function oauthAad(provider, userId, accountIdentifier) {
+  const p = String(provider || '').trim().toLowerCase();
+  const uid = String(userId || '').trim();
+  const account = String(accountIdentifier || '').trim();
+  if (!p || !uid || !account) {
+    throw vaultError('vault_aad_required', 'provider, userId, and accountIdentifier are required');
+  }
+  return `${p}:${uid}:${account}`;
+}
+
+export async function sealOauthToken(material, plaintext, aad) {
+  if (!String(aad || '')) throw vaultError('vault_aad_required', 'OAuth AAD is required');
+  const key = await deriveOauthKey(material, ['encrypt']);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(String(aad)) },
+    key,
+    enc.encode(String(plaintext ?? '')),
+  );
+  const packed = new Uint8Array(iv.byteLength + ciphertext.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(ciphertext), iv.byteLength);
+  const kid = await oauthKeyId(material);
+  return `${V2_PREFIX}${kid}:${bytesToB64(packed)}`;
+}
+
+export async function unsealOauthToken(material, blob, aad) {
+  const value = String(blob || '').trim();
+  if (!value) throw vaultError('vault_unseal_failed', 'OAuth vault payload is empty');
+  const key = await deriveOauthKey(material, ['decrypt']);
+
+  if (!value.startsWith(V2_PREFIX)) {
+    // Legacy IAM format: HKDF-derived AES-GCM with no AAD.
+    return decryptPacked(key, value, null);
+  }
+
+  const first = value.indexOf(':', V2_PREFIX.length);
+  if (first < 0) throw vaultError('vault_unseal_failed', 'Malformed v2 OAuth vault envelope');
+  const storedKid = value.slice(V2_PREFIX.length, first);
+  const packed = value.slice(first + 1);
+  const currentKid = await oauthKeyId(material);
+  if (storedKid !== currentKid) {
+    throw vaultError('vault_kid_mismatch', 'OAuth vault key id mismatch', {
+      storedKeyId: storedKid,
+      currentKeyId: currentKid,
+    });
+  }
+  if (!String(aad || '')) throw vaultError('vault_aad_required', 'OAuth AAD is required');
+  return decryptPacked(key, packed, String(aad));
+}
+
+/** Test/migration helper: emit the legacy IAM no-AAD format. */
+export async function sealLegacyIamOauthToken(material, plaintext) {
+  const key = await deriveOauthKey(material, ['encrypt']);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    enc.encode(String(plaintext ?? '')),
+  );
+  const packed = new Uint8Array(iv.byteLength + ciphertext.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(ciphertext), iv.byteLength);
+  return bytesToB64(packed);
+}

package/packages/agentsam-vault/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Package entry types for `@inneranimalmedia/agentsam-vault`.
+ * Re-exports crypto + contracts used by Local Studio / Worker consumers.
+ */
+
+export * from "./crypto/aes-gcm.js";
+export * from "./contracts/credential.js";
+
+export * from "./crypto/oauth-envelope.js";

package/packages/agentsam-vault/src/index.js

@@ -0,0 +1,27 @@
+export {
+  CREDENTIAL_KINDS,
+  CREDENTIAL_STATUSES,
+  CREDENTIAL_AUTHORITY,
+  normalizeCredentialRecord,
+  defineCredentialProvider,
+} from './contracts/credential.js';
+export { DEFAULT_CREDENTIAL_PROVIDERS, createProviderRegistry } from './providers/registry.js';
+export {
+  importVaultMasterKey,
+  parseVaultMasterKeyBytes,
+  mintVaultMasterKeyV1,
+  encryptVaultSecret,
+  decryptVaultSecret,
+  last4,
+  makeCredentialRef,
+} from './crypto/aes-gcm.js';
+export { createCredentialResolver } from './runtime/resolver.js';
+
+
+export {
+  oauthAad,
+  oauthKeyId,
+  sealOauthToken,
+  unsealOauthToken,
+  sealLegacyIamOauthToken,
+} from './crypto/oauth-envelope.js';

package/packages/agentsam-vault/src/providers/registry.js

@@ -0,0 +1,90 @@
+import { defineCredentialProvider, CREDENTIAL_KINDS } from '../contracts/credential.js';
+
+/** Provider registry — UI renders fields from this; no hardcoded dropdown lists. */
+export const DEFAULT_CREDENTIAL_PROVIDERS = Object.freeze([
+  defineCredentialProvider({
+    id: 'openai',
+    label: 'OpenAI',
+    credential: { kind: CREDENTIAL_KINDS.PROVIDER_API_KEY, sensitive: true },
+    fields: [{ id: 'api_key', type: 'secret', required: true, label: 'API key' }],
+    capabilities: ['models', 'chat', 'embeddings', 'responses'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'anthropic',
+    label: 'Anthropic',
+    credential: { kind: CREDENTIAL_KINDS.PROVIDER_API_KEY, sensitive: true },
+    fields: [{ id: 'api_key', type: 'secret', required: true, label: 'API key' }],
+    capabilities: ['models', 'chat'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'gemini',
+    label: 'Google Gemini',
+    credential: { kind: CREDENTIAL_KINDS.PROVIDER_API_KEY, sensitive: true },
+    fields: [{ id: 'api_key', type: 'secret', required: true, label: 'API key' }],
+    capabilities: ['models', 'chat', 'embeddings'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'cursor',
+    label: 'Cursor',
+    credential: { kind: CREDENTIAL_KINDS.PROVIDER_API_KEY, sensitive: true },
+    fields: [{ id: 'api_key', type: 'secret', required: true, label: 'API key' }],
+    capabilities: ['models', 'chat'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'xai',
+    label: 'xAI',
+    credential: { kind: CREDENTIAL_KINDS.PROVIDER_API_KEY, sensitive: true },
+    fields: [{ id: 'api_key', type: 'secret', required: true, label: 'API key' }],
+    capabilities: ['models', 'chat'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'cloudflare',
+    label: 'Cloudflare',
+    credential: { kind: CREDENTIAL_KINDS.OAUTH_CONNECTION, sensitive: true },
+    fields: [],
+    capabilities: ['workers', 'd1', 'r2', 'ai', 'dns'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'github',
+    label: 'GitHub',
+    credential: { kind: CREDENTIAL_KINDS.OAUTH_CONNECTION, sensitive: true },
+    fields: [],
+    capabilities: ['repos', 'actions'],
+    operations: { test: true, rotate: false, revoke: true },
+  }),
+  defineCredentialProvider({
+    id: 'agentsam',
+    label: 'AgentSam API key',
+    credential: { kind: CREDENTIAL_KINDS.AGENTSAM_API_KEY, sensitive: true },
+    fields: [{ id: 'api_key', type: 'secret', required: true, label: 'AGENTSAM_API_KEY (aak_…)' }],
+    capabilities: ['sdk', 'control_plane'],
+    operations: { test: true, rotate: true, revoke: true },
+  }),
+]);
+
+/**
+ * @param {import('../contracts/credential.js').CredentialProviderDefinition[]} [extra]
+ */
+export function createProviderRegistry(extra = []) {
+  const map = new Map();
+  for (const p of [...DEFAULT_CREDENTIAL_PROVIDERS, ...extra]) {
+    map.set(p.id, p);
+  }
+  return Object.freeze({
+    get(id) {
+      return map.get(String(id || '')) || null;
+    },
+    list() {
+      return [...map.values()];
+    },
+    listByKind(kind) {
+      return [...map.values()].filter((p) => p.credential.kind === kind);
+    },
+  });
+}

package/packages/agentsam-vault/src/runtime/resolver.js

@@ -0,0 +1,77 @@
+/**
+ * Resolve a usable secret for a capability — env is last-resort compatibility,
+ * not the product UX.
+ *
+ * Precedence (hosted Web Worker path):
+ *   1. explicit override
+ *   2. account vault (user_secrets unwrap via credential_ref)
+ *   3. permitted environment variable (provider adapter)
+ *   4. null
+ */
+
+/**
+ * @typedef {object} CredentialResolverOptions
+ * @property {(query: { provider: string, capability?: string }) => Promise<{ ref: string, last4?: string }|null>} [lookupVaultMeta]
+ * @property {(ref: string) => Promise<string|null>} [unwrap]
+ * @property {Record<string, string|undefined>} [env]
+ * @property {Record<string, string>} [envMap] provider → env var name
+ */
+
+const DEFAULT_ENV_MAP = Object.freeze({
+  openai: 'OPENAI_API_KEY',
+  anthropic: 'ANTHROPIC_API_KEY',
+  gemini: 'GEMINI_API_KEY',
+  cursor: 'CURSOR_API_KEY',
+  xai: 'XAI_API_KEY',
+  cloudflare: 'CLOUDFLARE_API_TOKEN',
+  agentsam: 'AGENTSAM_API_KEY',
+});
+
+/**
+ * @param {CredentialResolverOptions} options
+ */
+export function createCredentialResolver(options = {}) {
+  const envMap = { ...DEFAULT_ENV_MAP, ...(options.envMap || {}) };
+  const env = options.env || {};
+
+  return Object.freeze({
+    /**
+     * @param {{ provider: string, capability?: string, explicit?: string|null }} query
+     * @returns {Promise<{ source: 'explicit'|'vault'|'environment', value: string, last4?: string }|null>}
+     */
+    async resolve(query) {
+      const provider = String(query?.provider || '').trim().toLowerCase();
+      if (!provider) return null;
+
+      const explicit = String(query?.explicit || '').trim();
+      if (explicit) {
+        return { source: 'explicit', value: explicit, last4: explicit.slice(-4) };
+      }
+
+      if (typeof options.lookupVaultMeta === 'function' && typeof options.unwrap === 'function') {
+        const meta = await options.lookupVaultMeta({
+          provider,
+          capability: query.capability,
+        });
+        if (meta?.ref) {
+          const value = await options.unwrap(meta.ref);
+          if (value) {
+            return {
+              source: 'vault',
+              value,
+              last4: meta.last4 || value.slice(-4),
+            };
+          }
+        }
+      }
+
+      const envName = envMap[provider];
+      const fromEnv = envName ? String(env[envName] || '').trim() : '';
+      if (fromEnv) {
+        return { source: 'environment', value: fromEnv, last4: fromEnv.slice(-4) };
+      }
+
+      return null;
+    },
+  });
+}

package/packages/agentsam-workbench/README.md

@@ -0,0 +1,24 @@
+# @inneranimalmedia/agentsam-workbench
+
+Reusable React workbench primitives built on `@inneranimalmedia/agentsam-contracts`.
+
+This is the shared AgentSam UI layer for Local Studio, CAD Studio, and CMS Studio. It provides controlled/headless primitives for agent threads and composition, model selection, tool/artifact receipts, browser frames, terminal surfaces, and resizable shell panels. Product apps inject their own state, routing, auth, tools, runtime adapters, and visual treatment.
+
+Current proof consumer: `apps/local-studio/`. Local Studio now delegates its composer, thread scroll behavior, and split-handle behavior to this package while retaining product-specific styling and state.
+
+`packages/agentsam-shell-kit` remains only as a compatibility facade for older imports.
+# Floating annotation helper
+
+`MiniAgentSam` is exported from `@inneranimalmedia/agentsam-workbench/agent`.
+Import `@inneranimalmedia/agentsam-workbench/agent/mini-agentsam.css` once in the host.
+The host controls `selecting`, `onSelectingChange`, `onSubmit(prompt, selection)`,
+and an optional `renderComposer` slot. Use `scope()` to restrict selection to a
+particular root. No network, storage, plugin registry, or application dependency
+is built into the helper. It inherits `--nav-*` tokens; other hosts can supply
+`--mini-surface`, `--mini-text`, `--mini-muted`, `--mini-border`, and `--mini-accent`.
+
+Selections are bounded descriptive DOM context and never authorize edits. Input
+values are withheld. Cross-origin and sandboxed iframe contents are not inspected;
+their host frame may be selected as a contextual resource. Mark semantic ancestors
+with `data-agentsam-resource` and excluded controls with `data-annotation-control`.
+Local Studio stages the annotation in its active conversation draft for review.