@amalgm/chat 0.2.9-preview.35480111675 → 0.2.9-preview.36053697119

package/PURPOSE.md

@@ -231,11 +231,15 @@ execution before the first turn exists.
     invocation's initialized counters cannot make a turn look fully measured.
     Provider cancellation and its final usage settle before the turn seals.
 48. Non-platform step usage is delivered from the committed journal with a stable
-    idempotency key and retried until acknowledged. Platform usage is metered and
-    persisted by the API proxy for each upstream invocation; local observations
-    cannot create a second charge. The authenticated host supplies ownership.
-    Delivery starts only with a complete host-supplied platform capability;
-    absent delivery configuration leaves measurements pending and local Chat usable.
+    idempotency key and retried until acknowledged. Each delivery commits its own
+    payload with the step, so finding due work never re-reads turn journals. An
+    unavailable destination backs off the whole queue; a record it refuses is
+    retried on its own lengthening schedule and never blocks the records behind
+    it. Platform usage is metered and persisted by the API proxy for each
+    upstream invocation; local observations cannot create a second charge. The
+    authenticated host supplies ownership. Delivery starts only with a complete
+    host-supplied platform capability; absent delivery configuration leaves
+    measurements pending and local Chat usable.
 49. Only commands with an explicit Amalgm normalization may be advertised or
     executed. Native discovery is evidence, never execution permission. The only
     enabled command is `/compact`, on adapters with a proven compaction mapping;

package/docs/contracts/acp-and-step-usage.md

@@ -261,7 +261,8 @@ matching host and proxy implementation.
 Verification joins native invocation evidence to local steps, checks each
 bucket independently, then compares live/saved/replayed records and the
 owner-scoped Supabase rows. Inspect `usage_deliveries` for unacknowledged local
-records. Check `billing_transactions.usage_log_id` for platform settlement and
+records; `attempts`, `due_at` and `last_error` show a record the destination
+refused and when it is next retried. Check `billing_transactions.usage_log_id` for platform settlement and
 confirm BYOK/subscription records have no platform debit. Counts alone do not
 prove matching usage.
 

package/host/sqlite/index.d.ts

@@ -64,10 +64,11 @@ export class SqliteConversationStore implements ConversationStorePort {
   beginTurn(input: BeginConversationTurnInput): Promise<ConversationTurn>;
   appendTurnUsage(input: AppendTurnUsageInput): Promise<void>;
   pendingUsage(ownerUserId: string, limit?: number): Promise<readonly {
-    conversationId: string; turnId: string; stepId: string;
-    execution: ConversationTurn['execution']; observation: AppendTurnUsageInput['observation'];
+    conversationId: string; turnId: string; stepId: string; attempts: number;
+    execution: ConversationTurn['execution']; observation: Omit<AppendTurnUsageInput['observation'], 'raw'>;
   }[]>;
   acknowledgeUsage(ownerUserId: string, turnId: string, stepId: string): Promise<void>;
+  deferUsage(ownerUserId: string, turnId: string, stepId: string, retry: { dueAt: string; reason: string }): Promise<void>;
   appendTurnUpdate(input: AppendTurnUpdateInput): Promise<StoredTurnUpdate>;
   appendTurnUpdates(input: AppendTurnUpdatesInput): Promise<readonly StoredTurnUpdate[]>;
   sealTurn(input: SealConversationTurnInput): Promise<ConversationTurn>;

package/host/sqlite/index.js

@@ -5,7 +5,7 @@ import { TurnAdmissions } from './admissions.js';
 import { openDatabase } from './database.js';
 import { migrate } from './schema.js';
 import { SqliteConversationStoreError, required } from './errors.js';
-import { parseJson, stringify, conversationFromRow, turnFromRow, updateFromRow, messageFromRow, checkpointFromRow } from './rows.js';
+import { parseJson, stringify, deliveryObservation, conversationFromRow, turnFromRow, updateFromRow, messageFromRow, checkpointFromRow } from './rows.js';
 
 export { SqliteConversationStoreError } from './errors.js';
 export { createSqliteJournalBatchPolicy } from './batching.js';
@@ -227,24 +227,29 @@ export class SqliteConversationStore {
         const ledger = { ...createStepUsageLedger(turn.conversation_id, turn.id), steps: records.flatMap(record => record.step ? [record.step] : []) };
         if (recordStepUsage(ledger, step) === ledger) return;
       }
-      records.push({ usage: normalizeUsage(input.observation.usage), raw: input.observation.raw ?? null, ...(step ? { step } : {}) });
+      const record = { usage: normalizeUsage(input.observation.usage), raw: input.observation.raw ?? null, ...(step ? { step } : {}) };
+      records.push(record);
       this.database.prepare('UPDATE turns SET usage_json = ? WHERE id = ?').run(stringify(records), turn.id);
       if (step && parseJson(turn.execution_json, {}).auth?.mode !== 'platform') {
-        this.database.prepare('INSERT INTO usage_deliveries(turn_id, step_id) VALUES (?, ?)').run(turn.id, step.stepId);
+        this.database.prepare(`INSERT INTO usage_deliveries(turn_id, step_id, observation_json, due_at)
+          VALUES (?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`).run(turn.id, step.stepId, deliveryObservation(record));
       }
     })();
   }
 
+  /**
+   * Deliveries that are due now, oldest first. CROSS JOIN keeps the due index as
+   * the driving table, so the read is bounded by due rows, never by history.
+   */
   async pendingUsage(ownerUserId, limit = 100) {
     return this.database.prepare(`
-      SELECT d.turn_id, d.step_id, c.id AS conversation_id, c.owner_user_id, t.execution_json, j.value AS observation_json
-      FROM usage_deliveries d JOIN turns t ON t.id = d.turn_id
-      JOIN conversations c ON c.id = t.conversation_id
-      JOIN json_each(t.usage_json) j ON json_extract(j.value, '$.step.stepId') = d.step_id
-      WHERE c.owner_user_id = ? AND d.delivered_at IS NULL
-      ORDER BY t.created_at, json_extract(j.value, '$.step.ordinal') LIMIT ?
+      SELECT d.turn_id, d.step_id, d.attempts, d.observation_json, t.conversation_id, t.execution_json
+      FROM usage_deliveries d CROSS JOIN turns t ON t.id = d.turn_id
+      CROSS JOIN conversations c ON c.id = t.conversation_id
+      WHERE d.delivered_at IS NULL AND d.due_at <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now') AND c.owner_user_id = ?
+      ORDER BY d.due_at LIMIT ?
     `).all(ownerUserId, limit).map(row => ({
-      conversationId: row.conversation_id, turnId: row.turn_id, stepId: row.step_id,
+      conversationId: row.conversation_id, turnId: row.turn_id, stepId: row.step_id, attempts: row.attempts,
       execution: parseJson(row.execution_json, {}), observation: parseJson(row.observation_json, {}),
     }));
   }
@@ -256,6 +261,14 @@ export class SqliteConversationStore {
     `).run(turnId, stepId, ownerUserId);
   }
 
+  /** Record a refused attempt; the delivery stays pending and becomes due again at dueAt. */
+  async deferUsage(ownerUserId, turnId, stepId, { dueAt, reason }) {
+    this.database.prepare(`UPDATE usage_deliveries SET attempts = attempts + 1, due_at = ?, last_error = ?
+      WHERE turn_id = ? AND step_id = ? AND delivered_at IS NULL AND turn_id IN
+        (SELECT t.id FROM turns t JOIN conversations c ON c.id = t.conversation_id WHERE c.owner_user_id = ?)
+    `).run(required(dueAt, 'dueAt'), String(reason ?? ''), turnId, stepId, ownerUserId);
+  }
+
   async appendTurnUpdate(input) {
     const updates = await this.appendTurnUpdates({
       ...input,

package/host/sqlite/rows.js

@@ -9,6 +9,11 @@ export function stringify(value) {
   return JSON.stringify(value ?? null);
 }
 
+/** The committed step as delivered: its measurement without the provider's raw evidence. */
+export function deliveryObservation({ usage, step: { raw: _raw, ...step } }) {
+  return stringify({ usage, step });
+}
+
 export function boolean(value) {
   return Number(value) === 1;
 }

package/host/sqlite/schema.js

@@ -1,7 +1,8 @@
 import { migrateTurnQueue } from './queue-migration.js';
+import { migrateUsageDeliveries } from './usage-migration.js';
 import { SqliteConversationStoreError } from './errors.js';
 
-const SCHEMA_VERSION = 5;
+const SCHEMA_VERSION = 6;
 
 export function migrate(database) {
   const version = Number(database.pragma('user_version', { simple: true }));
@@ -12,7 +13,8 @@ export function migrate(database) {
     );
   }
   if (version === SCHEMA_VERSION) return;
-  if (version === 4) { migrateTurnQueue(database); return; }
+  if (version === 5) { migrateUsageDeliveries(database); return; }
+  if (version === 4) { migrateTurnQueue(database); migrate(database); return; }
   if (version === 3) {
     database.exec(`
       BEGIN IMMEDIATE;

package/host/sqlite/usage-migration.js

@@ -0,0 +1,47 @@
+import { deliveryObservation, parseJson } from './rows.js';
+
+/**
+ * Give every delivery its own committed payload and retry schedule, so reading
+ * pending usage touches only pending rows and never re-reads turn journals.
+ * Each journal is parsed once here; a delivery with no journaled step has
+ * nothing to deliver and is not carried forward.
+ */
+export function migrateUsageDeliveries(database) {
+  database.transaction(() => {
+    database.exec(`
+      ALTER TABLE usage_deliveries RENAME TO usage_deliveries_v5;
+      DROP INDEX usage_deliveries_pending_idx;
+      CREATE TABLE usage_deliveries (
+        turn_id TEXT NOT NULL REFERENCES turns(id) ON DELETE CASCADE,
+        step_id TEXT NOT NULL,
+        observation_json TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts >= 0),
+        due_at TEXT NOT NULL,
+        last_error TEXT,
+        delivered_at TEXT,
+        PRIMARY KEY(turn_id, step_id)
+      );
+      CREATE INDEX usage_deliveries_due_idx ON usage_deliveries(due_at) WHERE delivered_at IS NULL;
+    `);
+    const turns = database.prepare(`
+      SELECT id, usage_json, created_at FROM turns
+      WHERE id IN (SELECT turn_id FROM usage_deliveries_v5) ORDER BY created_at, rowid
+    `).all();
+    const deliveries = database.prepare('SELECT step_id, delivered_at FROM usage_deliveries_v5 WHERE turn_id = ?');
+    const insert = database.prepare(`
+      INSERT INTO usage_deliveries(turn_id, step_id, observation_json, due_at, delivered_at) VALUES (?, ?, ?, ?, ?)
+    `);
+    for (const turn of turns) {
+      const deliveredAt = new Map(deliveries.all(turn.id).map(row => [row.step_id, row.delivered_at]));
+      for (const record of parseJson(turn.usage_json, [])) {
+        if (!record.step || !deliveredAt.has(record.step.stepId)) continue;
+        insert.run(turn.id, record.step.stepId, deliveryObservation(record), turn.created_at, deliveredAt.get(record.step.stepId));
+      }
+    }
+    database.exec(`
+      DROP TABLE usage_deliveries_v5;
+      INSERT INTO schema_migrations(version, applied_at) VALUES (6, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+      PRAGMA user_version = 6;
+    `);
+  })();
+}

package/host/title-generator.js

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+
 import { fetchPlatformEgress, platformMetadataHeaders } from './platform-egress.js';
 
 export const TITLE_MODEL_ID = 'openai/gpt-5.6-luna';
@@ -49,7 +51,7 @@ export async function* generateConversationTitle({ conversationId, message, prox
       'content-type': 'application/json',
       ...platformMetadataHeaders({
         sessionId: conversationId,
-        assistantMessageId: `title:${conversationId}`,
+        assistantMessageId: randomUUID(),
         agentId: 'amalgm-title-generator',
         harness: 'title-generator',
         authMethod: 'amalgm',

package/host/usage-delivery.js

@@ -18,39 +18,75 @@ export async function beginPlatformTurn(proxy, contract) {
   if (!decision.skipped) await post(proxy, '/internal/turn-start', decision.body);
 }
 
-/** Deliver committed steps only. Acknowledgement is separate from the measurement. */
-export function createUsageDelivery({ store, ownerUserId, getProxy, intervalMs = 1000, onError = console.warn }) {
+function usageBody({ execution, observation, conversationId, turnId }) {
+  const step = observation.step;
+  return {
+    sessionId: conversationId, messageId: turnId,
+    agentId: execution.agent.installationId, harnessId: execution.agent.adapterId,
+    authMethod: execution.auth.mode === 'subscription' ? 'provider_auth' : 'byok',
+    modelId: step.model.model, provider: step.model.provider,
+    stepId: step.stepId, ordinal: step.ordinal, operation: step.operation,
+    source: step.source, exactness: step.exactness, usage: {
+      inputTokens: step.inputTokens, outputTokens: step.outputTokens,
+      cacheReadTokens: step.cacheReadTokens, cacheWriteTokens: step.cacheWriteTokens,
+    }, costUsd: observation.usage.costUsd,
+  };
+}
+
+/**
+ * A 4xx that is about the record itself: sending the same record again now
+ * cannot succeed, but the records behind it can. Auth, timeout, and rate
+ * limits describe the destination instead and pause the whole queue.
+ */
+function refusesRecord(error) {
+  return error.status >= 400 && error.status < 500 && ![401, 403, 408, 429].includes(error.status);
+}
+
+/**
+ * Deliver committed steps only. Acknowledgement is separate from the measurement.
+ * An unavailable destination backs the queue off; a refused record is retried on
+ * its own schedule and never blocks the records behind it.
+ */
+export function createUsageDelivery({ store, ownerUserId, getProxy, intervalMs = 1000, maxBackoffMs = 300_000,
+  refusedRetryMs = 60_000, maxRefusedRetryMs = 21_600_000, now = Date.now, onError = console.warn }) {
   let active = null;
   let closed = false;
   const flush = () => {
     if (active) return active;
     active = (async () => {
+      const refused = [];
       for (const record of await store.pendingUsage(ownerUserId)) {
-        const { execution, observation, conversationId, turnId } = record;
-        const step = observation.step;
-        await post(getProxy(), '/internal/usage', {
-          sessionId: conversationId, messageId: turnId,
-          agentId: execution.agent.installationId, harnessId: execution.agent.adapterId,
-          authMethod: execution.auth.mode === 'subscription' ? 'provider_auth' : 'byok',
-          modelId: step.model.model, provider: step.model.provider,
-          stepId: step.stepId, ordinal: step.ordinal, operation: step.operation,
-          source: step.source, exactness: step.exactness, usage: {
-            inputTokens: step.inputTokens, outputTokens: step.outputTokens,
-            cacheReadTokens: step.cacheReadTokens, cacheWriteTokens: step.cacheWriteTokens,
-          }, costUsd: observation.usage.costUsd,
-        });
-        await store.acknowledgeUsage(ownerUserId, turnId, step.stepId);
+        const { turnId, stepId, attempts } = record;
+        try {
+          await post(getProxy(), '/internal/usage', usageBody(record));
+        } catch (error) {
+          if (!refusesRecord(error)) throw error;
+          const retryMs = Math.min(refusedRetryMs * 2 ** attempts, maxRefusedRetryMs);
+          await store.deferUsage(ownerUserId, turnId, stepId, { dueAt: new Date(now() + retryMs).toISOString(), reason: error.message });
+          refused.push(error.message);
+          continue;
+        }
+        await store.acknowledgeUsage(ownerUserId, turnId, stepId);
       }
+      if (refused.length) onError(`[Chat usage] Destination refused ${refused.length} step(s); retrying later: ${refused[0]}`);
     })().finally(() => { active = null; });
     return active;
   };
+  let timer = null;
+  let delayMs = intervalMs;
   let reportedError = null;
-  const tick = () => { if (!closed) void flush().then(() => { reportedError = null; }, error => {
-    if (reportedError !== error.message) onError(`[Chat usage] Delivery pending: ${error.message}`);
-    reportedError = error.message;
-  }); };
-  const timer = setInterval(tick, intervalMs);
-  timer.unref?.();
+  const tick = () => {
+    if (closed) return;
+    void flush().then(() => { delayMs = intervalMs; reportedError = null; }, error => {
+      delayMs = Math.min(delayMs * 2, maxBackoffMs);
+      if (reportedError !== error.message) onError(`[Chat usage] Delivery pending: ${error.message}`);
+      reportedError = error.message;
+    }).finally(() => {
+      if (closed) return;
+      timer = setTimeout(tick, delayMs);
+      timer.unref?.();
+    });
+  };
   tick();
-  return { flush, async close() { closed = true; clearInterval(timer); await active?.catch(() => {}); } };
+  return { flush, async close() { closed = true; clearTimeout(timer); await active?.catch(() => {}); } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/chat",
-  "version": "0.2.9-preview.35480111675",
+  "version": "0.2.9-preview.36053697119",
   "description": "A provider-agnostic agent chat SDK with ACP content, prepared execution, normalized streams, and usage.",
   "type": "module",
   "license": "UNLICENSED",
@@ -119,11 +119,11 @@
   "allowScripts": {
     "better-sqlite3@12.11.1": true
   },
-  "gitHead": "399cea2ea226d47877e6686902a5321dea9645bd",
+  "gitHead": "f825aef403a999349cd54940687f3fbcc3f8ca25",
   "amalgmSource": {
     "repository": "amalgm-inc/amalgm-chat",
     "branch": "preview",
-    "commit": "399cea2ea226d47877e6686902a5321dea9645bd",
-    "occurrence": "35480111675"
+    "commit": "f825aef403a999349cd54940687f3fbcc3f8ca25",
+    "occurrence": "36053697119"
   }
 }