@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.2

package/docs/AUTH_IDENTITY_CONTRACT.md

@@ -6,47 +6,45 @@ The `agentsam-sdk` package owns the portable public configuration contract. Cons
 
 | Variable | Meaning |
 | --- | --- |
-| `IAM_ORIGIN` | Canonical IAM authority and browser/OAuth/API origin. |
+| `IAM_OAUTH_ISSUER` | Canonical IAM authority/issuer for browser OAuth and platform account requests. |
+| `IAM_ORIGIN` | Migration fallback for the IAM issuer. New code resolves `IAM_OAUTH_ISSUER` first. |
 | `IAM_CLIENT_ID` | OAuth client id for an application using IAM identity. |
 | `IAM_CLIENT_SECRET` | OAuth client secret. Keep it server-side. |
-| `AGENTSAM_SDK_KEY` | Account/delegated SDK bearer. Raw values use the `sdk_` prefix and are sent as `Authorization: Bearer …`. |
-| `AGENTSAM_BRIDGE_KEY` | Machine/integration credential. It is never a substitute for user SDK authentication. |
+| `AGENTSAM_API_KEY` | Reusable account/delegated API credential. Raw values use the `aak_` prefix and are sent as `Authorization: Bearer …`. |
+| `AGENTSAM_BRIDGE_KEY` | Infrastructure/machine integration trust. It is never a substitute for account authentication. |
 
-The host-side durable verifier for SDK credentials is `agentsam_sdk_tokens`. The SDK defines the public credential semantics; the host owns the database and authorization implementation.
+The host-side durable verifier for reusable AgentSam API credentials is `agentsam_api_credentials`. The SDK defines the public credential semantics; the host owns credential issuance, hashing, storage, revocation, and authorization.
 
-`AGENTSAM_BRIDGE_KEY` remains the direct machine-secret environment variable. A host may additionally resolve a hashed credential from `agentsam_sdk_tokens` when that row has `token_type='integration'`. That does not turn the bridge credential into user authentication.
+Interactive browser login is intentionally separate from `AGENTSAM_API_KEY`. The CLI stores an opaque machine-local browser session under `~/.agentsam/auth/session.json`; it does not turn that session into a reusable API key.
 
 ## Migration compatibility
 
-The current migration window accepts two deprecated read fallbacks:
+The issuer resolver accepts `IAM_ORIGIN` only when `IAM_OAUTH_ISSUER` is absent. The retired `AGENTSAM_SDK_KEY`, `AGENTSAM_SDK_TOKEN`, `sdk_` bearer, and `agentsam_sdk_tokens` account-auth contract is not read by the current SDK.
 
-```text
-IAM_ORIGIN
-  fallback: IAM_OAUTH_ISSUER
-
-AGENTSAM_SDK_KEY
-  fallback: AGENTSAM_SDK_TOKEN
-```
-
-Canonical names always win when both are present. New scaffolds, docs, and writes emit only the canonical names. Compatibility aliases are intentionally not a permanent parallel configuration surface.
-
-Older platform-base aliases (`IAM_CORE_URL`, `AGENTSAM_CORE_URL`, `AGENTSAM_BASE_URL`) are compatibility-only. SDK clients prefer `IAM_ORIGIN`.
+Older platform-base aliases (`IAM_CORE_URL`, `AGENTSAM_CORE_URL`, `AGENTSAM_BASE_URL`) remain compatibility-only where legacy clients still consume them.
 
 ## Credential boundaries
 
 ```text
-human/account SDK lane
-  AGENTSAM_SDK_KEY
-    -> sdk_* bearer
-    -> Authorization: Bearer <sdk_*>
+reusable account API lane
+  AGENTSAM_API_KEY
+    -> aak_* bearer
+    -> Authorization: Bearer <aak_*>
     -> account/delegated authority
-    -> agentsam_sdk_tokens
+    -> agentsam_api_credentials (hashed verifier on the host)
+
+interactive browser lane
+  agentsam login
+    -> opaque browser session credential
+    -> ~/.agentsam/auth/session.json
+    -> interactive account authority
+    -> never rewritten as AGENTSAM_API_KEY
 
-machine/integration lane
-  AGENTSAM_BRIDGE_KEY
+machine/infrastructure lane
+  enrolled opaque machine credential / infrastructure bridge trust
     -> machine principal
-    -> no user/workspace identity injection
-    -> host env secret OR agentsam_sdk_tokens(token_type='integration')
+    -> server resolves connection -> instance -> account
+    -> never accepted as account API auth
 ```
 
-Browser OAuth uses `IAM_ORIGIN` together with `IAM_CLIENT_ID` and `IAM_CLIENT_SECRET`. Repository identity, workspace labels, or machine trust do not prove account authority.
+Repository identity, workspace labels, terminal instance ids, and machine trust do not prove reusable account authority. Provider credentials such as `OPENAI_API_KEY`, `GEMINI_API_KEY`, `CURSOR_API_KEY`, and Cloudflare credentials are managed separately by the machine provider-credential service.

package/docs/SDK_WORKER.md

@@ -47,16 +47,17 @@ agentsam-sdk
 ├─ AGENTSAM_WAI        -> Workers AI provider
 ├─ EXECOS              -> execos service binding
 ├─ PTY_SERVICE         -> iam-vpc VPC service
-├─ IAM_ORIGIN          -> https://inneranimalmedia.com
+├─ IAM_OAUTH_ISSUER    -> https://inneranimalmedia.com
+├─ IAM_ORIGIN          -> migration fallback
 ├─ IAM_CLIENT_ID       -> public OAuth client id
 ├─ IAM_CLIENT_SECRET   -> secret
-├─ AGENTSAM_SDK_KEY    -> secret
+├─ AGENTSAM_API_KEY    -> aak_ account credential (only when a reusable account credential is needed)
 └─ AGENTSAM_BRIDGE_KEY -> secret
 ```
 
 Hosted model credentials are secrets: `XAI_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. Grok model inference is the `XAI_API_KEY` provider lane and is independent from the pre-wired Grok gate viewer identity/session system.
 
-`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` and `AGENTSAM_SDK_TOKEN` are SDK 2.5 migration-read aliases only; new configuration uses `IAM_ORIGIN` and `AGENTSAM_SDK_KEY`.
+`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` is the canonical IAM authority; `IAM_ORIGIN` is a migration fallback. Reusable account API credentials use `AGENTSAM_API_KEY` with an `aak_` prefix. Browser login sessions and machine/infrastructure credentials remain separate and must not be promoted into account API keys.
 
 ## Ollama
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "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",

package/packages/identity/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-identity",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "private": true,
   "type": "module",
-  "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace — publish via root SDK)",
+  "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace \u2014 publish via root SDK)",
   "agentsam": {
     "system": "identity",
     "kind": "library",

package/packages/identity/src/contracts/auth-config.js

@@ -1,20 +1,9 @@
 /**
  * Canonical AgentSam identity/auth environment contract.
  *
- * The SDK owns these public names. Host applications consume this contract and
- * may provide storage/verification adapters without inventing competing aliases.
- *
- * Canonical variables:
- *   IAM_OAUTH_ISSUER      public authorization-server authority (issuer)
- *   IAM_CLIENT_ID         OAuth client id
- *   IAM_CLIENT_SECRET     OAuth client secret
- *   IAM_ORIGIN            deprecated alias of IAM_OAUTH_ISSUER (migration window)
- *   AGENTSAM_SDK_KEY      account/delegated sdk_* bearer
- *   AGENTSAM_BRIDGE_KEY   machine/integration credential
- *
- * Migration-only fallbacks:
- *   IAM_ORIGIN            -> IAM_OAUTH_ISSUER
- *   AGENTSAM_SDK_TOKEN    -> AGENTSAM_SDK_KEY
+ * Browser login sessions and reusable API credentials are intentionally
+ * separate: login sessions are opaque, machine-local session state while
+ * AGENTSAM_API_KEY is an explicit delegated account credential.
  */
 
 export const DEFAULT_IAM_OAUTH_ISSUER = 'https://inneranimalmedia.com';
@@ -26,17 +15,12 @@ export const AGENTSAM_AUTH_ENV = Object.freeze({
   iamOrigin: 'IAM_ORIGIN',
   iamClientId: 'IAM_CLIENT_ID',
   iamClientSecret: 'IAM_CLIENT_SECRET',
-  sdkKey: 'AGENTSAM_SDK_KEY',
+  apiKey: 'AGENTSAM_API_KEY',
   bridgeKey: 'AGENTSAM_BRIDGE_KEY',
 });
 
-export const AGENTSAM_AUTH_LEGACY_ENV = Object.freeze({
-  iamOrigin: 'IAM_ORIGIN',
-  sdkKey: 'AGENTSAM_SDK_TOKEN',
-});
-
 export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
-  version: 1,
+  version: 2,
   authority: 'agentsam-sdk',
   iam: Object.freeze({
     issuer: AGENTSAM_AUTH_ENV.iamIssuer,
@@ -44,24 +28,23 @@ export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
     clientId: AGENTSAM_AUTH_ENV.iamClientId,
     clientSecret: AGENTSAM_AUTH_ENV.iamClientSecret,
   }),
-  sdk: Object.freeze({
-    env: AGENTSAM_AUTH_ENV.sdkKey,
-    tokenPrefix: 'sdk_',
+  apiKey: Object.freeze({
+    env: AGENTSAM_AUTH_ENV.apiKey,
+    tokenPrefix: 'aak_',
     authorizationScheme: 'Bearer',
     subject: 'account/delegated',
-    durableStore: 'agentsam_sdk_tokens',
+    durableStore: 'agentsam_api_credentials',
+  }),
+  browserSession: Object.freeze({
+    storage: '~/.agentsam/auth/session.json',
+    subject: 'interactive/user',
+    reusableApiCredential: false,
   }),
   bridge: Object.freeze({
     env: AGENTSAM_AUTH_ENV.bridgeKey,
     subject: 'machine/integration',
-    sdkTokenType: 'integration',
     userAuth: false,
   }),
-  compatibility: Object.freeze({
-    iamOriginFallback: AGENTSAM_AUTH_LEGACY_ENV.iamOrigin,
-    iamIssuerCanonical: AGENTSAM_AUTH_ENV.iamIssuer,
-    sdkKeyFallback: AGENTSAM_AUTH_LEGACY_ENV.sdkKey,
-  }),
 });
 
 function clean(value) {
@@ -84,24 +67,24 @@ export function resolveIamOrigin(env = {}, explicit = '') {
   return resolveIamIssuer(env, explicit);
 }
 
-/** Resolve account/delegated SDK bearer; canonical name wins over legacy. */
-export function resolveSdkKey(env = {}, explicit = '') {
-  return clean(explicit || env?.AGENTSAM_SDK_KEY || env?.AGENTSAM_SDK_TOKEN);
+/** Resolve the reusable delegated account API credential. */
+export function resolveApiKey(env = {}, explicit = '') {
+  return clean(explicit || env?.AGENTSAM_API_KEY);
 }
 
-/** Resolve machine/integration bridge credential. No user-SDK alias is accepted. */
+/** Resolve machine/integration bridge credential. No account API-key alias is accepted. */
 export function resolveBridgeKey(env = {}, explicit = '') {
   return clean(explicit || env?.AGENTSAM_BRIDGE_KEY);
 }
 
-export function isSdkKey(value) {
-  return clean(value).startsWith(AGENTSAM_AUTH_CONTRACT.sdk.tokenPrefix);
+export function isApiKey(value) {
+  return clean(value).startsWith(AGENTSAM_AUTH_CONTRACT.apiKey.tokenPrefix);
 }
 
-/** Build the public bearer header for an SDK key. */
-export function buildSdkAuthorizationHeaders(key, headers = {}) {
+/** Build the public bearer header for an AgentSam account API key. */
+export function buildApiAuthorizationHeaders(key, headers = {}) {
   const resolved = clean(key);
-  if (!isSdkKey(resolved)) throw new Error('AGENTSAM_SDK_KEY_required');
+  if (!isApiKey(resolved)) throw new Error('AGENTSAM_API_KEY_required');
   return {
     ...headers,
     Authorization: `Bearer ${resolved}`,

package/packages/identity/tests/auth-config.test.mjs

@@ -2,10 +2,10 @@ import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import {
   AGENTSAM_AUTH_CONTRACT,
-  buildSdkAuthorizationHeaders,
+  buildApiAuthorizationHeaders,
+  resolveApiKey,
   resolveBridgeKey,
   resolveIamOrigin,
-  resolveSdkKey,
 } from '../src/contracts/auth-config.js';
 
 describe('auth configuration contract', () => {
@@ -20,42 +20,33 @@ describe('auth configuration contract', () => {
   });
 
   it('accepts IAM_ORIGIN as migration-only fallback', () => {
-    assert.equal(
-      resolveIamOrigin({ IAM_ORIGIN: 'https://legacy.example.test/' }),
-      'https://legacy.example.test',
-    );
+    assert.equal(resolveIamOrigin({ IAM_ORIGIN: 'https://legacy.example.test/' }), 'https://legacy.example.test');
   });
 
   it('defaults issuer when neither IAM_OAUTH_ISSUER nor IAM_ORIGIN exists', () => {
     assert.equal(resolveIamOrigin({}), 'https://inneranimalmedia.com');
   });
 
-  it('prefers AGENTSAM_SDK_KEY over AGENTSAM_SDK_TOKEN', () => {
-    assert.equal(
-      resolveSdkKey({
-        AGENTSAM_SDK_KEY: 'sdk_new',
-        AGENTSAM_SDK_TOKEN: 'sdk_old',
-      }),
-      'sdk_new',
-    );
-    assert.equal(resolveSdkKey({ AGENTSAM_SDK_TOKEN: 'sdk_old' }), 'sdk_old');
+  it('resolves only AGENTSAM_API_KEY for delegated account API auth', () => {
+    assert.equal(resolveApiKey({ AGENTSAM_API_KEY: 'aak_new' }), 'aak_new');
+    assert.equal(resolveApiKey({ AGENTSAM_SDK_KEY: 'sdk_old' }), '');
+    assert.equal(AGENTSAM_AUTH_CONTRACT.apiKey.durableStore, 'agentsam_api_credentials');
   });
 
-  it('never aliases bridge machine trust to a user SDK key', () => {
+  it('never aliases bridge machine trust to an account API key', () => {
     assert.equal(
-      resolveBridgeKey({ AGENTSAM_BRIDGE_KEY: 'bridge_machine', AGENTSAM_SDK_KEY: 'sdk_user' }),
+      resolveBridgeKey({ AGENTSAM_BRIDGE_KEY: 'bridge_machine', AGENTSAM_API_KEY: 'aak_user' }),
       'bridge_machine',
     );
-    assert.equal(resolveBridgeKey({ AGENTSAM_SDK_KEY: 'sdk_user' }), '');
+    assert.equal(resolveBridgeKey({ AGENTSAM_API_KEY: 'aak_user' }), '');
     assert.equal(AGENTSAM_AUTH_CONTRACT.bridge.userAuth, false);
-    assert.equal(AGENTSAM_AUTH_CONTRACT.bridge.sdkTokenType, 'integration');
   });
 
-  it('builds Bearer authorization only for sdk_ keys', () => {
-    assert.deepEqual(buildSdkAuthorizationHeaders('sdk_abc', { Accept: 'application/json' }), {
+  it('builds Bearer authorization only for aak_ API keys', () => {
+    assert.deepEqual(buildApiAuthorizationHeaders('aak_abc', { Accept: 'application/json' }), {
       Accept: 'application/json',
-      Authorization: 'Bearer sdk_abc',
+      Authorization: 'Bearer aak_abc',
     });
-    assert.throws(() => buildSdkAuthorizationHeaders('bridge_machine'), /AGENTSAM_SDK_KEY_required/);
+    assert.throws(() => buildApiAuthorizationHeaders('bridge_machine'), /AGENTSAM_API_KEY_required/);
   });
 });

package/src/cli.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import pkg from '../package.json' with { type: 'json' };
-import readline from 'readline';
 import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
 import path from 'node:path';
 import { buildLocalScaffoldMeta } from './lib/local-scaffold.js';
@@ -9,10 +8,10 @@ import { writeScaffoldFiles } from './lib/write-files.js';
 import { initializeGitRepository } from './lib/init-git.js';
 import { initializeLocalSqlite } from './local/sqlite.js';
 import { printContextSummary } from './lib/detect-context.js';
-import { promptOptionalByokKeys } from './lib/prompt-byok.js';
 import { runStartLocal } from './commands/start-local.js';
 import { runOllama } from './commands/ollama.js';
 import { runModels } from './commands/models.js';
+import { runProviders } from './commands/providers.js';
 import { runEnv } from './commands/env.js';
 import { runTunnel } from './commands/tunnel.js';
 import { runDeploy } from './commands/deploy.js';
@@ -41,7 +40,7 @@ import { applyPresetSelection, runAdd, runCapabilities, runDev, runInspect } fro
 import { listPresets, resolvePreset } from './presets/index.js';
 import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
-import { resolveAccountSdkKey } from './lib/account-session.js';
+import { resolveAccountAuth } from './lib/account-session.js';
 import { renderDiagnosticError } from './errors/index.js';
 import { renderHelpOverview, runHelp } from './ui/cli/help.js';
 
@@ -53,13 +52,6 @@ function reportCliError(error) {
   console.error(`\n${rendered}\n`);
 }
 
-function createPrompt() {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return {
-    ask: (q) => new Promise((resolve) => rl.question(q, resolve)),
-    close: () => rl.close(),
-  };
-}
 
 function printHelp() {
   console.log(renderHelpOverview(VERSION));
@@ -96,6 +88,7 @@ function printLegacyHelp() {
     agentsam status [--json]   Live local Git + DB + API + PTY status
     agentsam db init|status    Manage the project-local SQLite database
     agentsam models            Verify configured providers and selectable hosted/local models
+    agentsam providers         Configure, verify, and remove machine provider credentials
     agentsam env init <name>   Create a secure provider profile + reusable shell loader
     agentsam login             Sign in to Inner Animal Media and persist a secure machine-local session
     agentsam logout            Sign out locally; provider credentials stay untouched
@@ -142,7 +135,7 @@ function printLegacyHelp() {
     --quick                    Quick tunnel (default) — trycloudflare.com URL
     --named                    Named CF tunnel (needs --tunnel-name --hostname --zone-id)
     --port <n>                 Local PTY port (default 3099)
-    --token <sdk_…>            Use existing AGENTSAM_SDK_KEY (skip browser auth)
+    --token <aak_…>            Use AGENTSAM_API_KEY-compatible account credential
 
   Init options:
     --name <name>              Project directory name
@@ -235,11 +228,6 @@ async function runLocalInit(config) {
     console.log(`    ${step}`);
   }
 
-  const sdkKey = resolveAccountSdkKey({ env: process.env }).value;
-  if (prompt && sdkKey) {
-    console.log('\n  Optional — BYOK keys for IAM dashboard Agent Sam (skip with Enter):\n');
-    await promptOptionalByokKeys(sdkKey, prompt);
-  }
 
   console.log(`
   Local means local: no Worker, tunnel, IAM login, or cloud database is required.
@@ -291,17 +279,12 @@ async function initInteractive(partial = {}) {
   if (runTarget !== 'local') {
     const { detectContext, missingForInit } = await import('./lib/detect-context.js');
     const ctx = await detectContext();
-    if (missingForInit(ctx, resolveAccountSdkKey({ env: process.env }).value, { runTarget }).length) {
+    if (missingForInit(ctx, resolveAccountAuth({ env: process.env }).value, { runTarget }).length) {
       printContextSummary(ctx);
     }
   }
 
-  const prompt = resolveAccountSdkKey({ env: process.env }).value ? createPrompt() : null;
-  try {
-    await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
-  } finally {
-    prompt?.close();
-  }
+  await runLocalInit({ projectName, lane: laneKey, runTarget, prompt: null });
   outro(`Created ${projectName}`);
 }
 
@@ -387,6 +370,13 @@ if (command === '--version' || command === '-v') {
     reportCliError(e);
     process.exit(1);
   }
+} else if (command === 'providers') {
+  try {
+    await runProviders(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exit(1);
+  }
 } else if (command === 'env') {
   try {
     await runEnv(rest);

package/src/commands/account-auth.js

@@ -11,7 +11,7 @@ export async function runLogin(argv = [], options = {}) {
   const write = options.write || ((text) => process.stdout.write(text));
   const authenticate = options.authenticateImpl || authenticateViaBrowser;
   const session = await authenticate();
-  if (!String(session?.access_token || '').trim().startsWith('sdk_')) throw new Error('Agent Sam login did not return a valid SDK session');
+  if (!String(session?.access_token || '').trim()) throw new Error('Agent Sam login did not return a browser session credential');
   // authenticateViaBrowser persists by default. Keep injected transports/test flows equivalent.
   if (!readAccountSession({ home: options.home })) saveAccountSession(session, { home: options.home });
   const status = await collectWhoami({ home: options.home, env: options.env || process.env, contextLoader: options.contextLoader });

package/src/commands/deploy.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { authenticateViaBrowser } from '../lib/auth.js';
 import { getJson, streamScaffold } from '../lib/core-client.js';
-import { resolveAccountSdkKey } from '../lib/account-session.js';
+import { resolveAccountAuth } from '../lib/account-session.js';
 import { getDefaultProfile, getDeployTarget, getLocalSchemaPath, getProjectName, getProjectPreset, readProjectConfig, setDeployTarget, writeProjectConfig } from '../lib/project-config.js';
 import { isLocalStudioCheckout, runLocalStudioDeploy } from '../lib/deploy/local-studio.js';
 
@@ -68,7 +68,7 @@ function ask(question) {
 async function runCloudflareDeploy(cwd, config, accountId) {
   console.log('\n  Cloudflare deploy — browser sign-in + resource provisioning…\n');
 
-  let token = resolveAccountSdkKey({ env: process.env }).value;
+  let token = resolveAccountAuth({ env: process.env }).value;
   if (!token) {
     const session = await authenticateViaBrowser();
     token = session.access_token;