@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/src/lib/provider-credentials.js

@@ -129,28 +129,17 @@ export function agentEnvLoaderPath(options = {}) {
 
 export function ensureAgentEnvLoader(options = {}) {
   const filename = agentEnvLoaderPath(options);
-  const supported = Object.keys(PROVIDER_CREDENTIALS).join('|');
-  const source = `# AgentSam provider environment loader. Source this file; do not execute it.
-if [ "$#" -eq 0 ]; then
-  echo "usage: source ~/.agentsam/load-agent-env.sh <profile> [profile ...]" >&2
-  return 2 2>/dev/null || exit 2
+  const source = `# AgentSam environment loader. Source this file; do not execute it.
+# Credentials resolve from the OS keychain / local vault via \`agentsam env shell\`.
+# Do not put plaintext secrets in this file.
+if command -v agentsam >/dev/null 2>&1; then
+  eval "$(agentsam env shell --profile default)"
+elif command -v agentsam-env >/dev/null 2>&1; then
+  eval "$(agentsam-env shell --profile default)"
+else
+  echo "agentsam CLI not found on PATH; cannot load AgentSam credentials" >&2
+  return 1 2>/dev/null || exit 1
 fi
-for _agentsam_profile in "$@"; do
-  case "$_agentsam_profile" in
-    grok) _agentsam_profile="xai" ;;
-    ${supported}) ;;
-    *) echo "unknown AgentSam provider profile: $_agentsam_profile" >&2; return 2 2>/dev/null || exit 2 ;;
-  esac
-  _agentsam_file="\${HOME}/.agentsam/env.d/\${_agentsam_profile}.env"
-  if [ ! -f "$_agentsam_file" ]; then
-    echo "AgentSam provider profile not found: $_agentsam_file" >&2
-    return 1 2>/dev/null || exit 1
-  fi
-  set -a
-  . "$_agentsam_file"
-  set +a
-done
-unset _agentsam_file _agentsam_profile
 `;
   atomicWrite(filename, source, 0o700);
   return filename;
@@ -359,3 +348,56 @@ export function describeProviderCredential(provider, options = {}) {
 export function listProviderCredentialStatus(options = {}) {
   return Object.freeze(Object.keys(PROVIDER_CREDENTIALS).map((provider) => describeProviderCredential(provider, options)));
 }
+
+/**
+ * Emit shell `export` lines for configured credentials from vault/keychain/env.
+ * Bootstrap-safe: does not require AGENTSAM_API_KEY already present to resolve it.
+ * Prefer vault/OS store over ambient env when `preferVault` is true (default for shell).
+ */
+export function renderEnvShellExports(options = {}) {
+  const profile = clean(options.profile || 'default').toLowerCase();
+  const wanted = Array.isArray(options.providers) && options.providers.length
+    ? options.providers.map(normalizeProviderId).filter(Boolean)
+    : profile === 'default'
+      ? Object.keys(PROVIDER_CREDENTIALS)
+      : profile.split(/[,\s]+/).map(normalizeProviderId).filter(Boolean);
+
+  const lines = ['# AgentSam env shell — evaluated by: eval "$(agentsam env shell)"'];
+  const emitted = [];
+
+  for (const provider of wanted) {
+    const spec = providerCredentialSpec(provider);
+    if (!spec) continue;
+
+    let resolved;
+    if (options.preferVault !== false) {
+      // Skip ambient process.env so a stale empty shell does not block keychain.
+      const vaultOnly = { ...options, env: { ...(options.env || {}), [spec.env]: undefined } };
+      if (spec.accountEnv) {
+        for (const name of spec.accountEnv) vaultOnly.env[name] = undefined;
+      }
+      resolved = resolveProviderCredential(spec.provider, vaultOnly);
+      if (!resolved.configured) {
+        resolved = resolveProviderCredential(spec.provider, options);
+      }
+    } else {
+      resolved = resolveProviderCredential(spec.provider, options);
+    }
+
+    if (!resolved.configured || !resolved.value) continue;
+    lines.push(`export ${spec.env}=${envLiteral(resolved.value)}`);
+    if (spec.provider === 'cloudflare' && resolved.account_id) {
+      lines.push(`export CLOUDFLARE_ACCOUNT_ID=${envLiteral(resolved.account_id)}`);
+    }
+    emitted.push(spec.provider);
+  }
+
+  if (!emitted.length) {
+    lines.push('# No AgentSam credentials configured. Run: agentsam api-key create --store keychain --activate');
+  }
+  return Object.freeze({
+    profile,
+    providers: emitted,
+    script: `${lines.join('\n')}\n`,
+  });
+}

package/src/lib/slash-commands.js

@@ -35,6 +35,7 @@ export const SLASH_COMMANDS = [
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
   { cmd: '/clear', description: 'Clear the terminal display', lane: 'terminal' },
+  { cmd: '/skills', description: 'List resolvable slash skill vocabulary', lane: 'agent' },
   { cmd: '/help', description: 'Show the factual implemented command catalog' },
   { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];

package/src/local-fs/capability.js

@@ -0,0 +1,121 @@
+/**
+ * Local runtime workspace capability — short-lived FS/PTY authority for one root.
+ *
+ * Compatible with later:
+ *   account → terminal connection → enrolled instance → approved workspace root
+ *
+ * Local today:
+ *   start-local binds one root + mints one capability.
+ *   Browser cannot invent an absolute root to gain authority.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const WORKSPACE_CAPABILITY_HEADER = 'x-agentsam-workspace-capability';
+export const LOCAL_RUNTIME_FILE = 'local-runtime.json';
+
+/**
+ * @param {{ root: string, port: number, host?: string }} opts
+ */
+export function mintWorkspaceCapability(opts) {
+  const root = path.resolve(opts.root);
+  const workspace_id = `ws_${crypto.randomBytes(10).toString('hex')}`;
+  const capability = `awc_${crypto.randomBytes(24).toString('hex')}`;
+  const expires_at = new Date(Date.now() + 12 * 60 * 60 * 1000).toISOString();
+  return Object.freeze({
+    schema: 'agentsam.local-workspace-capability.v1',
+    workspace_id,
+    capability,
+    root,
+    host: opts.host || '127.0.0.1',
+    port: opts.port,
+    runtimeBaseUrl: `http://${opts.host || '127.0.0.1'}:${opts.port}`,
+    fsBaseUrl: `http://${opts.host || '127.0.0.1'}:${opts.port}/v1/fs`,
+    expires_at,
+    purpose: 'local.filesystem+pty',
+  });
+}
+
+/**
+ * Persist capability beside the authorized root (machine-local; not file content authority).
+ * @param {object} record
+ */
+export function writeLocalRuntimeRecord(record) {
+  const dir = path.join(record.root, '.agentsam');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, LOCAL_RUNTIME_FILE);
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}
+
+/**
+ * @param {string} root
+ */
+export function readLocalRuntimeRecord(root) {
+  const file = path.join(path.resolve(root), '.agentsam', LOCAL_RUNTIME_FILE);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {string} expected
+ */
+export function extractCapability(req, expected) {
+  const header = req.headers[WORKSPACE_CAPABILITY_HEADER]
+    || req.headers.authorization
+    || '';
+  let token = '';
+  if (typeof header === 'string') {
+    if (header.toLowerCase().startsWith('bearer ')) token = header.slice(7).trim();
+    else token = header.trim();
+  }
+  if (!token && req.url) {
+    try {
+      const u = new URL(req.url, 'http://127.0.0.1');
+      token = u.searchParams.get('capability') || '';
+    } catch {
+      /* ignore */
+    }
+  }
+  return {
+    ok: Boolean(expected && token && token === expected),
+    token,
+  };
+}
+
+/**
+ * Loopback + Studio origin allowlist. Never `*`.
+ * @param {string|undefined} origin
+ * @param {string[]} [extra]
+ */
+export function isAllowedStudioOrigin(origin, extra = []) {
+  if (!origin || origin === 'null') return true; // non-browser / same-origin tooling
+  const allow = [
+    'http://127.0.0.1:8080',
+    'http://localhost:8080',
+    'http://127.0.0.1:5173',
+    'http://localhost:5173',
+    'http://127.0.0.1:3000',
+    'http://localhost:3000',
+    ...extra,
+  ];
+  return allow.includes(origin);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ */
+export function isLoopbackRemote(req) {
+  const raw = req.socket?.remoteAddress || '';
+  return raw === '127.0.0.1'
+    || raw === '::1'
+    || raw === '::ffff:127.0.0.1'
+    || raw.endsWith('127.0.0.1');
+}

package/src/local-fs/freshness.js

@@ -0,0 +1,75 @@
+/**
+ * Minimal repository/index freshness bridge.
+ * Filesystem writes mark generation stale — do not re-index on every keystroke.
+ */
+
+/** @type {Map<string, { generation: number, stale_paths: Set<string>, updated_at: string }>} */
+const roots = new Map();
+
+/**
+ * @param {string} root
+ * @param {{ paths?: string[], reason?: string }} [opts]
+ */
+export function markRepositoryStale(root, opts = {}) {
+  const key = String(root);
+  const prev = roots.get(key) || {
+    generation: 0,
+    stale_paths: new Set(),
+    updated_at: null,
+  };
+  const nextGen = prev.generation + 1;
+  const stale_paths = new Set(prev.stale_paths);
+  for (const p of opts.paths || []) stale_paths.add(String(p));
+  const record = {
+    generation: nextGen,
+    stale_paths,
+    updated_at: new Date().toISOString(),
+    reason: opts.reason || 'filesystem_write',
+  };
+  roots.set(key, record);
+  return {
+    ok: true,
+    schema: 'agentsam.repository-freshness.v1',
+    root: key,
+    generation: record.generation,
+    stale_paths: [...stale_paths].slice(0, 200),
+    updated_at: record.updated_at,
+    reason: record.reason,
+  };
+}
+
+/**
+ * @param {string} root
+ */
+export function getRepositoryFreshness(root) {
+  const key = String(root);
+  const record = roots.get(key);
+  if (!record) {
+    return {
+      ok: true,
+      schema: 'agentsam.repository-freshness.v1',
+      root: key,
+      generation: 0,
+      stale: false,
+      stale_paths: [],
+    };
+  }
+  return {
+    ok: true,
+    schema: 'agentsam.repository-freshness.v1',
+    root: key,
+    generation: record.generation,
+    stale: record.stale_paths.size > 0 || record.generation > 0,
+    stale_paths: [...record.stale_paths].slice(0, 200),
+    updated_at: record.updated_at,
+    reason: record.reason,
+  };
+}
+
+/**
+ * @param {string} root
+ */
+export function clearRepositoryFreshness(root) {
+  roots.delete(String(root));
+  return { ok: true };
+}

package/src/local-fs/index.js

@@ -0,0 +1,385 @@
+/**
+ * Local machine filesystem operations under an authorized workspace root.
+ * Version = sha256 of file bytes (content-addressed optimistic concurrency).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveContainedPath } from './paths.js';
+import { markRepositoryStale } from './freshness.js';
+
+export const LOCAL_FS_ENGINE = 'agentsam-local-fs-v1';
+export const MAX_TEXT_BYTES = 2 * 1024 * 1024; // 2 MiB text default
+
+/**
+ * @param {string} root
+ */
+export function createLocalFilesystem(root) {
+  const resolvedRoot = path.resolve(root);
+
+  function contain(rel) {
+    return resolveContainedPath(resolvedRoot, rel);
+  }
+
+  function hashBytes(buf) {
+    return `sha256:${crypto.createHash('sha256').update(buf).digest('hex')}`;
+  }
+
+  /**
+   * @param {string} relPath
+   * @param {{ recursive?: boolean, maxDepth?: number }} [opts]
+   */
+  function list(relPath = '.', opts = {}) {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    const recursive = Boolean(opts.recursive);
+    const maxDepth = opts.maxDepth ?? 6;
+    /** @type {Array<{ path: string, kind: string, size: number, mtime: number }>} */
+    const items = [];
+    const skip = new Set(['.git', 'node_modules', '.output', 'dist', '.DS_Store']);
+
+    /**
+     * @param {string} abs
+     * @param {string} rel
+     * @param {number} depth
+     */
+    function walk(abs, rel, depth) {
+      let entries;
+      try {
+        entries = fs.readdirSync(abs, { withFileTypes: true });
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'list_failed',
+        };
+      }
+      for (const e of entries) {
+        if (skip.has(e.name) || e.name === '.DS_Store') continue;
+        const childRel = rel === '.' ? e.name : `${rel}/${e.name}`;
+        const childAbs = path.join(abs, e.name);
+        let size = 0;
+        let mtime = 0;
+        try {
+          const st = fs.lstatSync(childAbs);
+          size = st.size;
+          mtime = Math.floor(st.mtimeMs);
+        } catch {
+          /* ignore */
+        }
+        const kind = e.isDirectory() ? 'directory' : e.isSymbolicLink() ? 'symlink' : 'file';
+        items.push({ path: childRel, kind, size, mtime });
+        if (recursive && kind === 'directory' && depth < maxDepth) {
+          const nested = walk(childAbs, childRel, depth + 1);
+          if (nested && nested.ok === false) return nested;
+        }
+      }
+      return { ok: true };
+    }
+
+    const walked = walk(gate.abs, gate.rel, 0);
+    if (walked && walked.ok === false) return walked;
+
+    items.sort((a, b) => {
+      if (a.kind !== b.kind) return a.kind === 'directory' ? -1 : 1;
+      return a.path.localeCompare(b.path);
+    });
+    return { ok: true, root: resolvedRoot, path: gate.rel, entries: items, engine: LOCAL_FS_ENGINE };
+  }
+
+  /**
+   * @param {string} relPath
+   */
+  function stat(relPath) {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    try {
+      const st = fs.lstatSync(gate.abs);
+      const kind = st.isDirectory() ? 'directory' : st.isSymbolicLink() ? 'symlink' : 'file';
+      let content_hash = null;
+      if (kind === 'file' && st.size <= MAX_TEXT_BYTES) {
+        content_hash = hashBytes(fs.readFileSync(gate.abs));
+      }
+      return {
+        ok: true,
+        path: gate.rel,
+        kind,
+        size: st.size,
+        mtime: Math.floor(st.mtimeMs),
+        content_hash,
+        binary: kind === 'file' && st.size > 0 ? null : false,
+        engine: LOCAL_FS_ENGINE,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'stat_failed',
+      };
+    }
+  }
+
+  /**
+   * @param {string} relPath
+   * @param {{ maxBytes?: number }} [opts]
+   */
+  function read(relPath, opts = {}) {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    const maxBytes = opts.maxBytes ?? MAX_TEXT_BYTES;
+    try {
+      const st = fs.statSync(gate.abs);
+      if (st.isDirectory()) {
+        return { ok: false, error: 'is_directory', code: 'is_directory' };
+      }
+      if (st.size > maxBytes) {
+        return {
+          ok: false,
+          error: `file_too_large:${st.size}>${maxBytes}`,
+          code: 'file_too_large',
+          size: st.size,
+        };
+      }
+      const buf = fs.readFileSync(gate.abs);
+      // Detect obvious binary
+      const sample = buf.subarray(0, Math.min(buf.length, 8000));
+      if (sample.includes(0)) {
+        return {
+          ok: false,
+          error: 'binary_file',
+          code: 'binary_file',
+          size: st.size,
+          content_hash: hashBytes(buf),
+        };
+      }
+      const content = buf.toString('utf8');
+      const version = hashBytes(buf);
+      return {
+        ok: true,
+        path: gate.rel,
+        content,
+        version,
+        content_hash: version,
+        mtime: Math.floor(st.mtimeMs),
+        size: st.size,
+        engine: LOCAL_FS_ENGINE,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'read_failed',
+      };
+    }
+  }
+
+  /**
+   * Atomic write with optional optimistic concurrency (expectedVersion).
+   * @param {string} relPath
+   * @param {string} content
+   * @param {{ expectedVersion?: string|null, overwrite?: boolean }} [opts]
+   */
+  function write(relPath, content, opts = {}) {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    if (typeof content !== 'string') {
+      return { ok: false, error: 'content_must_be_string', code: 'invalid_input' };
+    }
+    const buf = Buffer.from(content, 'utf8');
+    if (buf.length > MAX_TEXT_BYTES) {
+      return { ok: false, error: 'content_too_large', code: 'file_too_large' };
+    }
+
+    const exists = fs.existsSync(gate.abs);
+    if (exists) {
+      const current = fs.readFileSync(gate.abs);
+      const currentVersion = hashBytes(current);
+      if (opts.expectedVersion != null && opts.expectedVersion !== '' && opts.expectedVersion !== currentVersion) {
+        if (!opts.overwrite) {
+          return {
+            ok: false,
+            error: 'version_conflict',
+            code: 'version_conflict',
+            expected: opts.expectedVersion,
+            actual: currentVersion,
+            path: gate.rel,
+          };
+        }
+      }
+    } else if (opts.expectedVersion) {
+      return {
+        ok: false,
+        error: 'version_conflict',
+        code: 'version_conflict',
+        expected: opts.expectedVersion,
+        actual: null,
+        path: gate.rel,
+      };
+    }
+
+    try {
+      fs.mkdirSync(path.dirname(gate.abs), { recursive: true });
+      const tmp = path.join(
+        path.dirname(gate.abs),
+        `.agentsam-write-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`,
+      );
+      fs.writeFileSync(tmp, buf);
+      fs.renameSync(tmp, gate.abs);
+      const version = hashBytes(buf);
+      const st = fs.statSync(gate.abs);
+      markRepositoryStale(resolvedRoot, { paths: [gate.rel], reason: 'write' });
+      return {
+        ok: true,
+        path: gate.rel,
+        version,
+        content_hash: version,
+        mtime: Math.floor(st.mtimeMs),
+        size: st.size,
+        engine: LOCAL_FS_ENGINE,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'write_failed',
+      };
+    }
+  }
+
+  /**
+   * @param {string} relPath
+   * @param {string} [content]
+   */
+  function create(relPath, content = '') {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    if (fs.existsSync(gate.abs)) {
+      return { ok: false, error: 'already_exists', code: 'already_exists', path: gate.rel };
+    }
+    return write(relPath, content, {});
+  }
+
+  /**
+   * @param {string} fromRel
+   * @param {string} toRel
+   * @param {{ expectedVersion?: string|null }} [opts]
+   */
+  function rename(fromRel, toRel, opts = {}) {
+    const from = contain(fromRel);
+    if (!from.ok) return from;
+    const to = contain(toRel);
+    if (!to.ok) return to;
+    if (!fs.existsSync(from.abs)) {
+      return { ok: false, error: 'not_found', code: 'ENOENT', path: from.rel };
+    }
+    if (opts.expectedVersion) {
+      const st = fs.statSync(from.abs);
+      if (st.isFile()) {
+        const current = hashBytes(fs.readFileSync(from.abs));
+        if (current !== opts.expectedVersion) {
+          return {
+            ok: false,
+            error: 'version_conflict',
+            code: 'version_conflict',
+            expected: opts.expectedVersion,
+            actual: current,
+          };
+        }
+      }
+    }
+    if (fs.existsSync(to.abs)) {
+      return { ok: false, error: 'target_exists', code: 'already_exists', path: to.rel };
+    }
+    try {
+      fs.mkdirSync(path.dirname(to.abs), { recursive: true });
+      fs.renameSync(from.abs, to.abs);
+      markRepositoryStale(resolvedRoot, { paths: [from.rel, to.rel], reason: 'rename' });
+      return { ok: true, from: from.rel, to: to.rel, engine: LOCAL_FS_ENGINE };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'rename_failed',
+      };
+    }
+  }
+
+  /**
+   * @param {string} relPath
+   * @param {{ expectedVersion?: string|null, recursive?: boolean }} [opts]
+   */
+  function remove(relPath, opts = {}) {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    if (!fs.existsSync(gate.abs)) {
+      return { ok: false, error: 'not_found', code: 'ENOENT', path: gate.rel };
+    }
+    const st = fs.lstatSync(gate.abs);
+    if (st.isFile() && opts.expectedVersion) {
+      const current = hashBytes(fs.readFileSync(gate.abs));
+      if (current !== opts.expectedVersion) {
+        return {
+          ok: false,
+          error: 'version_conflict',
+          code: 'version_conflict',
+          expected: opts.expectedVersion,
+          actual: current,
+        };
+      }
+    }
+    try {
+      if (st.isDirectory()) {
+        fs.rmSync(gate.abs, { recursive: Boolean(opts.recursive), force: false });
+      } else {
+        fs.unlinkSync(gate.abs);
+      }
+      markRepositoryStale(resolvedRoot, { paths: [gate.rel], reason: 'remove' });
+      return { ok: true, path: gate.rel, engine: LOCAL_FS_ENGINE };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'remove_failed',
+      };
+    }
+  }
+
+  /**
+   * @param {string} relPath
+   */
+  function mkdir(relPath) {
+    const gate = contain(relPath);
+    if (!gate.ok) return gate;
+    try {
+      fs.mkdirSync(gate.abs, { recursive: true });
+      return { ok: true, path: gate.rel, engine: LOCAL_FS_ENGINE };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: err && typeof err === 'object' && 'code' in err ? String(err.code) : 'mkdir_failed',
+      };
+    }
+  }
+
+  return {
+    root: resolvedRoot,
+    engine: LOCAL_FS_ENGINE,
+    list,
+    stat,
+    read,
+    write,
+    create,
+    rename,
+    remove,
+    mkdir,
+  };
+}
+
+/**
+ * Disposable scratch root under os.tmpdir for tests.
+ */
+export function createTempWorkspaceRoot(prefix = 'agentsam-fs-') {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}