@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/packages/agentsam-brand/src/scan.js

@@ -0,0 +1,250 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import {
+  extractFromText,
+  isAssetPath,
+  isComponentPath,
+  isStylePath,
+} from './extract.js';
+
+function sha256Json(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+function emit(onEvent, type, payload = {}) {
+  if (typeof onEvent === 'function') onEvent({ type, ...payload, at: Date.now() });
+}
+
+function mergeEvidenceItems(map, key, item) {
+  const existing = map.get(key);
+  if (!existing) {
+    map.set(key, {
+      ...item,
+      occurrences: 1,
+      evidence: [...(item.evidence || [])],
+    });
+    return;
+  }
+  existing.occurrences += 1;
+  for (const e of item.evidence || []) {
+    if (!existing.evidence.some((x) => x.path === e.path && x.line === e.line)) {
+      existing.evidence.push(e);
+    }
+  }
+}
+
+function stableSortTokens(arr) {
+  return [...arr].sort((a, b) => {
+    const oc = (b.occurrences || 0) - (a.occurrences || 0);
+    if (oc) return oc;
+    return String(a.normalized_value || a.value).localeCompare(String(b.normalized_value || b.value));
+  });
+}
+
+/**
+ * brand.scan — deterministic evidence from repository.snapshot authority.
+ * model_required: false · side_effects: none
+ *
+ * @param {{
+ *   cwd?: string,
+ *   snapshot?: object,
+ *   repositorySnapshot?: (opts: object) => Promise<object>,
+ *   onEvent?: (ev: object) => void,
+ *   maxFiles?: number,
+ * }} opts
+ */
+export async function brandScan(opts = {}) {
+  const onEvent = opts.onEvent;
+  emit(onEvent, 'operation.started', { capability: 'brand.scan' });
+  emit(onEvent, 'operation.phase.started', { phase: 'repository_snapshot' });
+
+  let snapshot = opts.snapshot;
+  if (!snapshot) {
+    if (typeof opts.repositorySnapshot !== 'function') {
+      throw new TypeError('brandScan requires snapshot or repositorySnapshot()');
+    }
+    snapshot = await opts.repositorySnapshot({ cwd: opts.cwd || process.cwd() });
+  }
+  if (!snapshot?.snapshot_id || !snapshot?.tree?.paths || !snapshot?.tree?.merkle_root) {
+    throw new Error('brand_scan_invalid_snapshot');
+  }
+
+  const root = fs.realpathSync(opts.cwd || process.cwd());
+  const paths = snapshot.tree.paths;
+  const maxFiles = opts.maxFiles ?? 2500;
+
+  emit(onEvent, 'operation.phase.started', { phase: 'classify_sources' });
+
+  const stylePaths = [];
+  const componentPaths = [];
+  const assetPaths = [];
+  const configPaths = [];
+
+  for (const rel of paths) {
+    if (isStylePath(rel)) stylePaths.push(rel);
+    else if (isAssetPath(rel)) assetPaths.push(rel);
+    else if (isComponentPath(rel)) componentPaths.push(rel);
+    else if (/(?:package\.json|components\.json|\.agentsam\/|theme)/i.test(rel)) configPaths.push(rel);
+  }
+
+  const colorMap = new Map();
+  const cssVarMap = new Map();
+  const typographyMap = new Map();
+  const spacingMap = new Map();
+  const radiusMap = new Map();
+  const shadowMap = new Map();
+  const twMap = new Map();
+  const componentHints = new Map();
+
+  const readList = [
+    ...stylePaths,
+    ...componentPaths.slice(0, Math.min(componentPaths.length, 400)),
+  ].slice(0, maxFiles);
+
+  emit(onEvent, 'operation.phase.started', { phase: 'token_extraction', total: readList.length });
+
+  let read = 0;
+  for (const rel of readList) {
+    read += 1;
+    if (read % 40 === 0) {
+      emit(onEvent, 'operation.progress', {
+        phase: 'token_extraction',
+        current: read,
+        total: readList.length,
+        detail: rel,
+      });
+    }
+    const abs = path.join(root, rel);
+    let text = '';
+    try {
+      if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+      const size = fs.statSync(abs).size;
+      if (size > 512 * 1024) continue;
+      text = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    const extracted = extractFromText(text, rel);
+    for (const c of extracted.colors) mergeEvidenceItems(colorMap, c.normalized_value, c);
+    for (const v of extracted.cssVars) mergeEvidenceItems(cssVarMap, v.name, v);
+    for (const t of extracted.typography) mergeEvidenceItems(typographyMap, `${t.kind}:${t.value}`, t);
+    for (const s of extracted.spacing) mergeEvidenceItems(spacingMap, s.value, s);
+    for (const r of extracted.radius) mergeEvidenceItems(radiusMap, r.value, r);
+    for (const s of extracted.shadow) mergeEvidenceItems(shadowMap, s.value, s);
+    for (const t of extracted.tw) mergeEvidenceItems(twMap, t.value, t);
+
+    const base = path.basename(rel).replace(/\.[^.]+$/, '');
+    if (/^(button|btn|header|footer|card|nav|modal|dialog|badge|alert)/i.test(base)) {
+      const family = base.toLowerCase().replace(/(view|component|index)$/i, '') || base.toLowerCase();
+      const prev = componentHints.get(family) || { family, paths: [], count: 0 };
+      prev.count += 1;
+      if (prev.paths.length < 8) prev.paths.push(rel);
+      componentHints.set(family, prev);
+    }
+  }
+
+  emit(onEvent, 'operation.phase.started', { phase: 'assemble_evidence' });
+
+  const colors = stableSortTokens([...colorMap.values()]);
+  const tokens = {
+    colors,
+    typography: stableSortTokens([...typographyMap.values()]),
+    spacing: stableSortTokens([...spacingMap.values()]),
+    radius: stableSortTokens([...radiusMap.values()]),
+    shadow: stableSortTokens([...shadowMap.values()]),
+    motion: [],
+    breakpoints: [],
+    css_variables: stableSortTokens([...cssVarMap.values()]),
+    tailwind_colors: stableSortTokens([...twMap.values()]),
+  };
+
+  const components = Object.fromEntries(
+    [...componentHints.values()]
+      .sort((a, b) => b.count - a.count || a.family.localeCompare(b.family))
+      .map((row) => [row.family, row]),
+  );
+
+  const conflicts = [];
+  // near-duplicate color clusters (distance <= 12)
+  for (let i = 0; i < Math.min(colors.length, 80); i += 1) {
+    for (let j = i + 1; j < Math.min(colors.length, 80); j += 1) {
+      const a = colors[i];
+      const b = colors[j];
+      if (!a.rgb || !b.rgb) continue;
+      const d = Math.hypot(a.rgb[0] - b.rgb[0], a.rgb[1] - b.rgb[1], a.rgb[2] - b.rgb[2]);
+      if (d > 0 && d <= 12) {
+        conflicts.push({
+          kind: 'near_duplicate_color',
+          values: [a.value, b.value],
+          distance: Number(d.toFixed(2)),
+          occurrences: (a.occurrences || 0) + (b.occurrences || 0),
+        });
+      }
+    }
+  }
+  conflicts.sort((a, b) => (b.occurrences || 0) - (a.occurrences || 0));
+
+  const body = {
+    schema_version: 1,
+    capability: 'brand.scan',
+    deterministic: true,
+    model_required: false,
+    side_effects: 'none',
+    repository: {
+      snapshot_id: snapshot.snapshot_id,
+      content_hash: snapshot.content_hash,
+      merkle_root: snapshot.tree.merkle_root,
+      metadata_root: snapshot.tree.metadata_root,
+      path_count: paths.length,
+    },
+    sources: {
+      css: stylePaths.length,
+      components: componentPaths.length,
+      config: configPaths.length,
+      assets: assetPaths.length,
+      scanned_files: readList.length,
+    },
+    tokens,
+    components,
+    patterns: {
+      button_families: Object.keys(components).filter((k) => /btn|button/.test(k)).length,
+      header_families: Object.keys(components).filter((k) => /header|nav/.test(k)).length,
+      card_families: Object.keys(components).filter((k) => /card/.test(k)).length,
+    },
+    copy: {},
+    assets: {
+      count: assetPaths.length,
+      sample: assetPaths.slice(0, 24),
+    },
+    conflicts: conflicts.slice(0, 50),
+    evidence: [],
+    origin: {
+      mode: 'observed',
+      repository_snapshot: snapshot.snapshot_id,
+    },
+  };
+
+  const contentHash = sha256Json({
+    repository: body.repository,
+    sources: body.sources,
+    tokens: body.tokens,
+    components: body.components,
+    patterns: body.patterns,
+    assets: body.assets,
+    conflicts: body.conflicts,
+  });
+
+  const result = {
+    ...body,
+    content_hash: `sha256:${contentHash}`,
+  };
+
+  emit(onEvent, 'operation.completed', {
+    capability: 'brand.scan',
+    findings: colors.length + conflicts.length,
+    content_hash: result.content_hash,
+  });
+
+  return result;
+}

package/packages/agentsam-brand/test/brand-scan.test.mjs

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { execFileSync } from 'node:child_process';
+import { brandScan, brandResolve } from '../src/index.js';
+import { repositorySnapshot } from '../../../src/capabilities/index.js';
+import { scanTrustBoundary } from '../../../src/security/trust-boundary.js';
+import { suggestNextActions, routeDeterministicIntent } from '../../../src/progression/index.js';
+
+function fixtureRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-brand-'));
+  execFileSync('git', ['init'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['config', 'user.name', 'Test'], { cwd: root, stdio: 'ignore' });
+  fs.writeFileSync(path.join(root, '.gitignore'), 'ignored/\nnode_modules/\n');
+  fs.mkdirSync(path.join(root, 'src/styles'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'src/components'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'ignored'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'src/styles/theme.css'),
+    `:root {\n  --color-slate-950: #0f172a;\n  --black: #111111;\n  color: #101010;\n  background: rgb(17, 17, 17);\n  font-family: "Inter", system-ui;\n  font-size: 16px;\n  border-radius: 8px;\n}\n`,
+  );
+  fs.writeFileSync(
+    path.join(root, 'src/components/Button.tsx'),
+    `export function Button() { return <button className="bg-neutral-950 text-white">Go</button>; }\n`,
+  );
+  fs.writeFileSync(
+    path.join(root, 'src/components/Header.tsx'),
+    `export function Header() { return <header style={{ background: '#0f172a' }}>Nav</header>; }\n`,
+  );
+  fs.writeFileSync(path.join(root, 'ignored/secret.css'), `:root { --should-not-see: #ff0000; }\n`);
+  execFileSync('git', ['add', '.'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['commit', '-m', 'init'], { cwd: root, stdio: 'ignore' });
+  return root;
+}
+
+test('brand.scan derives stable brand evidence from repository snapshot', async (t) => {
+  const root = fixtureRepo();
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  const snapshot = await repositorySnapshot({ cwd: root, churnDays: 30 });
+  const one = await brandScan({ cwd: root, snapshot });
+  const two = await brandScan({ cwd: root, snapshot });
+
+  assert.equal(one.capability, 'brand.scan');
+  assert.equal(one.deterministic, true);
+  assert.equal(one.model_required, false);
+  assert.equal(one.repository.snapshot_id, snapshot.snapshot_id);
+  assert.equal(one.repository.snapshot_id, two.repository.snapshot_id);
+  assert.match(one.content_hash, /^sha256:[a-f0-9]{64}$/);
+  assert.equal(one.content_hash, two.content_hash);
+  assert.deepEqual(one.tokens.colors.map((c) => c.normalized_value), two.tokens.colors.map((c) => c.normalized_value));
+  assert.ok(one.tokens.colors.length >= 2);
+  assert.equal(one.sources.css >= 1, true);
+});
+
+test('brand scan and repository inspection share one file authority', async (t) => {
+  const root = fixtureRepo();
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  const snapshot = await repositorySnapshot({ cwd: root, churnDays: 30 });
+  const boundary = await scanTrustBoundary(root);
+  const brand = await brandScan({ cwd: root, snapshot });
+
+  assert.equal(snapshot.tree.merkle_root, boundary.merkle_root);
+  assert.equal(snapshot.tree.metadata_root, boundary.metadata_root);
+  assert.equal(brand.repository.merkle_root, snapshot.tree.merkle_root);
+  assert.equal(brand.repository.path_count, snapshot.tree.paths.length);
+  assert.equal(snapshot.tree.paths.some((p) => p.startsWith('ignored/')), false);
+  assert.equal(
+    JSON.stringify(brand).includes('should-not-see') || JSON.stringify(brand).includes('#ff0000'),
+    false,
+  );
+});
+
+test('brand.resolve keeps observed/inferred/declared/resolved separated', async (t) => {
+  const root = fixtureRepo();
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const snapshot = await repositorySnapshot({ cwd: root, churnDays: 30 });
+  const scan = await brandScan({ cwd: root, snapshot });
+  const resolved = brandResolve(scan);
+  assert.equal(resolved.capability, 'brand.resolve');
+  assert.ok(Array.isArray(resolved.observed.colors));
+  assert.equal(typeof resolved.inferred.colors, 'object');
+  assert.deepEqual(resolved.declared, {});
+  assert.equal(typeof resolved.resolved.colors, 'object');
+});
+
+test('progression engine suggests brand next actions without a model', () => {
+  const { next_actions } = suggestNextActions({
+    capability: 'brand.scan',
+    result: { conflicts: [{ kind: 'near_duplicate_color' }], complete: true },
+  });
+  assert.ok(next_actions.some((a) => a.id === 'brand.inspect.conflicts'));
+  assert.ok(next_actions.some((a) => a.command?.includes('plan brand')));
+  assert.equal(next_actions.every((a) => a.requires_model === false), true);
+});
+
+test('deterministic intent router handles what next without a model', () => {
+  const hit = routeDeterministicIntent('what should I do next?');
+  assert.equal(hit.intent, 'next');
+  assert.equal(hit.use_progression, true);
+  assert.equal(routeDeterministicIntent('show brand').command, 'agentsam brand');
+});

package/packages/agentsam-contracts/README.md

@@ -0,0 +1,23 @@
+# @inneranimalmedia/agentsam-contracts
+
+Framework-neutral AgentSam contracts shared by product surfaces. This package has no React dependency and must not know whether the host is Local Studio, CAD Studio, CMS Studio, Fuel & Free Time, or another product.
+
+It owns the portable AgentSam vocabulary: messages, inputs/runs, workbench events, tool calls/capabilities, tool definitions, provider descriptors/adapters, authority requirements, orchestration events, hook definitions, execution receipts, artifacts/attachments, explicit host context, model options, repository/company graph records, and adapter interfaces.
+
+## Execution-plane ownership
+
+The contracts intentionally separate portable definitions from host/provider mechanics:
+
+- **tool definition** — what capability exists, its schemas, authority needs, risk/side effects, idempotency, retry policy, handler reference and emitted events.
+- **provider adapter** — provider-specific request/response mechanics only.
+- **authority reference** — opaque host-resolved authority; raw tokens and secrets never belong in portable serialized contracts.
+- **orchestration event** — a provider, tool, workflow or system fact that can trigger downstream work.
+- **hook definition** — when matching events occur, which tool/workflow/event actions should run.
+- **execution receipt** — normalized status/output/error/usage/event evidence from an invocation.
+- **receipt policy** — portable redaction/metadata-only hints so PII, tokens and signing secrets do not leak into durable receipts or prompts.
+
+MCP, CLI, Work Graph, queue-control, application routes and provider packages should consume/project these same contracts rather than define competing tool schemas.
+
+Provider-specific storage, account/shop identifiers, secrets, business rules, and product state remain host concerns. A provider may emit both its native normalized event and a host/domain event (for example `completeful.order.created` then `commerce.order.created`).
+
+Product state does **not** belong here. Trails/projects, CAD geometry, CMS page schemas, auth/session persistence, fulfillment mappings, shop configuration, and deployment-specific wiring stay with their owning app/package.

package/packages/agentsam-contracts/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@inneranimalmedia/agentsam-contracts",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Framework-neutral AgentSam contracts for workbench, tools, providers, events, hooks, execution, identity and repository context.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./events": "./src/events.ts",
+    "./tools": "./src/tools.ts",
+    "./authority": "./src/authority.ts",
+    "./execution": "./src/execution.ts",
+    "./providers": "./src/providers.ts",
+    "./hooks": "./src/hooks.ts",
+    "./artifacts": "./src/artifacts.ts",
+    "./context": "./src/context.ts",
+    "./adapter": "./src/adapter.ts",
+    "./models": "./src/models.ts",
+    "./identity": "./src/identity.ts",
+    "./repository": "./src/repository.ts",
+    "./errors": "./src/errors.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/packages/agentsam-contracts/src/adapter.ts

@@ -0,0 +1,25 @@
+import type { AgentEvent } from './events';
+import type { AgentInput, AgentRun } from './agent';
+import type { AgentCapability } from './tools';
+import type { ModelOption } from './models';
+
+export interface AgentWorkbenchAdapter {
+  send(input: AgentInput): AgentRun | Promise<AgentRun>;
+  cancel(runId: string): void | Promise<void>;
+  getModels(): ModelOption[] | Promise<ModelOption[]>;
+  getCapabilities(): AgentCapability[] | Promise<AgentCapability[]>;
+  subscribe(conversationId: string, onEvent: (event: AgentEvent) => void): () => void;
+}
+
+export interface BrowserWorkbenchAdapter {
+  navigate(url: string): void | Promise<void>;
+  back?(): void | Promise<void>;
+  forward?(): void | Promise<void>;
+  reload?(): void | Promise<void>;
+}
+
+export interface TerminalWorkbenchAdapter {
+  write(command: string): void | Promise<void>;
+  interrupt?(): void | Promise<void>;
+  resize?(cols: number, rows: number): void | Promise<void>;
+}

package/packages/agentsam-contracts/src/agent.ts

@@ -0,0 +1,35 @@
+import type { AgentAttachment } from './artifacts';
+import type { AgentContext } from './context';
+
+export type AgentRole = 'user' | 'assistant' | 'system' | 'tool';
+
+export interface AgentMessage {
+  id: string;
+  role: AgentRole;
+  content: string;
+  createdAt: number;
+  name?: string;
+  modelId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentInput {
+  conversationId: string;
+  text: string;
+  attachments?: AgentAttachment[];
+  context?: AgentContext;
+  modelId?: string;
+  capabilityIds?: string[];
+}
+
+export type AgentRunStatus = 'queued' | 'running' | 'completed' | 'cancelled' | 'failed';
+
+export interface AgentRun {
+  id: string;
+  conversationId: string;
+  status: AgentRunStatus;
+  startedAt: number;
+  completedAt?: number;
+  modelId?: string;
+  error?: string;
+}

package/packages/agentsam-contracts/src/artifacts.ts

@@ -0,0 +1,33 @@
+export type AgentArtifactKind =
+  | 'code'
+  | 'file'
+  | 'preview'
+  | 'browser'
+  | 'terminal'
+  | 'deploy'
+  | 'render'
+  | 'model'
+  | 'receipt'
+  | string;
+
+export interface AgentAttachment {
+  id: string;
+  name: string;
+  mimeType?: string;
+  size?: number;
+  text?: string;
+  url?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentArtifact {
+  id: string;
+  kind: AgentArtifactKind;
+  title?: string;
+  mimeType?: string;
+  content?: string;
+  url?: string;
+  createdAt?: number;
+  updatedAt?: number;
+  metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/src/authority.ts

@@ -0,0 +1,29 @@
+export type AgentAuthorityType =
+  | 'none'
+  | 'host'
+  | 'binding'
+  | 'secret'
+  | 'oauth'
+  | 'connection';
+
+export interface AgentAuthorityRequirement {
+  type: AgentAuthorityType;
+  ref?: string;
+  provider?: string;
+  scopes?: string[];
+  optional?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Opaque, non-secret reference to authority resolved by the host runtime.
+ * Raw credentials/tokens must not be serialized into portable AgentSam contracts.
+ */
+export interface AgentResolvedAuthorityReference {
+  type: Exclude<AgentAuthorityType, 'none'>;
+  ref: string;
+  provider?: string;
+  accountRef?: string;
+  scopes?: string[];
+  metadata?: Record<string, unknown>;
+}

package/packages/agentsam-contracts/src/context.ts

@@ -0,0 +1,16 @@
+export type AgentSurface = 'chat' | 'work' | 'cad' | 'cms' | string;
+
+export interface AgentContext {
+  surface: AgentSurface;
+  accountId?: string;
+  authUserId?: string;
+  repository?: string;
+  files?: string[];
+  selection?: unknown;
+  projectId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentContextProvider {
+  getContext(): AgentContext | Promise<AgentContext>;
+}

package/packages/agentsam-contracts/src/errors.ts

@@ -0,0 +1,46 @@
+// GENERATED by scripts/generate-error-contracts.mjs. Do not edit by hand.
+export const AGENTSAM_ERROR_SCHEMA_VERSION = 1 as const;
+
+export type AgentSamErrorCode = "OK" | "CANCELLED" | "UNKNOWN" | "INVALID_ARGUMENT" | "DEADLINE_EXCEEDED" | "NOT_FOUND" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "RESOURCE_EXHAUSTED" | "FAILED_PRECONDITION" | "ABORTED" | "OUT_OF_RANGE" | "UNIMPLEMENTED" | "INTERNAL" | "UNAVAILABLE" | "DATA_LOSS" | "UNAUTHENTICATED";
+export type AgentSamErrorReason = "unknown" | "input_invalid" | "input_out_of_range" | "precondition_failed" | "unsupported_operation" | "auth_missing" | "auth_invalid" | "permission_denied" | "user_permission_denied" | "provider_not_connected" | "provider_credential_missing" | "provider_credential_invalid" | "provider_credential_expired" | "provider_scope_insufficient" | "provider_budget_exhausted" | "provider_quota_exhausted" | "provider_rate_limited" | "provider_capacity_exhausted" | "provider_unavailable" | "provider_overloaded" | "provider_request_invalid" | "provider_model_not_found" | "provider_region_unsupported" | "provider_content_blocked" | "context_window_exceeded" | "service_tier_unsupported" | "continuation_invalid" | "target_not_found" | "already_exists" | "conflict" | "stale_version" | "rate_limited" | "quota_exhausted" | "capacity_exhausted" | "transport_unreachable" | "transport_refused" | "transport_timeout" | "upstream_invalid_response" | "dns_unresolved" | "tls_handshake_failed" | "tls_certificate_invalid" | "tunnel_connector_unavailable" | "cancelled" | "deadline_exceeded" | "execution_timeout" | "execution_failed" | "process_spawn_failed" | "process_crashed" | "process_output_limit" | "device_not_enrolled" | "device_credential_missing" | "device_credential_invalid" | "device_credential_expired" | "device_registration_missing" | "device_registration_stale" | "connection_revoked" | "connection_disabled" | "identity_resolution_failed" | "identity_mismatch" | "repository_scope_violation" | "repository_changed" | "index_stale" | "index_failed" | "embedding_failed" | "vector_store_failed" | "github_installation_missing" | "github_repository_not_found" | "github_rate_limited" | "github_secondary_rate_limited" | "github_scope_insufficient" | "cloudflare_workers_cpu_exhausted" | "cloudflare_service_binding_unavailable" | "cloudflare_durable_object_unavailable" | "cloudflare_d1_unavailable" | "cloudflare_r2_unavailable" | "docker_daemon_unavailable" | "docker_image_not_found" | "docker_build_failed" | "docker_container_failed" | "docker_registry_auth_failed" | "docker_pull_rate_limited" | "gcp_project_missing" | "gcp_api_disabled" | "gcp_quota_exhausted" | "gcp_vm_not_found" | "gcp_vm_unavailable" | "cad_tool_not_installed" | "cad_tool_not_executable" | "cad_tool_version_incompatible" | "cad_component_missing" | "cad_dependency_missing" | "cad_dependency_version_incompatible" | "cad_source_parse_failed" | "cad_input_format_unsupported" | "cad_import_failed" | "cad_model_recompute_failed" | "cad_constraint_unsatisfied" | "cad_geometry_invalid" | "cad_null_shape" | "cad_boolean_failed" | "cad_kernel_failed" | "cad_script_failed" | "cad_export_format_unsupported" | "cad_export_failed" | "cad_output_missing" | "cad_output_invalid" | "cad_render_engine_unavailable" | "cad_gpu_unavailable" | "cad_render_failed" | "cad_memory_exhausted" | "cad_process_crashed" | "cad_warning_escalated" | "policy_blocked" | "copyright_blocked" | "persistence_failed" | "data_corrupt" | "data_loss" | "internal" | "internal_invariant_violation" | "internal_configuration_invalid" | "internal_contract_violation" | "internal_adapter_failed" | "internal_dependency_failed";
+export type AgentSamErrorSeverity = "transient" | "blocking_user_fixable" | "blocking_internal" | "policy_blocking";
+export type AgentSamErrorSourceKind = "user" | "agentsam" | "provider" | "dependency" | "runtime" | "policy";
+export type AgentSamErrorResolutionOwner = "user" | "agentsam" | "provider" | "organization_admin" | "policy" | "unknown";
+export type AgentSamErrorDomain = "runtime" | "provider" | "auth" | "device" | "terminal" | "transport" | "repository" | "indexing" | "knowledge" | "cad" | "deployment" | "persistence" | "policy" | "tool";
+export type AgentSamRemediationAction = "none" | "retry" | "retry_later" | "reauthenticate" | "connect_provider" | "configure_provider_credential" | "refresh_provider_credential" | "request_permission" | "reenroll_device" | "reconnect_service" | "install_dependency" | "upgrade_dependency" | "configure_dependency" | "change_configuration" | "change_input" | "reduce_scope" | "increase_quota" | "add_budget" | "select_model" | "change_region" | "restart_runtime" | "inspect_platform" | "contact_provider" | "contact_agentsam" | "contact_organization_admin";
+
+export interface AgentSamErrorSource { kind: AgentSamErrorSourceKind; name: string; service: string | null; }
+export interface AgentSamErrorRemediation { action: AgentSamRemediationAction; message: string | null; automatic: boolean; command: string | null; url: string | null; }
+export interface AgentSamErrorResource { type: string; id: string | null; name: string | null; }
+export interface AgentSamNativeErrorEvidence { code: string | null; exception_type: string | null; exit_code: number | null; signal: string | null; stderr: string | null; stdout: string | null; stack: string | null; }
+export interface AgentSamEnvironmentEvidence { detected_version: string | null; required_version: string | null; component: string | null; runtime: string | null; platform: string | null; }
+
+export interface AgentSamErrorEnvelope {
+  ok: false;
+  schema_version: typeof AGENTSAM_ERROR_SCHEMA_VERSION;
+  code: AgentSamErrorCode;
+  reason: AgentSamErrorReason | (string & {});
+  severity: AgentSamErrorSeverity;
+  source: AgentSamErrorSource;
+  resolution_owner: AgentSamErrorResolutionOwner;
+  domain: AgentSamErrorDomain;
+  tool: string | null;
+  stage: string | null;
+  message: string;
+  retryable: boolean;
+  retry_after_ms: number | null;
+  remediation: AgentSamErrorRemediation;
+  resource: AgentSamErrorResource | null;
+  native: AgentSamNativeErrorEvidence | null;
+  environment: AgentSamEnvironmentEvidence | null;
+  http_status: number | null;
+  grpc_status: number | null;
+  transport: string | null;
+  provider: string | null;
+  provider_code: string | null;
+  request_id: string | null;
+  trace_id: string | null;
+  fingerprint: string;
+  occurrence_count: number;
+  details: unknown;
+}

package/packages/agentsam-contracts/src/events.ts

@@ -0,0 +1,47 @@
+import type { AgentArtifact } from './artifacts';
+import type { AgentMessage, AgentRunStatus } from './agent';
+import type { AgentToolCall } from './tools';
+
+/**
+ * Workbench-facing event stream retained for UI/runtime compatibility.
+ */
+export type AgentEvent =
+  | { type: 'message'; message: AgentMessage }
+  | { type: 'message.delta'; messageId: string; delta: string }
+  | { type: 'run.status'; runId: string; status: AgentRunStatus; error?: string }
+  | { type: 'tool'; toolCall: AgentToolCall }
+  | { type: 'artifact'; artifact: AgentArtifact }
+  | { type: 'error'; runId?: string; error: string };
+
+export type AgentEventSourceKind =
+  | 'webhook'
+  | 'tool'
+  | 'workflow'
+  | 'provider'
+  | 'system'
+  | 'user';
+
+export interface AgentEventSource {
+  kind: AgentEventSourceKind;
+  provider?: string;
+  ref?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Portable orchestration/domain event. Provider events can be retained while a host
+ * additionally emits normalized domain events (for example completeful.order.created
+ * followed by commerce.order.created).
+ */
+export interface AgentOrchestrationEvent<TPayload = unknown> {
+  id: string;
+  eventKey: string;
+  occurredAt: number;
+  source: AgentEventSource;
+  payload: TPayload;
+  accountId?: string;
+  subject?: string;
+  correlationId?: string;
+  causationId?: string;
+  metadata?: Record<string, unknown>;
+}