@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/src/receipts/sinks.js

@@ -0,0 +1,285 @@
+import { createHash } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  RECEIPT_SCHEMA_URL,
+  RECEIPT_R2_PREFIX,
+  SCHEMA_BASE_URL,
+  SCHEMAS_BUCKET_NAME,
+  receiptR2Key,
+  retentionExpiresAt,
+  validateReceiptEnvelope,
+} from "./contract.js";
+
+function stablePayload(receipt) {
+  return JSON.stringify(
+    {
+      $schema: RECEIPT_SCHEMA_URL,
+      ...receipt,
+    },
+    null,
+    2,
+  );
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export class LocalReceiptSink {
+  constructor({ baseDir = join(process.cwd(), ".agentsam", "receipts") } = {}) {
+    this.baseDir = baseDir;
+  }
+
+  async write(receipt) {
+    const validation = validateReceiptEnvelope(receipt);
+    if (!validation.ok) {
+      throw new TypeError(`Invalid AgentSam receipt: ${validation.errors.join("; ")}`);
+    }
+    const payload = stablePayload(receipt);
+    const localPath = join(this.baseDir, `${receipt.receipt_id}.json`);
+    await mkdir(dirname(localPath), { recursive: true });
+    await writeFile(localPath, payload, "utf8");
+    return {
+      local_path: localPath,
+      content_hash: sha256(payload),
+      byte_size: Buffer.byteLength(payload),
+    };
+  }
+}
+
+export class R2ReceiptSink {
+  constructor(env = {}) {
+    this.env = env;
+  }
+
+  async write(receipt) {
+    const validation = validateReceiptEnvelope(receipt);
+    if (!validation.ok) {
+      throw new TypeError(`Invalid AgentSam receipt: ${validation.errors.join("; ")}`);
+    }
+
+    const r2Key = receiptR2Key(receipt);
+    if (!r2Key.startsWith(`${RECEIPT_R2_PREFIX}/`)) {
+      throw new Error("receipt_key_prefix_violation");
+    }
+
+    const payload = stablePayload(receipt);
+    const bucket = this.env.SCHEMAS_BUCKET;
+    if (bucket) {
+      await bucket.put(r2Key, payload, {
+        httpMetadata: {
+          contentType: "application/json",
+          cacheControl: "public, max-age=31536000, immutable",
+        },
+      });
+    }
+
+    return {
+      r2_key: r2Key,
+      url: `${SCHEMA_BASE_URL}/${r2Key}`,
+      bucket: SCHEMAS_BUCKET_NAME,
+      content_hash: sha256(payload),
+      byte_size: Buffer.byteLength(payload),
+      persisted: Boolean(bucket),
+    };
+  }
+}
+
+export class D1ReceiptCatalog {
+  constructor(db) {
+    if (!db?.prepare) throw new TypeError("D1ReceiptCatalog requires a D1-compatible DB");
+    this.db = db;
+  }
+
+  async insertReceipt(receipt, sinkResult, { expiresAtUnix = null } = {}) {
+    const r2Key = sinkResult?.r2_key;
+    if (!r2Key?.startsWith(`${RECEIPT_R2_PREFIX}/`)) {
+      throw new Error("receipt_catalog_r2_key_prefix_violation");
+    }
+
+    const payload = stablePayload(receipt);
+    const contentHash = sinkResult.content_hash || sha256(payload);
+    const byteSize = Number(sinkResult.byte_size || Buffer.byteLength(payload));
+
+    await this.db
+      .prepare(
+        `INSERT INTO agentsam_receipt_catalog
+          (id, account_id, receipt_kind, schema_name, status, retention_class,
+           repository_id, git_sha, run_id, r2_key, content_hash, byte_size,
+           created_at_unix, expires_at_unix, meta_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           status=excluded.status,
+           r2_key=excluded.r2_key,
+           content_hash=excluded.content_hash,
+           byte_size=excluded.byte_size,
+           expires_at_unix=excluded.expires_at_unix,
+           meta_json=excluded.meta_json`,
+      )
+      .bind(
+        receipt.receipt_id,
+        receipt.identity.account_id,
+        receipt.kind,
+        receipt.schema,
+        receipt.status,
+        receipt.retention_class,
+        receipt.identity.repository_id || null,
+        receipt.identity.git_sha || null,
+        receipt.identity.run_id || null,
+        r2Key,
+        contentHash,
+        byteSize,
+        Number(receipt.metrics.created_at_unix),
+        expiresAtUnix,
+        JSON.stringify({
+          pty_session_id: receipt.identity.pty_session_id || null,
+          schema_url: RECEIPT_SCHEMA_URL,
+        }),
+      )
+      .run();
+  }
+
+  async list({ limit = 20, repositoryId = null, status = null } = {}) {
+    const where = [];
+    const binds = [];
+    if (repositoryId) {
+      where.push("repository_id = ?");
+      binds.push(String(repositoryId));
+    }
+    if (status) {
+      where.push("status = ?");
+      binds.push(String(status));
+    }
+    const boundedLimit = Math.max(1, Math.min(200, Number(limit) || 20));
+    const sql =
+      "SELECT id, account_id, receipt_kind, schema_name, status, retention_class, " +
+      "repository_id, git_sha, run_id, r2_key, content_hash, byte_size, " +
+      "created_at_unix, expires_at_unix, meta_json " +
+      "FROM agentsam_receipt_catalog " +
+      (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
+      "ORDER BY created_at_unix DESC LIMIT ?";
+    binds.push(boundedLimit);
+    const result = await this.db.prepare(sql).bind(...binds).all();
+    return (result?.results || []).map((row) => ({
+      receipt_id: row.id,
+      kind: row.receipt_kind,
+      schema: row.schema_name,
+      status: row.status,
+      retention_class: row.retention_class,
+      identity: {
+        account_id: row.account_id,
+        repository_id: row.repository_id,
+        git_sha: row.git_sha,
+        run_id: row.run_id,
+      },
+      metrics: {
+        created_at_unix: row.created_at_unix,
+        receipt_byte_size: row.byte_size,
+      },
+      r2_key: row.r2_key,
+      content_hash: row.content_hash,
+      expires_at_unix: row.expires_at_unix,
+      meta: row.meta_json ? JSON.parse(row.meta_json) : null,
+    }));
+  }
+
+  async getIndex(receiptId) {
+    const result = await this.db
+      .prepare(
+        "SELECT id, account_id, receipt_kind, schema_name, status, retention_class, " +
+          "repository_id, git_sha, run_id, r2_key, content_hash, byte_size, " +
+          "created_at_unix, expires_at_unix, meta_json " +
+          "FROM agentsam_receipt_catalog WHERE id = ? LIMIT 1",
+      )
+      .bind(String(receiptId))
+      .first();
+    return result || null;
+  }
+}
+
+export class ReceiptCatalogReader {
+  constructor({ catalog, bucket }) {
+    if (!catalog?.list || !catalog?.getIndex) {
+      throw new TypeError("ReceiptCatalogReader requires a D1ReceiptCatalog-compatible catalog");
+    }
+    if (!bucket?.get) {
+      throw new TypeError("ReceiptCatalogReader requires an R2-compatible bucket");
+    }
+    this.catalog = catalog;
+    this.bucket = bucket;
+  }
+
+  async list(options = {}) {
+    return this.catalog.list(options);
+  }
+
+  async get(receiptId) {
+    const row = await this.catalog.getIndex(receiptId);
+    if (!row) return null;
+    if (!String(row.r2_key || "").startsWith(RECEIPT_R2_PREFIX + "/")) {
+      throw new Error("receipt_catalog_r2_key_prefix_violation");
+    }
+    const object = await this.bucket.get(row.r2_key);
+    if (!object) return null;
+    const text =
+      typeof object.text === "function"
+        ? await object.text()
+        : new TextDecoder().decode(await object.arrayBuffer());
+    const receipt = JSON.parse(text);
+    const validation = validateReceiptEnvelope(receipt);
+    if (!validation.ok) {
+      throw new Error("stored_receipt_envelope_invalid: " + validation.errors.join("; "));
+    }
+    return receipt;
+  }
+}
+
+export class CompositeReceiptSink {
+  constructor({ localSink, r2Sink = null, dbCatalog = null } = {}) {
+    if (!localSink?.write) {
+      throw new TypeError("CompositeReceiptSink requires localSink");
+    }
+    this.localSink = localSink;
+    this.r2Sink = r2Sink;
+    this.dbCatalog = dbCatalog;
+  }
+
+  async write(receipt, options = {}) {
+    const validation = validateReceiptEnvelope(receipt);
+    if (!validation.ok) {
+      throw new TypeError(`Invalid AgentSam receipt: ${validation.errors.join("; ")}`);
+    }
+
+    const localRes = await this.localSink.write(receipt);
+    let r2Res = {};
+    const expiresAtUnix = retentionExpiresAt(receipt);
+
+    if (this.r2Sink) {
+      r2Res = await this.r2Sink.write(receipt);
+      if (this.dbCatalog && r2Res.r2_key) {
+        await this.dbCatalog.insertReceipt(receipt, r2Res, { expiresAtUnix });
+      }
+    }
+
+    if (options.localWorkdir) {
+      await this.cleanupLocalWorkspace(options.localWorkdir, receipt.status);
+    }
+
+    return {
+      local_path: localRes.local_path,
+      r2_key: r2Res.r2_key,
+      url: r2Res.url,
+      content_hash: r2Res.content_hash || localRes.content_hash,
+      expires_at_unix: expiresAtUnix,
+    };
+  }
+
+  async cleanupLocalWorkspace(workdir, status) {
+    if (status !== "passed") return false;
+    const value = String(workdir || "");
+    if (!value || !value.includes("agentsam-")) return false;
+    await rm(value, { recursive: true, force: true });
+    return true;
+  }
+}

package/src/rpc/generated/errors_pb.js

@@ -103,7 +103,8 @@ proto.agentsam.knowledge.v1.ErrorDetail.toObject = function(includeInstance, msg
     detailsJson: jspb.Message.getFieldWithDefault(msg, 25, ""),
     occurrenceCount: jspb.Message.getFieldWithDefault(msg, 26, 0),
     requestId: jspb.Message.getFieldWithDefault(msg, 27, ""),
-    schemaVersion: jspb.Message.getFieldWithDefault(msg, 28, 0)
+    schemaVersion: jspb.Message.getFieldWithDefault(msg, 28, 0),
+    nativeStage: jspb.Message.getFieldWithDefault(msg, 29, "")
   };
 
   if (includeInstance) {
@@ -252,6 +253,10 @@ proto.agentsam.knowledge.v1.ErrorDetail.deserializeBinaryFromReader = function(m
       var value = /** @type {number} */ (reader.readUint32());
       msg.setSchemaVersion(value);
       break;
+    case 29:
+      var value = /** @type {string} */ (reader.readString());
+      msg.setNativeStage(value);
+      break;
     default:
       reader.skipField();
       break;
@@ -477,6 +482,13 @@ proto.agentsam.knowledge.v1.ErrorDetail.serializeBinaryToWriter = function(messa
       f
     );
   }
+  f = /** @type {string} */ (jspb.Message.getField(message, 29));
+  if (f != null) {
+    writer.writeString(
+      29,
+      f
+    );
+  }
 };
 
 
@@ -1416,6 +1428,42 @@ proto.agentsam.knowledge.v1.ErrorDetail.prototype.hasSchemaVersion = function()
 };
 
 
+/**
+ * optional string native_stage = 29;
+ * @return {string}
+ */
+proto.agentsam.knowledge.v1.ErrorDetail.prototype.getNativeStage = function() {
+  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 29, ""));
+};
+
+
+/**
+ * @param {string} value
+ * @return {!proto.agentsam.knowledge.v1.ErrorDetail} returns this
+ */
+proto.agentsam.knowledge.v1.ErrorDetail.prototype.setNativeStage = function(value) {
+  return jspb.Message.setField(this, 29, value);
+};
+
+
+/**
+ * Clears the field making it undefined.
+ * @return {!proto.agentsam.knowledge.v1.ErrorDetail} returns this
+ */
+proto.agentsam.knowledge.v1.ErrorDetail.prototype.clearNativeStage = function() {
+  return jspb.Message.setField(this, 29, undefined);
+};
+
+
+/**
+ * Returns whether this field is set.
+ * @return {boolean}
+ */
+proto.agentsam.knowledge.v1.ErrorDetail.prototype.hasNativeStage = function() {
+  return jspb.Message.getField(this, 29) != null;
+};
+
+
 /**
  * @enum {number}
  */

package/src/tools/runtime.js

@@ -1,4 +1,4 @@
-import { ERROR_REASON_POLICY, normalizeError } from '../errors/index.js';
+import { ERROR_REASON_POLICY, canonicalizeErrorReason, normalizeError } from '../errors/index.js';
 import { receiptPayload, redactToolValue } from './redact.js';
 
 function defaultId(prefix) {
@@ -6,6 +6,11 @@ function defaultId(prefix) {
 }
 
 function reasonForError(error) {
+  const nativeReason = canonicalizeErrorReason(error);
+  if (/^(hook|mcp|lsp|tool|provider)_/.test(nativeReason || '')) return nativeReason;
+  const message = String(error?.message || error || '').toLowerCase();
+  if (message.includes('provider adapter not registered') || message.includes('no registered execution target')) return 'tool_handler_unavailable';
+  if (/timeout|timed out|deadline/.test(message)) return 'tool_timeout';
   const status = Number(error?.status || error?.http_status || 0);
   if (status === 401) return 'provider_credential_invalid';
   if (status === 403) return 'provider_scope_insufficient';
@@ -16,12 +21,12 @@ function reasonForError(error) {
   if (status === 400 || status === 422) return 'provider_request_invalid';
   if (error?.code === 'completeful_idempotency_required') return 'input_invalid';
   if (error instanceof TypeError) return 'input_invalid';
-  return 'execution_failed';
+  return nativeReason || 'tool_execution_failed';
 }
 
-function normalizeToolError(error, definition) {
+function normalizeToolError(error, definition, sideEffectState = 'unknown') {
   const reason = reasonForError(error);
-  const policy = ERROR_REASON_POLICY[reason] || ERROR_REASON_POLICY.execution_failed;
+  const policy = ERROR_REASON_POLICY[reason] || ERROR_REASON_POLICY.tool_execution_failed;
   return normalizeError(error, {
     code: policy.code,
     reason,
@@ -29,6 +34,9 @@ function normalizeToolError(error, definition) {
       ? { kind: 'provider', name: definition.provider, service: definition.provider }
       : { kind: 'runtime', name: 'agentsam-tool-runtime' },
     domain: 'tool',
+    stage: 'execute',
+    feature: 'tool.execute',
+    side_effect_state: sideEffectState,
     tool: definition.toolKey,
     provider: definition.provider || null,
     provider_code: error?.code || null,
@@ -132,7 +140,7 @@ export function createToolExecutor({
     try {
       invoke = await resolveExecutionTarget(registry, definition);
     } catch (error) {
-      const normalized = normalizeToolError(error, definition);
+      const normalized = normalizeToolError(error, definition, 'not_started');
       const completedAt = now();
       const receipt = {
         invocationId: invocation.id,

package/templates/mini/gadget/app.js

@@ -1,45 +1,20 @@
-const minutes = document.querySelector('#minutes');
-const clock = document.querySelector('#clock');
-const toggle = document.querySelector('#toggle');
+const action = document.querySelector('#action');
+const reset = document.querySelector('#reset');
 const status = document.querySelector('#status');
-let remaining = 300000;
-let deadline = 0;
-let interval;
+let interactions = 0;
+
 function draw() {
-  const seconds = Math.ceil(remaining / 1000);
-  clock.textContent = `${String(Math.floor(seconds / 60)).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`;
+  status.textContent = interactions === 0
+    ? 'Ready.'
+    : `Interaction ${interactions} recorded. Replace this behavior with your own.`;
 }
-function pause() {
-  clearInterval(interval);
-  interval = undefined;
-  minutes.disabled = false;
-  toggle.textContent = 'Resume';
-}
-function reset() {
-  pause();
-  const value = Math.min(180, Math.max(1, Math.round(Number(minutes.value) || 5)));
-  minutes.value = value;
-  remaining = value * 60000;
-  toggle.textContent = 'Start focus';
-  status.textContent = 'Ready when you are.';
+
+action.addEventListener('click', () => {
+  interactions += 1;
+  draw();
+});
+
+reset.addEventListener('click', () => {
+  interactions = 0;
   draw();
-}
-toggle.addEventListener('click', () => {
-  if (interval) {
-    remaining = Math.max(0, deadline - Date.now());
-    pause(); draw(); status.textContent = 'Paused. Take your time.';
-    return;
-  }
-  if (remaining <= 0) reset();
-  deadline = Date.now() + remaining;
-  minutes.disabled = true;
-  toggle.textContent = 'Pause';
-  status.textContent = 'Focus on your next small step.';
-  interval = setInterval(() => {
-    remaining = Math.max(0, deadline - Date.now());
-    draw();
-    if (!remaining) { pause(); toggle.textContent = 'Start again'; status.textContent = 'Session complete. Nice work.'; }
-  }, 200);
 });
-minutes.addEventListener('change', reset);
-document.querySelector('#reset').addEventListener('click', reset);

package/templates/mini/gadget/index.html

@@ -3,11 +3,11 @@
 <head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>{{NAME}} · AgentSam Mini</title><link rel="stylesheet" href="/style.css"><script src="/app.js" defer></script></head>
 <body><main>
   <div class="brand"><span class="dot"></span>AGENTSAM MINI</div>
-  <h1>A little space to focus.</h1><p>One task. A few quiet minutes.</p>
-  <section class="card" aria-label="Focus timer">
-    <label for="minutes">Session length in minutes</label><input id="minutes" type="number" min="1" max="180" value="5">
-    <div class="clock" id="clock" role="timer" aria-label="Time remaining">05:00</div>
-    <div class="row"><button id="toggle" class="primary">Start focus</button><button id="reset">Reset</button></div>
-    <p id="status" class="status" role="status">Ready when you are.</p>
-  </section><footer>{{NAME}} · Changes to the timer stay in this tab.</footer>
+  <h1>A small surface to shape.</h1><p>Start with one interaction, then replace it with the utility you actually need.</p>
+  <section class="card" aria-label="Interactive starter">
+    <h2>Interactive canvas</h2>
+    <p>This starter proves local state and events without pretending to be a finished product.</p>
+    <div class="row"><button id="action" class="primary">Try interaction</button><button id="reset">Reset</button></div>
+    <p id="status" class="status" role="status">Ready.</p>
+  </section><footer>{{NAME}} · Plain HTML, CSS, and JavaScript.</footer>
 </main></body></html>

package/templates/mini/shared/style.css

@@ -1 +1 @@
-:root{color-scheme:light;font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#20242d;background:#f5f6f8;font-synthesis:none}*{box-sizing:border-box}body{margin:0;padding:24px}main{max-width:720px;margin:8vh auto}.brand{display:flex;align-items:center;gap:8px;font-size:.8rem;letter-spacing:.04em;color:#616979}.dot{width:8px;height:8px;border-radius:50%;background:#5a7df7}h1{font-size:clamp(2rem,7vw,3.2rem);line-height:1.1;letter-spacing:-.055em;margin:22px 0 12px}h2{font-size:1.1rem}p{color:#616979}.card{padding:clamp(20px,5vw,36px);border:1px solid #e4e7ed;border-radius:24px;background:white;margin-top:28px;box-shadow:0 8px 32px #25305606}.row{display:flex;gap:12px;flex-wrap:wrap;align-items:center}button,.button{font:inherit;cursor:pointer;border-radius:12px;border:1px solid #d8dee9;background:white;color:#20242d;padding:12px 20px;min-height:48px;text-decoration:none;display:inline-flex;justify-content:center;align-items:center}.primary{background:#365cdb;color:#fff;border-color:#365cdb}button:hover,.button:hover{filter:brightness(.95)}:focus-visible{outline:3px solid #5a7df7;outline-offset:4px}label{display:block;font-size:.875rem;color:#485165;margin-bottom:8px}input,textarea{font:inherit;width:100%;padding:12px;border:1px solid #c5ccd9;border-radius:10px;background:#fff;color:#20242d}input[type=number]{max-width:100px}textarea{font:13px/1.6 ui-monospace,SFMono-Regular,monospace;resize:vertical;min-height:180px}.clock{font-size:clamp(4rem,18vw,7rem);font-variant-numeric:tabular-nums;letter-spacing:-.065em;text-align:center;line-height:1.3;margin:24px 0}.muted,footer{font-size:.85rem;color:#616979}footer{margin:24px 0}.status{min-height:24px;font-size:.875rem}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:13px/1.6 ui-monospace,SFMono-Regular,monospace;background:#f5f6f8;padding:16px;border-radius:12px;max-height:340px;overflow:auto}.space{margin-top:20px}.error{color:#aa2331}@media(max-width:480px){body{padding:18px}main{margin:6vh auto}.row>button{flex:1}}@media(prefers-reduced-motion:no-preference){button,.button{transition:filter .15s}}
+:root{color-scheme:light;font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#20242d;background:#f5f6f8;font-synthesis:none}*{box-sizing:border-box}body{margin:0;padding:24px}main{max-width:720px;margin:8vh auto}.brand{display:flex;align-items:center;gap:8px;font-size:.8rem;letter-spacing:.04em;color:#616979}.dot{width:8px;height:8px;border-radius:50%;background:#5a7df7}h1{font-size:clamp(2rem,7vw,3.2rem);line-height:1.1;letter-spacing:-.055em;margin:22px 0 12px}h2{font-size:1.1rem}p{color:#616979}.card{padding:clamp(20px,5vw,36px);border:1px solid #e4e7ed;border-radius:24px;background:white;margin-top:28px;box-shadow:0 8px 32px #25305606}.row{display:flex;gap:12px;flex-wrap:wrap;align-items:center}button,.button{font:inherit;cursor:pointer;border-radius:12px;border:1px solid #d8dee9;background:white;color:#20242d;padding:12px 20px;min-height:48px;text-decoration:none;display:inline-flex;justify-content:center;align-items:center}.primary{background:#365cdb;color:#fff;border-color:#365cdb}button:hover,.button:hover{filter:brightness(.95)}:focus-visible{outline:3px solid #5a7df7;outline-offset:4px}label{display:block;font-size:.875rem;color:#485165;margin-bottom:8px}input,textarea{font:inherit;width:100%;padding:12px;border:1px solid #c5ccd9;border-radius:10px;background:#fff;color:#20242d}input[type=number]{max-width:100px}textarea{font:13px/1.6 ui-monospace,SFMono-Regular,monospace;resize:vertical;min-height:180px}.muted,footer{font-size:.85rem;color:#616979}footer{margin:24px 0}.status{min-height:24px;font-size:.875rem}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:13px/1.6 ui-monospace,SFMono-Regular,monospace;background:#f5f6f8;padding:16px;border-radius:12px;max-height:340px;overflow:auto}.space{margin-top:20px}.error{color:#aa2331}@media(max-width:480px){body{padding:18px}main{margin:6vh auto}.row>button{flex:1}}@media(prefers-reduced-motion:no-preference){button,.button{transition:filter .15s}}