@amalgm/chat 0.1.2 → 0.2.1

package/dist/usage/steps.d.ts

@@ -0,0 +1,70 @@
+/** The four billable token categories Amalgm normalizes for every model step. */
+export interface UsageTokenCounts {
+    /** Non-cached input tokens. */
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+}
+export type UsageExactness = 'exact' | 'derived' | 'partial';
+export interface StepUsageModel {
+    adapter: string;
+    provider: string;
+    model: string;
+}
+/** One immutable usage record for one provider model invocation. */
+export interface StepUsage extends UsageTokenCounts {
+    type: 'usage.step';
+    conversationId: string;
+    turnId: string;
+    stepId: string;
+    /** Zero-based model-invocation order within the turn. */
+    ordinal: number;
+    model: StepUsageModel;
+    source: string;
+    exactness: UsageExactness;
+    raw: unknown;
+}
+export interface StepUsageInput {
+    conversationId: string;
+    turnId: string;
+    stepId: string;
+    ordinal: number;
+    model: StepUsageModel;
+    inputTokens?: unknown;
+    outputTokens?: unknown;
+    cacheReadTokens?: unknown;
+    cacheWriteTokens?: unknown;
+    source: string;
+    exactness: UsageExactness;
+    raw?: unknown;
+}
+export interface StepUsageLedger {
+    conversationId: string;
+    turnId: string;
+    steps: readonly StepUsage[];
+}
+export interface TurnUsage extends UsageTokenCounts {
+    type: 'usage.turn';
+    conversationId: string;
+    turnId: string;
+    stepIds: readonly string[];
+    exactness: UsageExactness;
+    source: 'step_sum';
+}
+/** Normalize native usage without turning missing values into zero. */
+export declare function createStepUsage(input: StepUsageInput): StepUsage;
+export declare function createStepUsageLedger(conversationId: string, turnId: string): StepUsageLedger;
+/**
+ * Finalize a step exactly once. Identical replay is idempotent; conflicting
+ * facts for the same step or ordinal are rejected rather than double-counted.
+ */
+export declare function recordStepUsage(ledger: StepUsageLedger, usage: StepUsage): StepUsageLedger;
+/** Derive the turn record from its ordered, finalized model steps. */
+export declare function aggregateTurnUsage(ledger: StepUsageLedger): TurnUsage;
+/**
+ * Convert a cumulative meter into a delta only when a prior baseline exists.
+ * Counter resets remain unknown instead of being clamped into plausible data.
+ */
+export declare function usageDeltaFromCumulative(current: UsageTokenCounts, previous: UsageTokenCounts | null): UsageTokenCounts;
+//# sourceMappingURL=steps.d.ts.map

package/dist/usage/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../src/usage/steps.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IACjD,IAAI,EAAE,YAAY,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,cAAc,CAAC;IAC1B,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,cAAc,CAAC;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IACjD,IAAI,EAAE,YAAY,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,UAAU,CAAC;CACpB;AA6BD,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAoBhE;AAED,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,eAAe,CAMjB;AAsBD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,SAAS,GACf,eAAe,CAoBjB;AAqBD,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAarE;AAOD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAChC,gBAAgB,CAelB"}

package/dist/usage/steps.js

@@ -0,0 +1,152 @@
+function nonEmpty(value, label) {
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new TypeError(`${label} must be a non-empty string`);
+    return normalized;
+}
+function tokenCount(value, label) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${label} must be a non-negative safe integer or null`);
+    }
+    return value;
+}
+function usageExactness(value) {
+    if (value === 'exact' || value === 'derived' || value === 'partial')
+        return value;
+    throw new TypeError('exactness must be exact, derived, or partial');
+}
+function normalizeModel(model) {
+    return Object.freeze({
+        adapter: nonEmpty(model.adapter, 'model.adapter'),
+        provider: nonEmpty(model.provider, 'model.provider'),
+        model: nonEmpty(model.model, 'model.model'),
+    });
+}
+/** Normalize native usage without turning missing values into zero. */
+export function createStepUsage(input) {
+    if (!Number.isSafeInteger(input.ordinal) || input.ordinal < 0) {
+        throw new TypeError('ordinal must be a non-negative safe integer');
+    }
+    return Object.freeze({
+        type: 'usage.step',
+        conversationId: nonEmpty(input.conversationId, 'conversationId'),
+        turnId: nonEmpty(input.turnId, 'turnId'),
+        stepId: nonEmpty(input.stepId, 'stepId'),
+        ordinal: input.ordinal,
+        model: normalizeModel(input.model),
+        inputTokens: tokenCount(input.inputTokens, 'inputTokens'),
+        outputTokens: tokenCount(input.outputTokens, 'outputTokens'),
+        cacheReadTokens: tokenCount(input.cacheReadTokens, 'cacheReadTokens'),
+        cacheWriteTokens: tokenCount(input.cacheWriteTokens, 'cacheWriteTokens'),
+        source: nonEmpty(input.source, 'source'),
+        exactness: usageExactness(input.exactness),
+        raw: Object.hasOwn(input, 'raw') ? input.raw : null,
+    });
+}
+export function createStepUsageLedger(conversationId, turnId) {
+    return Object.freeze({
+        conversationId: nonEmpty(conversationId, 'conversationId'),
+        turnId: nonEmpty(turnId, 'turnId'),
+        steps: Object.freeze([]),
+    });
+}
+function sameModel(left, right) {
+    return left.adapter === right.adapter
+        && left.provider === right.provider
+        && left.model === right.model;
+}
+function sameFinalizedFacts(left, right) {
+    return left.conversationId === right.conversationId
+        && left.turnId === right.turnId
+        && left.stepId === right.stepId
+        && left.ordinal === right.ordinal
+        && sameModel(left.model, right.model)
+        && left.inputTokens === right.inputTokens
+        && left.outputTokens === right.outputTokens
+        && left.cacheReadTokens === right.cacheReadTokens
+        && left.cacheWriteTokens === right.cacheWriteTokens
+        && left.source === right.source
+        && left.exactness === right.exactness;
+}
+/**
+ * Finalize a step exactly once. Identical replay is idempotent; conflicting
+ * facts for the same step or ordinal are rejected rather than double-counted.
+ */
+export function recordStepUsage(ledger, usage) {
+    if (usage.conversationId !== ledger.conversationId || usage.turnId !== ledger.turnId) {
+        throw new Error('step usage belongs to a different conversation or turn');
+    }
+    const existing = ledger.steps.find((step) => step.stepId === usage.stepId);
+    if (existing !== undefined) {
+        if (!sameFinalizedFacts(existing, usage)) {
+            throw new Error(`conflicting finalized usage for step ${usage.stepId}`);
+        }
+        return ledger;
+    }
+    const ordinalOwner = ledger.steps.find((step) => step.ordinal === usage.ordinal);
+    if (ordinalOwner !== undefined) {
+        throw new Error(`step ordinal ${usage.ordinal} already belongs to ${ordinalOwner.stepId}`);
+    }
+    const steps = Object.freeze([...ledger.steps, usage].sort((a, b) => a.ordinal - b.ordinal));
+    return Object.freeze({ ...ledger, steps });
+}
+function sumKnown(steps, field) {
+    let sum = 0;
+    for (const step of steps) {
+        const value = step[field];
+        if (value === null)
+            return null;
+        sum += value;
+        if (!Number.isSafeInteger(sum))
+            throw new RangeError(`${field} sum exceeds safe integer range`);
+    }
+    return steps.length === 0 ? null : sum;
+}
+function aggregateExactness(steps) {
+    if (steps.length === 0 || steps.some((step) => step.exactness === 'partial'))
+        return 'partial';
+    return steps.every((step) => step.exactness === 'exact') ? 'exact' : 'derived';
+}
+/** Derive the turn record from its ordered, finalized model steps. */
+export function aggregateTurnUsage(ledger) {
+    return Object.freeze({
+        type: 'usage.turn',
+        conversationId: ledger.conversationId,
+        turnId: ledger.turnId,
+        stepIds: Object.freeze(ledger.steps.map((step) => step.stepId)),
+        inputTokens: sumKnown(ledger.steps, 'inputTokens'),
+        outputTokens: sumKnown(ledger.steps, 'outputTokens'),
+        cacheReadTokens: sumKnown(ledger.steps, 'cacheReadTokens'),
+        cacheWriteTokens: sumKnown(ledger.steps, 'cacheWriteTokens'),
+        exactness: aggregateExactness(ledger.steps),
+        source: 'step_sum',
+    });
+}
+function cumulativeDelta(current, previous) {
+    if (current === null || previous === null || current < previous)
+        return null;
+    return current - previous;
+}
+/**
+ * Convert a cumulative meter into a delta only when a prior baseline exists.
+ * Counter resets remain unknown instead of being clamped into plausible data.
+ */
+export function usageDeltaFromCumulative(current, previous) {
+    if (previous === null) {
+        return {
+            inputTokens: null,
+            outputTokens: null,
+            cacheReadTokens: null,
+            cacheWriteTokens: null,
+        };
+    }
+    return {
+        inputTokens: cumulativeDelta(current.inputTokens, previous.inputTokens),
+        outputTokens: cumulativeDelta(current.outputTokens, previous.outputTokens),
+        cacheReadTokens: cumulativeDelta(current.cacheReadTokens, previous.cacheReadTokens),
+        cacheWriteTokens: cumulativeDelta(current.cacheWriteTokens, previous.cacheWriteTokens),
+    };
+}
+//# sourceMappingURL=steps.js.map

package/dist/usage/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/usage/steps.ts"],"names":[],"mappings":"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"}

package/dist/usage/tokens.d.ts

@@ -1,14 +1,11 @@
 /**
- * Token counting primitives — engine `chat-core/usage.js:11-63,118-127`,
- * ported byte-exact. Owned by the usage module; the wire module imports
- * `totalUsageTokens` for PromptUsage projection.
+ * Token counting primitives owned by the usage module.
  */
-/** Engine `n()`: coerce to a finite number, else 0. */
+/** Coerce to a finite number, else 0. */
 export declare function n(value: unknown): number;
 /**
- * Engine `nonNegativeOrNull()`: the numeric value when finite and >= 0,
- * else null. Note `Number(null)` is 0, so null coerces to 0 here — callers
- * relying on "absent" must pass `undefined`.
+ * Return the numeric value when finite and non-negative, otherwise null.
+ * `Number(null)` is zero, so callers representing absence pass `undefined`.
  */
 export declare function nonNegativeOrNull(value: unknown): number | null;
 /** The six-bucket token list every normalized usage record carries. */

package/dist/usage/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/usage/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uDAAuD;AACvD,wBAAgB,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,cAAmB,GAAG,SAAS,CAoBxE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,OAAO,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,OAAO,CAAC,CAAM,GAAG,OAAO,CAGtG;AAED,uDAAuD;AACvD,wBAAgB,aAAa,IAAI,SAAS,CAEzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAE,OAAO,CAAC,SAAS,CAAM,EAAE,CAAC,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAQ/F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,OAAO,CAAC,SAAS,CAAM,EAAE,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAQ7G;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,SAAc,GAAG,MAAM,CAM9D"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/usage/tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,yCAAyC;AACzC,wBAAgB,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGxC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,cAAmB,GAAG,SAAS,CAoBxE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,OAAO,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,OAAO,CAAC,CAAM,GAAG,OAAO,CAGtG;AAED,uDAAuD;AACvD,wBAAgB,aAAa,IAAI,SAAS,CAEzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAE,OAAO,CAAC,SAAS,CAAM,EAAE,CAAC,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAQ/F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,OAAO,CAAC,SAAS,CAAM,EAAE,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAQ7G;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,SAAc,GAAG,MAAM,CAM9D"}

package/dist/usage/tokens.js

@@ -1,17 +1,14 @@
 /**
- * Token counting primitives — engine `chat-core/usage.js:11-63,118-127`,
- * ported byte-exact. Owned by the usage module; the wire module imports
- * `totalUsageTokens` for PromptUsage projection.
+ * Token counting primitives owned by the usage module.
  */
-/** Engine `n()`: coerce to a finite number, else 0. */
+/** Coerce to a finite number, else 0. */
 export function n(value) {
     const parsed = Number(value || 0);
     return Number.isFinite(parsed) ? parsed : 0;
 }
 /**
- * Engine `nonNegativeOrNull()`: the numeric value when finite and >= 0,
- * else null. Note `Number(null)` is 0, so null coerces to 0 here — callers
- * relying on "absent" must pass `undefined`.
+ * Return the numeric value when finite and non-negative, otherwise null.
+ * `Number(null)` is zero, so callers representing absence pass `undefined`.
  */
 export function nonNegativeOrNull(value) {
     const parsed = Number(value);

package/dist/usage/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/usage/tokens.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/usage/tokens.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,51 @@
+# ACP and step usage contract
+
+## Decision
+
+The public agent/client shape is ACP v1 from `@agentclientprotocol/sdk`.
+Prompts are official ACP content blocks and provider output is official ACP
+`SessionUpdate`. Chat does not maintain a second browser or provider event
+grammar.
+
+Amalgm durability metadata lives only at `_meta.amalgm`:
+
+```text
+conversationId · turnId · sequence · native event type · timestamp · raw event
+```
+
+The sequence is assigned by the durable journal before fanout. It is the replay
+cursor, not a provider stream index.
+
+## Output
+
+| Part | ACP update |
+| --- | --- |
+| assistant text | `agent_message_chunk` |
+| reasoning | `agent_thought_chunk` |
+| tool start | `tool_call` |
+| tool progress/result | `tool_call_update` |
+| plan, mode, config, commands, session info, context | their official ACP session updates |
+
+Adapters may reject unsupported input with a typed error. They may not silently
+drop it or disguise non-text state as text.
+
+## Step usage
+
+Stable ACP context updates describe occupancy, not a complete billing ledger.
+Chat therefore owns one separate usage extension for a model invocation.
+
+1. A step is one provider model invocation.
+2. `(turnId, stepId)` is its idempotency key.
+3. Every bucket is a non-negative integer or `null`; missing and measured zero
+   are different facts.
+4. Re-recording identical final facts is a no-op. Conflicting final facts are
+   rejected.
+5. A turn bucket is summed only when every contributing step reports it.
+6. A cumulative counter becomes a delta only against a proven prior baseline.
+7. Raw provider evidence and provenance survive normalization.
+8. Billing settlement remains owned by the billing authority, not ACP context
+   telemetry.
+
+The usage algebra and idempotency laws are fully tested. Provider adapters may
+still report incomplete native evidence; those fields remain `null` until the
+provider proves them.

package/docs/contracts/conversation-persistence.md

@@ -0,0 +1,47 @@
+# Conversation persistence and durable turns
+
+## Purpose
+
+A conversation keeps one identity across subscribers, reconnects, host
+restarts, and execution-computer changes. Live delivery, replay, and reload
+reduce to the same transcript.
+
+## Stored primitives
+
+```text
+conversations         private identity and header
+turns                 accepted prompt, execution snapshot, status, result
+turn_updates          append-only official ACP update journal
+messages              user/assistant transcript projection
+provider_checkpoints  exact-execution native continuation evidence
+schema_migrations     explicit local schema version
+```
+
+One owner-scoped database contains many conversations across installed agents.
+Agent Homes remain isolated by installation and are not folded into this
+database.
+
+## Laws
+
+1. The host supplies one owner when constructing Chat.
+2. A conversation belongs to one agent installation. A provider session,
+   process, socket, subscriber, filesystem path, or computer is not identity.
+3. Accepting a turn commits its prompt, execution snapshot, user message, and
+   running state before provider invocation.
+4. Every provider update commits before fanout.
+5. `(turnId, sequence)` is unique and sequence increases by one.
+6. One runtime pump owns provider iteration; subscribers are disposable cursor
+   readers.
+7. Subscription registers for live delivery before replaying the committed
+   tail, then removes duplicates by sequence.
+8. Terminal state, assistant transcript, and conversation activity seal once
+   in one transaction.
+9. Restart marks uncertain unsealed work interrupted unless an adapter proves
+   reattachment. Chat never silently repeats external effects.
+10. Provider checkpoints resume only the exact prepared execution revision
+    that created them.
+11. SQLite WAL is the local working authority. Synchronization, when added,
+    moves logical records and immutable batches, never a live SQLite file.
+
+The canonical application projection uses camelCase `ConversationRecord`,
+`ConversationMessage`, and `ConversationTurn` values from this package.

package/docs/contracts/input-and-execution.md

@@ -0,0 +1,177 @@
+# Prompt input and prepared execution
+
+This is the public input contract for `@amalgm/chat`. It is deliberately small:
+prompt content is ACP content, while every choice needed to execute that prompt
+is resolved into an immutable handle before the runtime starts a turn.
+
+## Purpose
+
+A developer should be able to start a session and send the same prompt through
+any registered agent without learning provider payloads. Preparation owns
+discovery and resolution; start and send consume its result.
+
+## Primitives
+
+- A **prompt** is a non-empty, ordered list of official ACP content blocks.
+- An **attachment** is any non-text ACP content block. It is already embedded or
+  addressable when the prompt is accepted.
+- An **execution contract** is the normalized set of choices for one future
+  turn: tools, auth, cwd, permission mode, agent revision, provider-scoped
+  model and settings, and execution computer.
+- A **prepared execution** is an execution contract plus an opaque host binding.
+  The host binding contains the already-resolved effects required by the
+  adapter. It is never serialized by the SDK.
+- An **execution handle** is `{ id, revision }`. Send carries this handle and
+  prompt content only.
+
+## Axioms
+
+1. Prompt parts use the official ACP `ContentBlock` type and retain their order.
+2. Chat never fetches, uploads, reads, or rewrites an attachment on the send
+   path. A host prepares attachment bytes or references before enabling send.
+3. Every execution field is explicit. Missing auth, provider, model, agent
+   revision, cwd, permission mode, or computer is an error; there are no silent
+   defaults or fallback auth modes.
+4. A model is identified by `(agent revision, provider id, model id)`. Model
+   settings are ACP session-config selections scoped inside that model choice.
+5. Ordinary tools and MCP tools are selected through one immutable toolset
+   revision. `amalgm-tools` resolves that revision to the complete official ACP
+   MCP server configuration during preparation; Chat adds no ambient server.
+6. Secrets are not execution-contract values. Auth names an opaque binding; the
+   authorized host resolves secrets into the opaque prepared binding.
+7. A cwd is an absolute, already-materialized path on the selected computer. A
+   Live workspace id and materialization revision are either both present or
+   both absent.
+8. Preparation validates provider/model availability, agent capabilities,
+   permission support, tools, auth, cwd, and computer placement. Send performs
+   one in-memory `{id, revision}` lookup and never calls preparation.
+9. A prepared revision is immutable. Any execution-relevant change creates a
+   different revision.
+10. Execution is selected per turn, not frozen to an Amalgm conversation.
+    Changing auth or computer keeps the conversation id and may cause the host
+    adapter to replace its native provider session.
+11. A native provider checkpoint is scoped to the execution that created it.
+    An adapter may reuse it after an execution change only with an explicit
+    continuation proof; the reference host starts a new native session.
+12. Every selected input is applied exactly or rejected with a typed error
+    before prompting. No adapter may silently ignore an attachment, auth mode,
+    tool, permission mode, model setting, provider/model choice, cwd, agent
+    revision, or computer placement.
+
+## Public path
+
+```ts
+const execution = await chat.prepareExecution("composer", {
+  agent: {
+    adapterId: "codex",
+    installationId: "agent-installation",
+    revisionId: "agent-revision",
+  },
+  model: {
+    providerId: "openai",
+    modelId: "gpt-5.6-codex",
+    settings: [{ configId: "thought_level", value: "high" }],
+  },
+  auth: { mode: "subscription", bindingId: "codex-login" },
+  tools: { revisionId: null, toolIds: [] },
+  cwd: {
+    path: "/workspace/project",
+    workspaceId: null,
+    materializationRevision: null,
+  },
+  permissionMode: "ask",
+  computerId: "computer-1",
+});
+
+const session = await chat.startSession({ execution });
+const updates = await session.send({
+  execution,
+  prompt: { parts: [{ type: "text", text: "Hello" }] },
+});
+
+for await (const update of updates) render(update);
+```
+
+`prepareExecution` is the control plane. `startSession` and `send` are the hot
+path. Tests must prove that neither hot-path operation can call the preparation
+port.
+
+## Adapter input contract
+
+The scalable adapter set is five native adapters plus one generic ACP adapter.
+Amp, Gemini CLI, Kiro, and any other compliant ACP agent enter through the
+generic adapter; they do not get product-name branches.
+
+| Adapter | Auth | Model settings | Tools | Attachment rule |
+| --- | --- | --- | --- | --- |
+| Codex | platform, subscription, BYOK | reasoning and speed | selected MCP servers | native text/image/audio/file projection |
+| Claude Code | platform, subscription, BYOK | reasoning and speed | selected MCP servers | native text/image/document/PDF projection; audio rejects |
+| Cursor | subscription, BYOK Cursor API key; platform rejects | exact reasoning and speed encoded by an advertised Cursor model id | selected ACP MCP servers | ACP capability negotiation |
+| OpenCode | platform, subscription, BYOK | one exact model-catalog `variant`; other settings reject | selected MCP servers | native file parts |
+| Pi | platform, subscription, BYOK | reasoning only; speed rejects | selected MCP servers through the Amalgm Pi extension | native text/image projection |
+| Generic ACP | modes declared by the immutable agent revision | advertised ACP config options | selected ACP MCP servers | ACP capability negotiation |
+
+All six paths accept the same prepared cwd, permission mode, immutable agent
+revision, provider-scoped model, and execution computer. The host validates
+the selected revision/model and placement during preparation. `ask` uses one
+common permission port; `full_access` is explicit rather than a missing
+permission policy.
+
+The generic ACP revision contributes launch facts, never UI conditionals:
+
+```ts
+type AcpLaunch = {
+  command: string;
+  args: string[];
+  supportedAuthModes: ("platform" | "subscription" | "byok")[];
+  env?: Record<string, string>;
+  auth?: {
+    platform?: { tokenEnv: string; baseUrlEnv?: string };
+    byok?: { tokenEnv: string; baseUrlEnv?: string };
+  };
+  authMethodIds?: Partial<Record<AuthMode, string>>;
+  modelConfiguredAtLaunch?: boolean;
+};
+```
+
+At runtime it negotiates ACP protocol version, prompt capabilities, MCP
+transports, load/resume support, config options, permissions, cancel, and
+close. A missing capability becomes `UNSUPPORTED_EXECUTION_INPUT`; it never
+becomes a best-effort fallback.
+
+## Native attachment projection
+
+The SDK never changes the canonical ACP prompt. A host adapter projects it at
+the final native boundary:
+
+| Adapter | Native projection |
+| --- | --- |
+| ACP / Cursor | ACP content blocks unchanged after capability validation |
+| Codex | text, URL/base64 image or audio, local image/audio, or file mention |
+| Claude Code | structured text, image, plain-text document, or PDF blocks |
+| OpenCode | text and URL/data-URL file parts |
+| Pi | text plus its RPC image channel |
+
+When a native protocol lacks a content type, the adapter throws
+`UNSUPPORTED_PROMPT_PART` with the adapter, part index, and part type. It never
+silently drops the part or pretends a missing binary is an attached file.
+
+## Real acceptance
+
+The public `Chat` path has run real text-plus-image turns for all five native
+adapters. Claude Code and Pi additionally passed one combined image, selected
+stdio MCP tool, `ask` permission, tool-result, and streamed-response turn.
+Codex, Cursor, and OpenCode have equivalent real image acceptance; Cursor and
+OpenCode have real selected-tool and permission acceptance. The generic ACP
+adapter has passed text and selected-tool turns against the live Cursor ACP
+server.
+
+OpenCode accepts a model-scoped variant id from its prepared catalog. A live
+`high`-variant session passed OpenCode's model resolution and reached the
+selected Vercel model; that provider then rejected the request for account
+credits, which is external billing state rather than input translation.
+
+Cursor's own API key is BYOK and reaches `cursor-agent acp` only as
+`CURSOR_API_KEY`. Cursor platform auth remains an explicit typed rejection:
+the native product has no Amalgm proxy/billing path. Subscription uses the
+native Cursor login.

package/docs/contracts/platform-authorization.md

@@ -0,0 +1,22 @@
+# Platform authorization contract
+
+Chat never owns a user or machine credential. For platform-auth turns, the
+host injects one live credential broker into the native runtime. Every local
+egress request asks that broker for audience `amalgm-api-proxy` and the exact
+provider scope selected by the frozen route.
+
+The broker returns a short-lived DPoP access token plus a fresh proof for the
+request method and full upstream URL. Chat forwards both, never stores them,
+and retries exactly once when the proxy returns `401` after invalidating the
+rejected access token. There is no fallback to a durable bearer or environment
+variable.
+
+If issuance or proof creation fails, egress returns `503` without contacting
+the provider. The provider adapter propagates failure through the ordinary
+runtime pump, and Chat seals the turn as `failed`; stable host error codes are
+preserved in the durable turn error.
+
+The local relay accepts only its session capability, removes caller-supplied
+credentials and Amalgm metadata, bounds buffered request bytes, rejects
+redirects, and applies response backpressure. These are part of the egress
+boundary, not provider-specific adapter behavior.

package/host/adapters/acp-capabilities.js

@@ -0,0 +1,30 @@
+import { UnsupportedExecutionInputError } from './input-capabilities.js';
+
+/** Validate optional ACP inputs against the capabilities negotiated at initialize. */
+export function assertAcpMcpCapabilities(adapterId, capabilities, servers) {
+  const mcp = capabilities?.mcpCapabilities || {};
+  for (const server of servers) {
+    if ((server.type === 'http' || server.type === 'sse') && mcp[server.type] !== true) {
+      throw new UnsupportedExecutionInputError(
+        adapterId,
+        'tools',
+        `agent does not advertise ACP ${server.type} MCP support`,
+      );
+    }
+  }
+}
+
+export function assertAcpPromptCapabilities(adapterId, capabilities, prompt) {
+  const supported = capabilities?.promptCapabilities || {};
+  for (const part of prompt.parts) {
+    if (part.type === 'image' && supported.image !== true) {
+      throw new UnsupportedExecutionInputError(adapterId, 'attachments', 'agent does not advertise image prompts');
+    }
+    if (part.type === 'audio' && supported.audio !== true) {
+      throw new UnsupportedExecutionInputError(adapterId, 'attachments', 'agent does not advertise audio prompts');
+    }
+    if (part.type === 'resource' && supported.embeddedContext !== true) {
+      throw new UnsupportedExecutionInputError(adapterId, 'attachments', 'agent does not advertise embedded context');
+    }
+  }
+}