@bernierllc/agent-changeset 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,7 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/

package/README.md

@@ -1,45 +1,161 @@
 # @bernierllc/agent-changeset
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@bernierllc/agent-changeset`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Records mutations made by agent tools during a conversation and produces structured user-facing change reports. Accumulates `ChangeRecord` entries (dot-notation actions, before/after state) per conversation, renders per-change one-line summaries for tool-result cards, computes field-level diffs, and produces an end-of-conversation rollup summary (markdown + plain text). Serializable via `toJSON()`/`fromJSON()` for persistence alongside conversation messages.
+
+Designed to be installed as an `@bernierllc/agent-tool-registry` after-hook.
+
+## Installation
+
+```bash
+npm install @bernierllc/agent-changeset
+```
+
+## Quick Start
+
+```typescript
+import { createChangesetRecorder } from '@bernierllc/agent-changeset';
+
+const recorder = createChangesetRecorder();
+const changeset = recorder.forConversation('conv-abc123');
+
+// Record mutations from tool calls
+changeset.record({
+  action: 'admin.service.add',
+  resourceType: 'service',
+  resourceId: 'svc-999',
+  after: { name: 'Haircut', price: 45, durationMinutes: 30 },
+  summary: 'Added service "Haircut" at $45 (30 min)',
+  toolCallId: 'tc-001',
+  success: true,
+});
+
+changeset.record({
+  action: 'admin.discount.create',
+  resourceType: 'discount',
+  resourceId: 'disc-42',
+  after: { code: 'SAVE10', percentOff: 10 },
+  summary: 'Created discount code "SAVE10" (10% off)',
+  toolCallId: 'tc-002',
+  success: true,
+});
+
+// Per-change line summary (for tool-result cards in the UI)
+const [first] = changeset.changes;
+console.log(changeset.renderLineSummary(first.id));
+// '+ Added service "Haircut" at $45 (30 min)'
+
+// End-of-conversation rollup
+const rollup = changeset.renderRollupSummary();
+console.log(rollup.markdown);
+// ### Changes Made This Session
+// **Service** (1 change)
+// - Added service "Haircut" at $45 (30 min)
+//
+// **Discount** (1 change)
+// - Created discount code "SAVE10" (10% off)
+
+console.log(rollup.plainText);
+// 'Here is what changed this session: Service: Added service "Haircut" at $45 (30 min). Discount: Created discount code "SAVE10" (10% off).'
+
+// Persist alongside conversation messages
+const json = changeset.toJSON();
+// store json to your database / agent-conversation-store ...
+
+// Restore from JSON on reconnect
+const restored = recorder.fromJSON(json);
+```
+
+## Field-Level Diffs
+
+For changes that carry both `before` and `after`, `computeDiff()` reports added keys, removed keys, and modified fields:
+
+```typescript
+changeset.record({
+  action: 'admin.service.update',
+  resourceType: 'service',
+  resourceId: 'svc-999',
+  before: { name: 'Haircut', price: 40, durationMinutes: 30 },
+  after:  { name: 'Haircut', price: 45, durationMinutes: 30, active: true },
+  summary: 'Updated service "Haircut" — price $40 to $45, added active flag',
+  toolCallId: 'tc-003',
+  success: true,
+});
+
+const updateChange = changeset.changes[2];
+const diff = changeset.computeDiff(updateChange.id);
+// {
+//   added:    ['active'],
+//   removed:  [],
+//   modified: [{ field: 'price', from: 40, to: 45 }]
+// }
+```
+
+Returns `null` for create-only (no `before`) or delete-only (no `after`) mutations.
+
+## After-Hook Pattern
+
+```typescript
+import { createChangesetRecorder } from '@bernierllc/agent-changeset';
+
+const recorder = createChangesetRecorder();
+const changeset = recorder.forConversation(conversationId);
+
+toolRegistry.addHook({
+  after: async (record, _ctx) => {
+    if (record.state === 'success' && record.output?.success === true) {
+      changeset.record({
+        action: resolveAction(record.toolName),
+        resourceType: record.toolName,
+        toolCallId: record.toolCallId,
+        summary: String(record.output.message ?? record.toolName),
+        success: true,
+      });
+    }
+  },
+});
+```
+
+## API Reference
+
+### `createChangesetRecorder(): ChangesetRecorder`
+
+Entry point. Returns a recorder that creates and restores `ConversationChangeset` instances.
+
+### `ChangesetRecorder`
+
+| Method | Description |
+|---|---|
+| `forConversation(id)` | Create a fresh changeset for the conversation. |
+| `fromJSON(data)` | Restore from `SerializedChangeset`. Throws `InvalidChangesetDataError` if malformed. |
+
+### `ConversationChangeset`
+
+| Method | Description |
+|---|---|
+| `record(entry)` | Add a mutation. Auto-generates `id` (UUID v4) and `timestamp` (ISO 8601). Returns the stored `ChangeRecord`. |
+| `renderLineSummary(changeId)` | One-liner: `"+ summary"` for success, `"- summary"` for failure. Throws `ChangeNotFoundError` if unknown id. |
+| `computeDiff(changeId)` | Field-level diff from `before`/`after`. Returns `null` if either is absent. Throws `ChangeNotFoundError` if unknown id. |
+| `renderRollupSummary()` | End-of-conversation rollup with `totalChanges`, `successfulChanges`, `failedChanges`, `byResourceType`, `markdown`, `plainText`. |
+| `toJSON()` | Plain `SerializedChangeset` for persistence. |
+| `changes` | Read-only ordered array of recorded `ChangeRecord`s. |
+| `conversationId` | The conversation identifier. |
+
+### Error Classes
+
+| Class | Code | When thrown |
+|---|---|---|
+| `ChangesetError` | `CHANGESET_ERROR` | Base class for all package errors. |
+| `ChangeNotFoundError` | `CHANGE_NOT_FOUND` | `renderLineSummary` or `computeDiff` called with unknown `changeId`. |
+| `InvalidChangesetDataError` | `INVALID_CHANGESET_DATA` | `fromJSON` called with malformed data. |
+
+All errors chain the root cause via `Error.cause` and carry a `context` object with debugging details.
+
+## Architecture
+
+- **Core tier** — pure TypeScript, zero runtime dependencies beyond `@bernierllc/logger`.
+- **No I/O** — pure in-memory computation; runs server-side as part of the agent service layer.
+- **MECE** — owns only mutation recording and diff rendering for agent conversations. Persistence is `agent-conversation-store`'s concern. Database audit logging is `admin-agent-service`'s concern.
+
+## License
+
+Bernier LLC limited-use license. See [LICENSE](./LICENSE).

package/dist/changeset.d.ts

@@ -0,0 +1,19 @@
+import type { ChangeRecord, ChangesetDiff, ConversationChangeset, RecordInput, RollupSummary, SerializedChangeset } from './types';
+/**
+ * Implementation of `ConversationChangeset`.
+ * Not exported directly — consumers obtain instances via `createChangesetRecorder`.
+ */
+export declare class ConversationChangesetImpl implements ConversationChangeset {
+    readonly conversationId: string;
+    private readonly _changes;
+    get changes(): ReadonlyArray<ChangeRecord>;
+    constructor(conversationId: string, initialChanges?: ChangeRecord[]);
+    record(entry: RecordInput): ChangeRecord;
+    renderLineSummary(changeId: string): string;
+    computeDiff(changeId: string): ChangesetDiff | null;
+    renderRollupSummary(): RollupSummary;
+    toJSON(): SerializedChangeset;
+    /** @throws {ChangeNotFoundError} */
+    private findChange;
+}
+//# sourceMappingURL=changeset.d.ts.map

package/dist/changeset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changeset.d.ts","sourceRoot":"","sources":["../src/changeset.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAejB;;;GAGG;AACH,qBAAa,yBAA0B,YAAW,qBAAqB;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,IAAI,OAAO,IAAI,aAAa,CAAC,YAAY,CAAC,CAEzC;gBAEW,cAAc,EAAE,MAAM,EAAE,cAAc,GAAE,YAAY,EAAO;IAKvE,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY;IAiBxC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAM3C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAuCnD,mBAAmB,IAAI,aAAa;IA2DpC,MAAM,IAAI,mBAAmB;IAO7B,oCAAoC;IACpC,OAAO,CAAC,UAAU;CAOnB"}

package/dist/changeset.js

@@ -0,0 +1,160 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationChangesetImpl = void 0;
+const crypto_1 = require("crypto");
+const logger_1 = require("@bernierllc/logger");
+const errors_1 = require("./errors");
+const logger = (0, logger_1.createLogger)();
+/**
+ * Capitalises the first character of a string.
+ * Handles empty strings and `noUncheckedIndexedAccess` safely.
+ */
+function capitaliseFirst(str) {
+    if (str.length === 0)
+        return str;
+    const first = str[0];
+    if (first === undefined)
+        return str;
+    return first.toUpperCase() + str.slice(1);
+}
+/**
+ * Implementation of `ConversationChangeset`.
+ * Not exported directly — consumers obtain instances via `createChangesetRecorder`.
+ */
+class ConversationChangesetImpl {
+    conversationId;
+    _changes;
+    get changes() {
+        return this._changes;
+    }
+    constructor(conversationId, initialChanges = []) {
+        this.conversationId = conversationId;
+        this._changes = [...initialChanges];
+    }
+    record(entry) {
+        const change = {
+            ...entry,
+            id: (0, crypto_1.randomUUID)(),
+            timestamp: new Date().toISOString(),
+        };
+        this._changes.push(change);
+        logger.debug('agent-changeset: change recorded', {
+            changeId: change.id,
+            action: change.action,
+            resourceType: change.resourceType,
+            toolCallId: change.toolCallId,
+            success: change.success,
+        });
+        return change;
+    }
+    renderLineSummary(changeId) {
+        const change = this.findChange(changeId);
+        const prefix = change.success ? '+' : '-';
+        return `${prefix} ${change.summary}`;
+    }
+    computeDiff(changeId) {
+        const change = this.findChange(changeId);
+        if (change.before === undefined || change.after === undefined) {
+            return null;
+        }
+        const before = change.before;
+        const after = change.after;
+        const beforeKeys = new Set(Object.keys(before));
+        const afterKeys = new Set(Object.keys(after));
+        const added = [];
+        const removed = [];
+        const modified = [];
+        for (const key of afterKeys) {
+            if (!beforeKeys.has(key)) {
+                added.push(key);
+            }
+        }
+        for (const key of beforeKeys) {
+            if (!afterKeys.has(key)) {
+                removed.push(key);
+            }
+            else {
+                // Both objects have this key; compare values structurally.
+                // Use JSON.stringify for deep equality of unknown values.
+                const fromVal = before[key];
+                const toVal = after[key];
+                if (JSON.stringify(fromVal) !== JSON.stringify(toVal)) {
+                    modified.push({ field: key, from: fromVal, to: toVal });
+                }
+            }
+        }
+        return { added, removed, modified };
+    }
+    renderRollupSummary() {
+        const totalChanges = this._changes.length;
+        const successfulChanges = this._changes.filter((c) => c.success).length;
+        const failedChanges = totalChanges - successfulChanges;
+        // Group by resourceType using a Map to avoid noUncheckedIndexedAccess issues.
+        const groups = new Map();
+        for (const change of this._changes) {
+            let group = groups.get(change.resourceType);
+            if (group === undefined) {
+                group = { count: 0, lines: [] };
+                groups.set(change.resourceType, group);
+            }
+            group.count++;
+            // Rollup lines strip the +/- prefix and expose only the summary text.
+            group.lines.push(change.summary);
+        }
+        // Build byResourceType plain object for the public interface.
+        const byResourceType = {};
+        for (const [type, group] of groups) {
+            byResourceType[type] = group;
+        }
+        // Render markdown.
+        const markdownSections = ['### Changes Made This Session'];
+        const plainTextParts = [];
+        for (const [type, group] of groups) {
+            const heading = capitaliseFirst(type);
+            const countLabel = group.count === 1 ? '1 change' : `${group.count} changes`;
+            markdownSections.push(`**${heading}** (${countLabel})`);
+            for (const line of group.lines) {
+                markdownSections.push(`- ${line}`);
+            }
+            markdownSections.push('');
+            plainTextParts.push(`${heading}: ${group.lines.join('; ')}`);
+        }
+        const markdown = totalChanges === 0
+            ? '### Changes Made This Session\n\nNo changes were made this session.'
+            : markdownSections.join('\n').trimEnd();
+        const plainText = totalChanges === 0
+            ? 'No changes were made this session.'
+            : `Here is what changed this session: ${plainTextParts.join('. ')}.`;
+        return {
+            totalChanges,
+            successfulChanges,
+            failedChanges,
+            byResourceType,
+            plainText,
+            markdown,
+        };
+    }
+    toJSON() {
+        return {
+            conversationId: this.conversationId,
+            changes: [...this._changes],
+        };
+    }
+    /** @throws {ChangeNotFoundError} */
+    findChange(changeId) {
+        const change = this._changes.find((c) => c.id === changeId);
+        if (change === undefined) {
+            throw new errors_1.ChangeNotFoundError(changeId);
+        }
+        return change;
+    }
+}
+exports.ConversationChangesetImpl = ConversationChangesetImpl;
+//# sourceMappingURL=changeset.js.map

package/dist/changeset.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Error thrown by this package for all exceptional conditions.
+ *
+ * Uses ES2022 `Error.cause` chaining per the BernierLLC error propagation
+ * standard so underlying errors are never swallowed.
+ */
+export declare class ChangesetError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        cause?: Error;
+        code?: string;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Thrown when a `changeId` passed to `renderLineSummary` or `computeDiff`
+ * does not match any recorded change in the changeset.
+ */
+export declare class ChangeNotFoundError extends ChangesetError {
+    constructor(changeId: string);
+}
+/**
+ * Thrown when `fromJSON` receives data that does not conform to
+ * `SerializedChangeset` shape.
+ */
+export declare class InvalidChangesetDataError extends ChangesetError {
+    constructor(reason: string, context?: Record<string, unknown>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,KAAK,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CAUJ;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,QAAQ,EAAE,MAAM;CAQ7B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,cAAc;gBAC/C,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQ9D"}

package/dist/errors.js

@@ -0,0 +1,61 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidChangesetDataError = exports.ChangeNotFoundError = exports.ChangesetError = void 0;
+/**
+ * Error thrown by this package for all exceptional conditions.
+ *
+ * Uses ES2022 `Error.cause` chaining per the BernierLLC error propagation
+ * standard so underlying errors are never swallowed.
+ */
+class ChangesetError extends Error {
+    code;
+    context;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'ChangesetError';
+        this.code = options?.code ?? 'CHANGESET_ERROR';
+        if (options?.context !== undefined) {
+            this.context = options.context;
+        }
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+exports.ChangesetError = ChangesetError;
+/**
+ * Thrown when a `changeId` passed to `renderLineSummary` or `computeDiff`
+ * does not match any recorded change in the changeset.
+ */
+class ChangeNotFoundError extends ChangesetError {
+    constructor(changeId) {
+        super(`Change not found: ${changeId}`, {
+            code: 'CHANGE_NOT_FOUND',
+            context: { changeId },
+        });
+        this.name = 'ChangeNotFoundError';
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+exports.ChangeNotFoundError = ChangeNotFoundError;
+/**
+ * Thrown when `fromJSON` receives data that does not conform to
+ * `SerializedChangeset` shape.
+ */
+class InvalidChangesetDataError extends ChangesetError {
+    constructor(reason, context) {
+        super(`Invalid changeset data: ${reason}`, {
+            code: 'INVALID_CHANGESET_DATA',
+            ...(context !== undefined ? { context } : {}),
+        });
+        this.name = 'InvalidChangesetDataError';
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+exports.InvalidChangesetDataError = InvalidChangesetDataError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAEF;;;;;GAKG;AACH,MAAa,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAS;IACb,OAAO,CAA2B;IAE3C,YACE,OAAe,EACf,OAIC;QAED,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,iBAAiB,CAAC;QAC/C,IAAI,OAAO,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACjC,CAAC;QACD,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACpD,CAAC;CACF;AApBD,wCAoBC;AAED;;;GAGG;AACH,MAAa,mBAAoB,SAAQ,cAAc;IACrD,YAAY,QAAgB;QAC1B,KAAK,CAAC,qBAAqB,QAAQ,EAAE,EAAE;YACrC,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,EAAE,QAAQ,EAAE;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACpD,CAAC;CACF;AATD,kDASC;AAED;;;GAGG;AACH,MAAa,yBAA0B,SAAQ,cAAc;IAC3D,YAAY,MAAc,EAAE,OAAiC;QAC3D,KAAK,CAAC,2BAA2B,MAAM,EAAE,EAAE;YACzC,IAAI,EAAE,wBAAwB;YAC9B,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACpD,CAAC;CACF;AATD,8DASC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ChangesetError, ChangeNotFoundError, InvalidChangesetDataError } from './errors';
+export type { ChangeRecord, ChangesetDiff, RollupSummary, SerializedChangeset, RecordInput, ConversationChangeset, ChangesetRecorder, } from './types';
+export { createChangesetRecorder } from './recorder';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAG1F,YAAY,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChangesetRecorder = exports.InvalidChangesetDataError = exports.ChangeNotFoundError = exports.ChangesetError = void 0;
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ChangesetError", { enumerable: true, get: function () { return errors_1.ChangesetError; } });
+Object.defineProperty(exports, "ChangeNotFoundError", { enumerable: true, get: function () { return errors_1.ChangeNotFoundError; } });
+Object.defineProperty(exports, "InvalidChangesetDataError", { enumerable: true, get: function () { return errors_1.InvalidChangesetDataError; } });
+// Factory
+var recorder_1 = require("./recorder");
+Object.defineProperty(exports, "createChangesetRecorder", { enumerable: true, get: function () { return recorder_1.createChangesetRecorder; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAEF,SAAS;AACT,mCAA0F;AAAjF,wGAAA,cAAc,OAAA;AAAE,6GAAA,mBAAmB,OAAA;AAAE,mHAAA,yBAAyB,OAAA;AAavE,UAAU;AACV,uCAAqD;AAA5C,mHAAA,uBAAuB,OAAA"}

package/dist/recorder.d.ts

@@ -0,0 +1,13 @@
+import type { ChangesetRecorder } from './types';
+/**
+ * Creates a `ChangesetRecorder` — the entry point for this package.
+ *
+ * ```typescript
+ * import { createChangesetRecorder } from '@bernierllc/agent-changeset';
+ *
+ * const recorder = createChangesetRecorder();
+ * const changeset = recorder.forConversation('conv-abc123');
+ * ```
+ */
+export declare function createChangesetRecorder(): ChangesetRecorder;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,iBAAiB,EAGlB,MAAM,SAAS,CAAC;AAiGjB;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D"}

package/dist/recorder.js

@@ -0,0 +1,82 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChangesetRecorder = createChangesetRecorder;
+const errors_1 = require("./errors");
+const changeset_1 = require("./changeset");
+/**
+ * Validates that a raw value looks like a `ChangeRecord` and returns it typed.
+ * Throws `InvalidChangesetDataError` if required fields are missing or wrong type.
+ */
+function validateChangeRecord(item, index) {
+    if (typeof item !== 'object' ||
+        item === null ||
+        Array.isArray(item)) {
+        throw new errors_1.InvalidChangesetDataError(`change at index ${index} is not an object`, { index });
+    }
+    const record = item;
+    const requiredStrings = [
+        'id',
+        'action',
+        'resourceType',
+        'summary',
+        'timestamp',
+        'toolCallId',
+    ];
+    for (const field of requiredStrings) {
+        if (typeof record[field] !== 'string') {
+            throw new errors_1.InvalidChangesetDataError(`change at index ${index} is missing required string field "${field}"`, { index, field });
+        }
+    }
+    if (typeof record['success'] !== 'boolean') {
+        throw new errors_1.InvalidChangesetDataError(`change at index ${index} is missing required boolean field "success"`, { index });
+    }
+    // Optional fields: resourceId, before, after — presence is acceptable, type checked if present.
+    if (record['resourceId'] !== undefined &&
+        typeof record['resourceId'] !== 'string') {
+        throw new errors_1.InvalidChangesetDataError(`change at index ${index} has non-string "resourceId"`, { index });
+    }
+    for (const optField of ['before', 'after']) {
+        const val = record[optField];
+        if (val !== undefined &&
+            (typeof val !== 'object' || val === null || Array.isArray(val))) {
+            throw new errors_1.InvalidChangesetDataError(`change at index ${index} has invalid "${optField}" (must be a plain object or absent)`, { index, field: optField });
+        }
+    }
+    return item;
+}
+class ChangesetRecorderImpl {
+    forConversation(conversationId) {
+        return new changeset_1.ConversationChangesetImpl(conversationId);
+    }
+    fromJSON(data) {
+        if (typeof data !== 'object' ||
+            data === null ||
+            typeof data.conversationId !== 'string' ||
+            !Array.isArray(data.changes)) {
+            throw new errors_1.InvalidChangesetDataError('top-level shape must have string "conversationId" and array "changes"');
+        }
+        const changes = data.changes.map((item, index) => validateChangeRecord(item, index));
+        return new changeset_1.ConversationChangesetImpl(data.conversationId, changes);
+    }
+}
+/**
+ * Creates a `ChangesetRecorder` — the entry point for this package.
+ *
+ * ```typescript
+ * import { createChangesetRecorder } from '@bernierllc/agent-changeset';
+ *
+ * const recorder = createChangesetRecorder();
+ * const changeset = recorder.forConversation('conv-abc123');
+ * ```
+ */
+function createChangesetRecorder() {
+    return new ChangesetRecorderImpl();
+}
+//# sourceMappingURL=recorder.js.map

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;AAoHF,0DAEC;AApHD,qCAAqD;AACrD,2CAAwD;AAQxD;;;GAGG;AACH,SAAS,oBAAoB,CAAC,IAAa,EAAE,KAAa;IACxD,IACE,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EACnB,CAAC;QACD,MAAM,IAAI,kCAAyB,CACjC,mBAAmB,KAAK,mBAAmB,EAC3C,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAA+B,CAAC;IAE/C,MAAM,eAAe,GAA8B;QACjD,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,SAAS;QACT,WAAW;QACX,YAAY;KACb,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,kCAAyB,CACjC,mBAAmB,KAAK,sCAAsC,KAAK,GAAG,EACtE,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,IAAI,kCAAyB,CACjC,mBAAmB,KAAK,8CAA8C,EACtE,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;IAED,gGAAgG;IAChG,IACE,MAAM,CAAC,YAAY,CAAC,KAAK,SAAS;QAClC,OAAO,MAAM,CAAC,YAAY,CAAC,KAAK,QAAQ,EACxC,CAAC;QACD,MAAM,IAAI,kCAAyB,CACjC,mBAAmB,KAAK,8BAA8B,EACtD,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,QAAQ,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAU,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7B,IACE,GAAG,KAAK,SAAS;YACjB,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAC/D,CAAC;YACD,MAAM,IAAI,kCAAyB,CACjC,mBAAmB,KAAK,iBAAiB,QAAQ,sCAAsC,EACvF,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAC3B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,IAAoB,CAAC;AAC9B,CAAC;AAED,MAAM,qBAAqB;IACzB,eAAe,CAAC,cAAsB;QACpC,OAAO,IAAI,qCAAyB,CAAC,cAAc,CAAC,CAAC;IACvD,CAAC;IAED,QAAQ,CAAC,IAAyB;QAChC,IACE,OAAO,IAAI,KAAK,QAAQ;YACxB,IAAI,KAAK,IAAI;YACb,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ;YACvC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAC5B,CAAC;YACD,MAAM,IAAI,kCAAyB,CACjC,uEAAuE,CACxE,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAmB,IAAI,CAAC,OAAO,CAAC,GAAG,CAC9C,CAAC,IAAa,EAAE,KAAa,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,EAAE,KAAK,CAAC,CACpE,CAAC;QAEF,OAAO,IAAI,qCAAyB,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,SAAgB,uBAAuB;IACrC,OAAO,IAAI,qBAAqB,EAAE,CAAC;AACrC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * A single mutation recorded during a conversation turn.
+ */
+export interface ChangeRecord {
+    /** UUID generated at record time. */
+    id: string;
+    /** Dot-notation action label, e.g. `admin.service.add`. */
+    action: string;
+    /** Domain noun the mutation affects, e.g. `service`, `booking`. */
+    resourceType: string;
+    /** Optional identifier of the specific resource. */
+    resourceId?: string;
+    /** State of the resource before the mutation. Omit for creates. */
+    before?: Record<string, unknown>;
+    /** State of the resource after the mutation. Omit for deletes. */
+    after?: Record<string, unknown>;
+    /** Human-readable one-sentence description of the change. */
+    summary: string;
+    /** ISO 8601 timestamp generated at record time. */
+    timestamp: string;
+    /** Correlates this record to the tool call that produced it. */
+    toolCallId: string;
+    /** Whether the tool call succeeded. */
+    success: boolean;
+}
+/**
+ * Field-level diff between `before` and `after` states of a `ChangeRecord`.
+ */
+export interface ChangesetDiff {
+    /** Keys present in `after` but absent in `before`. */
+    added: string[];
+    /** Keys present in `before` but absent in `after`. */
+    removed: string[];
+    /** Keys present in both states whose values differ. */
+    modified: Array<{
+        field: string;
+        from: unknown;
+        to: unknown;
+    }>;
+}
+/**
+ * End-of-conversation rollup: totals and per-resource-type groupings.
+ */
+export interface RollupSummary {
+    totalChanges: number;
+    successfulChanges: number;
+    failedChanges: number;
+    /** Grouped by `resourceType` — each entry has a count and per-change lines. */
+    byResourceType: Record<string, {
+        count: number;
+        lines: string[];
+    }>;
+    /** Plain text suitable for injection into an LLM system prompt. */
+    plainText: string;
+    /** Markdown suitable for rendering in a `<ChangeSummaryCard>` UI component. */
+    markdown: string;
+}
+/**
+ * Serializable snapshot for persistence alongside conversation messages.
+ */
+export interface SerializedChangeset {
+    conversationId: string;
+    changes: ChangeRecord[];
+}
+/**
+ * Input accepted by `ConversationChangeset.record()`.
+ * Identical to `ChangeRecord` minus the auto-generated `id` and `timestamp`.
+ */
+export type RecordInput = Omit<ChangeRecord, 'id' | 'timestamp'>;
+/**
+ * Accumulates mutation records for a single conversation and renders
+ * per-change summaries and end-of-conversation rollups.
+ */
+export interface ConversationChangeset {
+    readonly conversationId: string;
+    readonly changes: ReadonlyArray<ChangeRecord>;
+    /** Record a single mutation; auto-generates `id` and `timestamp`. */
+    record(entry: RecordInput): ChangeRecord;
+    /**
+     * Returns a compact one-liner for the given changeId.
+     * Prefix is `+` for success, `-` for failure.
+     * @throws {ChangeNotFoundError} if `changeId` is unknown.
+     */
+    renderLineSummary(changeId: string): string;
+    /**
+     * Computes a field-level diff for a change that has both `before` and `after`.
+     * Returns `null` when either is absent (create-only or delete-only mutations).
+     * @throws {ChangeNotFoundError} if `changeId` is unknown.
+     */
+    computeDiff(changeId: string): ChangesetDiff | null;
+    /**
+     * Produces an end-of-conversation rollup grouped by `resourceType`.
+     * Includes both `plainText` (for LLM context injection) and `markdown` (for UI).
+     */
+    renderRollupSummary(): RollupSummary;
+    /** Serializes the changeset to plain JSON for persistence. */
+    toJSON(): SerializedChangeset;
+}
+/**
+ * Factory that creates and restores `ConversationChangeset` instances.
+ */
+export interface ChangesetRecorder {
+    /** Create a fresh changeset scoped to the given conversation. */
+    forConversation(conversationId: string): ConversationChangeset;
+    /**
+     * Restore a changeset from serialized JSON (e.g. loaded from storage).
+     * @throws {InvalidChangesetDataError} if the data is malformed.
+     */
+    fromJSON(data: SerializedChangeset): ConversationChangeset;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sDAAsD;IACtD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uDAAuD;IACvD,QAAQ,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACnE,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAE9C,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAAC;IAEzC;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IAEpD;;;OAGG;IACH,mBAAmB,IAAI,aAAa,CAAC;IAErC,8DAA8D;IAC9D,MAAM,IAAI,mBAAmB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,qBAAqB,CAAC;IAC/D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAAC;CAC5D"}

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;EAME"}

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "@bernierllc/agent-changeset",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @bernierllc/agent-changeset",
+  "version": "0.2.0",
+  "description": "Records agent-tool mutations per conversation and renders per-change summaries and end-of-conversation rollups",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "ai",
+    "agent",
+    "changeset",
+    "audit",
+    "diff",
+    "bernierllc"
+  ],
+  "author": "Bernier LLC",
+  "license": "Bernier LLC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bernierllc/tools.git",
+    "directory": "packages/core/agent-changeset"
+  },
+  "dependencies": {
+    "@bernierllc/logger": "1.7.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.19",
+    "eslint": "^8.0.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "test:run": "jest"
+  }
+}