@substrat-run/engine-assistant 0.0.0-stage → 0.1.28

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @substrat-run/engine-assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The record of a chat between a person and an assistant, for [Substrat](https://github.com/substrat-run/substrat).
+An append-only event log, a single-writer run lease, and tool calls whose gated writes need an
+approval bound to the exact input.
+
+Configured for **public npm publication**; the first npm release is pending. Nothing composes
+it yet; it is the first part of the assistant described in [#2283](https://github.com/substrat-run/substrat/issues/2283).
+
+## How a host uses it
+
+The engine is composed **by call** and never talks to a model. A host runs the loop and calls
+the in-scope functions inside its own transaction, as a principal holding the right key:
+
+```ts
+import { assistantModule, sendMessage, acquireRun, appendEvents, claimExecution, resolveApproval } from '@substrat-run/engine-assistant';
+
+host.registerModule(assistantModule);
+
+// A person (assistant:use) says something, which begins a turn.
+sendMessage(ctx, { threadId, text });
+
+// The host (assistant:run) takes the lease and appends what the assistant did.
+acquireRun(ctx, { threadId, runId });
+await appendEvents(ctx, { threadId, runId, events: [{ t: 'text-start', pid: 'p1' }, /* … */] });
+
+// A change waits for approval. The request carries what it binds and their digest, with the
+// thread's owner as the approver:
+//   digest = await approvalDigest({ version, approver: threadOwner, thread: threadId, step,
+//                                   call: callId, operation, expiresAt, nonce, input })
+//   { t: 'approval-request', callId, step, tool, operation, version, input, expiresAt, nonce, digest, preview }
+// The person approves with the digest they were shown (assistant:use, as the owner), on a
+// route the loop cannot call; `version` is the deployed version the HOST serves the answer under.
+await resolveApproval(ctx, { threadId, callId, digest, approved: true, version });
+
+// Before running the operation, the host claims its one execution with what it is about to run.
+await claimExecution(ctx, { threadId, runId, callId, operation, version, input });
+```
+
+`approvalDigest` and the event vocabulary (`assistantStreamBody`) are in
+`@substrat-run/contracts/assistant-stream`.
+
+**After every answer, the host runs.** An `approval-resolved`, approval or denial, resumes the
+turn rather than ending it, so the owner gets `turn_in_progress` until a run writes
+`turn-finish` or `turn-error`. A host therefore takes the lease after every answer, a denial
+included, and ends the turn (`turn-finish: done` after a denial, or `turn-error` if it cannot
+go on). If a turn is abandoned, because the host never came back, a later run takes the lease
+once the holder is stale and closes it the same way. The owner has no way to end a turn
+without a run; closing the thread is their only way out.
+
+## Two keys
+
+`assistant:use` is a person's: open and read their own threads, say something, approve or deny.
+`assistant:run` is for a **system principal only** (the assistant host's), never a role a person
+holds: it writes the assistant's side of the record. The manifest declares it `holder: 'system'`,
+and `pnpm lint:permissions` refuses a role or entity grant shape that grants it. `assistant:audit`
+reads other principals' threads and never writes, and only together with `assistant:use`, which
+every read checks first.
+
+## Files for imports and comparisons
+
+The host-facing entry point `@substrat-run/engine-assistant/files` accepts `.csv`, `.tsv`
+and `.xlsx` uploads, up to 10 MiB each. A message can reference up to five files from its
+own thread. Text is optional when files are present; existing text-only calls are unchanged.
+Older `.xls` workbooks must first be saved as `.xlsx`.
+
+```ts
+import { assistantFiles } from '@substrat-run/engine-assistant/files';
+import { readSpreadsheet } from '@substrat-run/attachment-extractors';
+
+// HOST code: both handles MUST address the same scope. `person` is an authenticated
+// person's ScopeStub; `storage` is the assistant host's ScopeAttachments, holding
+// assistant:run through its system role. Never hand that storage handle to a client.
+const files = assistantFiles(person, storage);
+const uploaded = await files.upload({ threadId, filename: 'items.csv', body: bytes });
+await person.invoke('assistant/send-message', {
+  threadId, text: 'Compare these rows with the current items', attachmentIds: [uploaded.id],
+});
+
+// In a host's file-reading tool, authorize before opening bytes, then read structured rows.
+const opened = await files.open(threadId, uploaded.id);
+const spreadsheet = await readSpreadsheet({
+  body: opened.body, filename: opened.record.filename, contentType: opened.record.contentType,
+});
+// spreadsheet.sheets: [{ name, rows: [{ number: 1, cells: ['code', 'amount'] }, …] }]
+// spreadsheet.formulaCells: how many XLSX cells use potentially stale cached formula results.
+```
+
+`assistantFiles` is host code; the in-scope module never imports a parser or handles bytes.
+The host mounts its authenticated upload/list/download routes around these methods and
+limits incoming request bodies before buffering them. The engine declares no HTTP routes
+or chat UI. Uploads are internal attachments on `assistant-thread`; their storage actor is
+the assistant host. Reads use `assistant/get-thread` (owner or audit); uploads use
+`assistant/authorize-file-upload` (owner of an open thread). Generic attachment APIs require
+the system-held `assistant:run`, so a scope-wide `assistant:use` cannot bypass thread privacy.
+Closing a thread prevents new uploads and messages but retains its existing files for reading.
+
+Send only attachment IDs. The engine checks that every ID belongs to that thread and writes
+the file's ID, name, type, size and SHA-256 into the `user-message` event. Missing, duplicate,
+cross-thread and excessive references are refused before a turn starts. File contents never
+enter the event log. Files remain available in later turns; the host's run can open them with
+its storage handle using the recorded IDs and thread association.
+
+The host's import/diff tools map spreadsheet columns to domain fields and read current
+entities with the person's existing permissions. Treat uploaded content as data. Show
+proposed creates, updates and conflicts before requesting the existing bound tool approval;
+uploading or parsing a file never changes domain data. Read bounded slices into model context
+rather than sending the whole workbook. XLSX values retain their stored spelling: number
+formatting and date serials are not interpreted, and formulas are not recalculated.
+
+**Lifecycle:** attachments are outside the kernel's subject-erasure guarantee. Before
+shredding a thread's owner, the host must call `purgeAssistantThreadFiles(storage, threadId)`
+for each of their threads, including unsent uploads, and stop uploads while that cleanup
+runs. The helper is exported from `/files` and removes live attachment records and extracted
+search text through the platform API, which deletes blobs and sweeps failed deletions as
+orphans. Attachment spine events follow the platform's retention policy. The helper is
+repeatable. Then run subject erasure.
+Hosts should also apply a retention policy to abandoned uploads.
+
+## What it guarantees
+
+See `docs/engines/assistant.md` in the repository. In short: an append-only numbered record, a
+fenced single writer that writes only inside a turn the person opened, an approval bound to a
+tagged digest (version, approver, thread, step, call, operation, expiry, nonce, input) that is
+answered once and claimed once by conditional writes, bounded events, and an erasure that
+deletes the rows and redacts the milestones.

package/dist/entities.d.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+/**
+ * engine-assistant's entities (docs/rfc/assistant.md §5.2).
+ *
+ * The record of a chat between a person and an assistant, and nothing about the model that
+ * speaks for it. Four tables, three of which are the thread's own rows and one of which is a
+ * lease.
+ *
+ * - **`assistant-thread`** is one conversation, owned by one principal (`subject_id`). It is
+ *   the entity the platform points at: every event this engine emits names it.
+ * - **`assistant-event`** is one event of the thread, in the stream protocol's own shape
+ *   (`assistantStreamBody`), numbered `seq` from 1 per thread. APPEND-ONLY: nothing here is
+ *   updated or deleted by the engine. `seq` is the cursor a client resumes after. `body` is
+ *   the event serialised, without its `seq`, and is where the person's words live.
+ * - **`assistant-run`** is the single-writer lease: which run may append the assistant's
+ *   events to a thread right now, and when it last beat. Not an entity of the person's, but
+ *   it carries `subject_id` so an erasure leaves no row naming a thread that is gone.
+ * - **`assistant-tool-call`** is the state a tool call passes through, which is where the
+ *   engine's central invariant lives: a gated write runs only from `approved`, once, with the
+ *   input whose digest the user saw.
+ *
+ * Erasure (K-46). Everything that holds what the person said or what the assistant did for
+ * them is theirs whole, so each table names `subject_id` as its subject column and erases by
+ * `delete`. The rows have no `id` of their own to survive an erasure with, and nothing about
+ * a thread is meaningful once its owner is gone. The events this engine EMITS carry no text,
+ * no tool input or output and no digest of one, and every one is `pseudonymous` with the
+ * thread's subject as its `subjectId`, so the same erasure redacts their payloads too.
+ */
+export declare const assistantEntities: {
+    readonly 'assistant-thread': {
+        readonly table: "assistant_threads";
+        readonly fields: z.ZodObject<{
+            id: z.ZodString;
+            subject_id: z.ZodString;
+            title: z.ZodNullable<z.ZodString>;
+            status: z.ZodEnum<{
+                closed: "closed";
+                open: "open";
+            }>;
+            created_at: z.ZodString;
+            last_event_at: z.ZodString;
+            closed_at: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        readonly erasable: readonly ["title"];
+        readonly erasure: {
+            readonly subjects: readonly ["subject_id"];
+            readonly mode: "delete";
+        };
+    };
+    readonly 'assistant-event': {
+        readonly table: "assistant_events";
+        readonly fields: z.ZodObject<{
+            thread_id: z.ZodString;
+            seq: z.ZodNumber;
+            type: z.ZodString;
+            body: z.ZodString;
+            subject_id: z.ZodString;
+            created_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["thread_id", "seq"];
+        readonly erasable: readonly ["body"];
+        readonly erasure: {
+            readonly subjects: readonly ["subject_id"];
+            readonly mode: "delete";
+        };
+    };
+    readonly 'assistant-run': {
+        readonly table: "assistant_runs";
+        readonly fields: z.ZodObject<{
+            thread_id: z.ZodString;
+            run_id: z.ZodString;
+            subject_id: z.ZodString;
+            beat_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["thread_id"];
+        readonly erasable: readonly ["subject_id"];
+        readonly erasure: {
+            readonly subjects: readonly ["subject_id"];
+            readonly mode: "delete";
+        };
+    };
+    readonly 'assistant-tool-call': {
+        readonly table: "assistant_tool_calls";
+        readonly fields: z.ZodObject<{
+            thread_id: z.ZodString;
+            call_id: z.ZodString;
+            tool: z.ZodString;
+            state: z.ZodEnum<{
+                approved: "approved";
+                "awaiting-approval": "awaiting-approval";
+                denied: "denied";
+                done: "done";
+                executing: "executing";
+                failed: "failed";
+                running: "running";
+            }>;
+            digest: z.ZodNullable<z.ZodString>;
+            step: z.ZodNullable<z.ZodString>;
+            operation: z.ZodNullable<z.ZodString>;
+            version: z.ZodNullable<z.ZodString>;
+            expires_at: z.ZodNullable<z.ZodString>;
+            nonce: z.ZodNullable<z.ZodString>;
+            request_seq: z.ZodNullable<z.ZodNumber>;
+            decided_by: z.ZodNullable<z.ZodString>;
+            decided_at: z.ZodNullable<z.ZodString>;
+            subject_id: z.ZodString;
+            created_at: z.ZodString;
+            updated_at: z.ZodString;
+        }, z.core.$strip>;
+        readonly primaryKey: readonly ["thread_id", "call_id"];
+        readonly erasable: readonly ["subject_id", "decided_by"];
+        readonly erasure: {
+            readonly subjects: readonly ["subject_id"];
+            readonly mode: "delete";
+        };
+    };
+};
+/** One thread, as stored. */
+export declare const threadRow: z.ZodObject<{
+    id: z.ZodString;
+    subject_id: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        closed: "closed";
+        open: "open";
+    }>;
+    created_at: z.ZodString;
+    last_event_at: z.ZodString;
+    closed_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** One event of a thread, as stored. */
+export declare const eventRow: z.ZodObject<{
+    thread_id: z.ZodString;
+    seq: z.ZodNumber;
+    type: z.ZodString;
+    body: z.ZodString;
+    subject_id: z.ZodString;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+/** The lease on a thread, as stored. */
+export declare const runRow: z.ZodObject<{
+    thread_id: z.ZodString;
+    run_id: z.ZodString;
+    subject_id: z.ZodString;
+    beat_at: z.ZodString;
+}, z.core.$strip>;
+/** One tool call's state, as stored. */
+export declare const toolCallRow: z.ZodObject<{
+    thread_id: z.ZodString;
+    call_id: z.ZodString;
+    tool: z.ZodString;
+    state: z.ZodEnum<{
+        approved: "approved";
+        "awaiting-approval": "awaiting-approval";
+        denied: "denied";
+        done: "done";
+        executing: "executing";
+        failed: "failed";
+        running: "running";
+    }>;
+    digest: z.ZodNullable<z.ZodString>;
+    step: z.ZodNullable<z.ZodString>;
+    operation: z.ZodNullable<z.ZodString>;
+    version: z.ZodNullable<z.ZodString>;
+    expires_at: z.ZodNullable<z.ZodString>;
+    nonce: z.ZodNullable<z.ZodString>;
+    request_seq: z.ZodNullable<z.ZodNumber>;
+    decided_by: z.ZodNullable<z.ZodString>;
+    decided_at: z.ZodNullable<z.ZodString>;
+    subject_id: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuE5B,CAAC;AAEH,6BAA6B;AAC7B,eAAO,MAAM,SAAS;;;;;;;;;;;iBAA+C,CAAC;AACtE,wCAAwC;AACxC,eAAO,MAAM,QAAQ;;;;;;;iBAA8C,CAAC;AACpE,wCAAwC;AACxC,eAAO,MAAM,MAAM;;;;;iBAA4C,CAAC;AAChE,wCAAwC;AACxC,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;iBAAkD,CAAC"}

package/dist/entities.js

@@ -0,0 +1,110 @@
+import { defineEntities } from '@substrat-run/contracts';
+import { z } from 'zod';
+/**
+ * engine-assistant's entities (docs/rfc/assistant.md §5.2).
+ *
+ * The record of a chat between a person and an assistant, and nothing about the model that
+ * speaks for it. Four tables, three of which are the thread's own rows and one of which is a
+ * lease.
+ *
+ * - **`assistant-thread`** is one conversation, owned by one principal (`subject_id`). It is
+ *   the entity the platform points at: every event this engine emits names it.
+ * - **`assistant-event`** is one event of the thread, in the stream protocol's own shape
+ *   (`assistantStreamBody`), numbered `seq` from 1 per thread. APPEND-ONLY: nothing here is
+ *   updated or deleted by the engine. `seq` is the cursor a client resumes after. `body` is
+ *   the event serialised, without its `seq`, and is where the person's words live.
+ * - **`assistant-run`** is the single-writer lease: which run may append the assistant's
+ *   events to a thread right now, and when it last beat. Not an entity of the person's, but
+ *   it carries `subject_id` so an erasure leaves no row naming a thread that is gone.
+ * - **`assistant-tool-call`** is the state a tool call passes through, which is where the
+ *   engine's central invariant lives: a gated write runs only from `approved`, once, with the
+ *   input whose digest the user saw.
+ *
+ * Erasure (K-46). Everything that holds what the person said or what the assistant did for
+ * them is theirs whole, so each table names `subject_id` as its subject column and erases by
+ * `delete`. The rows have no `id` of their own to survive an erasure with, and nothing about
+ * a thread is meaningful once its owner is gone. The events this engine EMITS carry no text,
+ * no tool input or output and no digest of one, and every one is `pseudonymous` with the
+ * thread's subject as its `subjectId`, so the same erasure redacts their payloads too.
+ */
+export const assistantEntities = defineEntities({
+    'assistant-thread': {
+        table: 'assistant_threads',
+        fields: z.object({
+            id: z.string(),
+            subject_id: z.string(),
+            title: z.string().nullable(),
+            status: z.enum(['open', 'closed']),
+            created_at: z.string(),
+            last_event_at: z.string(),
+            closed_at: z.string().nullable(),
+        }),
+        erasable: ['title'],
+        erasure: { subjects: ['subject_id'], mode: 'delete' },
+    },
+    'assistant-event': {
+        table: 'assistant_events',
+        fields: z.object({
+            thread_id: z.string(),
+            seq: z.number(),
+            type: z.string(),
+            body: z.string(),
+            subject_id: z.string(),
+            created_at: z.string(),
+        }),
+        primaryKey: ['thread_id', 'seq'],
+        erasable: ['body'],
+        erasure: { subjects: ['subject_id'], mode: 'delete' },
+    },
+    'assistant-run': {
+        table: 'assistant_runs',
+        fields: z.object({
+            thread_id: z.string(),
+            run_id: z.string(),
+            subject_id: z.string(),
+            beat_at: z.string(),
+        }),
+        primaryKey: ['thread_id'],
+        // Holds no words, but the principal's id says whose thread this lease was on.
+        erasable: ['subject_id'],
+        erasure: { subjects: ['subject_id'], mode: 'delete' },
+    },
+    'assistant-tool-call': {
+        table: 'assistant_tool_calls',
+        fields: z.object({
+            thread_id: z.string(),
+            call_id: z.string(),
+            tool: z.string(),
+            state: z.enum(['running', 'awaiting-approval', 'approved', 'denied', 'executing', 'done', 'failed']),
+            digest: z.string().nullable(),
+            // What the approval request bound (`approvalDigest`), kept so an answer and a claim can
+            // recompute the digest rather than trust one. Set together with `digest`, or all null.
+            // The input itself is not copied here: `request_seq` points at the request event.
+            step: z.string().nullable(),
+            operation: z.string().nullable(),
+            version: z.string().nullable(),
+            expires_at: z.string().nullable(),
+            nonce: z.string().nullable(),
+            request_seq: z.number().nullable(),
+            decided_by: z.string().nullable(),
+            decided_at: z.string().nullable(),
+            subject_id: z.string(),
+            created_at: z.string(),
+            updated_at: z.string(),
+        }),
+        primaryKey: ['thread_id', 'call_id'],
+        // The tool name and the digest are not the person's, but who the call was for, and who
+        // decided it, are.
+        erasable: ['subject_id', 'decided_by'],
+        erasure: { subjects: ['subject_id'], mode: 'delete' },
+    },
+});
+/** One thread, as stored. */
+export const threadRow = assistantEntities['assistant-thread'].fields;
+/** One event of a thread, as stored. */
+export const eventRow = assistantEntities['assistant-event'].fields;
+/** The lease on a thread, as stored. */
+export const runRow = assistantEntities['assistant-run'].fields;
+/** One tool call's state, as stored. */
+export const toolCallRow = assistantEntities['assistant-tool-call'].fields;
+//# sourceMappingURL=entities.js.map

package/dist/entities.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,106 @@
+/**
+ * engine-assistant's event contract (#696) — what a VERTICAL imports so that consuming this
+ * engine by event is checked rather than guessed.
+ *
+ * Milestones only. The thread's own record is `assistant_events`; these are what the rest of
+ * the platform learns about it. A text delta is not a platform event: forty of them make one
+ * answer, and an outbox row each would be the record written twice.
+ *
+ * **No text and no tool data ride an event.** A message, a tool input and a tool output are
+ * the person's data. So a payload names the thread, the call and the tool, and nothing else:
+ * not the approval's `preview` wording, which can restate what the person asked for, and not
+ * its digest either — a SHA-256 of a small input is recovered by guessing the input, so it
+ * is the input. Nor does a payload name the person: who a thread belongs to is the
+ * envelope's `subjectId`.
+ *
+ * **Every milestone is `pseudonymous`, keyed to the thread's subject** (`emitAssistantEvent`
+ * makes that the only way to emit one). A thread id names one person's conversation, so the
+ * outbox rows that carry it are that person's; with a `subjectId`, an erasure (K-46) redacts
+ * their payloads along with the thread's own rows.
+ *
+ * VERTICAL-FACING ONLY. A sibling engine consuming one of these must NOT import it (R1,
+ * star topology).
+ *
+ * Additive, like every other engine surface: a new event type may appear, an existing
+ * payload field does not change shape without a `schemaVersion` bump.
+ */
+import { type DomainEventInput } from '@substrat-run/contracts';
+import type { OperationContext } from '@substrat-run/kernel';
+/** A thread was opened. Whose it is, is the envelope's `subjectId`. */
+export interface AssistantThreadCreatedPayload {
+    threadId: string;
+}
+/** The user said something and a turn began. */
+export interface AssistantTurnStartedPayload {
+    threadId: string;
+}
+/** A run came to rest on a turn: done, waiting for an approval, stopped, or out of budget. */
+export interface AssistantTurnFinishedPayload {
+    threadId: string;
+    reason: 'done' | 'awaiting-approval' | 'stopped' | 'budget';
+}
+/**
+ * A gated tool call is waiting for the user. The digest it is bound to stays in the record
+ * (`assistant_events`), never here: it is a hash of the person's input.
+ */
+export interface AssistantApprovalRequestedPayload {
+    threadId: string;
+    callId: string;
+    tool: string;
+}
+/** The user approved or denied a gated tool call. */
+export interface AssistantApprovalResolvedPayload {
+    threadId: string;
+    callId: string;
+    tool: string;
+    approved: boolean;
+}
+/** The thread was closed; nothing more is appended. */
+export interface AssistantThreadClosedPayload {
+    threadId: string;
+}
+/**
+ * engine-assistant's event contract — the six event types this engine emits and the payload
+ * each one carries. Satisfies the kernel's `EventContract`.
+ */
+export type AssistantEvents = {
+    events: {
+        'assistant.thread-created': AssistantThreadCreatedPayload;
+        'assistant.turn-started': AssistantTurnStartedPayload;
+        'assistant.turn-finished': AssistantTurnFinishedPayload;
+        'assistant.approval-requested': AssistantApprovalRequestedPayload;
+        'assistant.approval-resolved': AssistantApprovalResolvedPayload;
+        'assistant.thread-closed': AssistantThreadClosedPayload;
+    };
+};
+/** Every event type this engine emits. */
+export type AssistantEventType = keyof AssistantEvents['events'];
+/**
+ * Every event type this engine emits, and the `schemaVersion` each is emitted at — the ONE
+ * home for that number (#1597). `emitAssistantEvent` stamps it and the manifest's `emits` is
+ * derived from it, so the two cannot drift. Bumping a version is K-39's REPLACE.
+ */
+export declare const assistantEventVersions: {
+    readonly 'assistant.thread-created': 1;
+    readonly 'assistant.turn-started': 1;
+    readonly 'assistant.turn-finished': 1;
+    readonly 'assistant.approval-requested': 1;
+    readonly 'assistant.approval-resolved': 1;
+    readonly 'assistant.thread-closed': 1;
+};
+/** The manifest's `events.emits`, read off {@link assistantEventVersions} — never hand-declared. */
+export declare const assistantEmitDeclarations: {
+    type: string;
+    schemaVersion: number;
+}[];
+/**
+ * `ctx.emit`, with the event type and its payload welded together, so the map above is the
+ * source rather than a description nothing holds in agreement. It stamps `schemaVersion`, and
+ * makes every milestone `pseudonymous` under `subject` — the thread's owner — so an erasure
+ * of that person reaches it; there is no way to emit one as `none`.
+ */
+export declare function emitAssistantEvent<K extends AssistantEventType>(ctx: OperationContext, subject: string, event: Omit<DomainEventInput, 'type' | 'payload' | 'schemaVersion' | 'piiClass' | 'subjectId'> & {
+    type: K;
+    payload: AssistantEvents['events'][K];
+}): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,uEAAuE;AACvE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC7D;AAED;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qDAAqD;AACrD,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE;QACN,0BAA0B,EAAE,6BAA6B,CAAC;QAC1D,wBAAwB,EAAE,2BAA2B,CAAC;QACtD,yBAAyB,EAAE,4BAA4B,CAAC;QACxD,8BAA8B,EAAE,iCAAiC,CAAC;QAClE,6BAA6B,EAAE,gCAAgC,CAAC;QAChE,yBAAyB,EAAE,4BAA4B,CAAC;KACzD,CAAC;CACH,CAAC;AAEF,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;yCACL,CAAC;uCACH,CAAC;wCACA,CAAC;6CACI,CAAC;4CACF,CAAC;wCACL,CAAC;CACyB,CAAC;AAExD,oGAAoG;AACpG,eAAO,MAAM,yBAAyB,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAEpB,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,kBAAkB,EAC7D,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC,GAAG;IAC/F,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CACvC,GACA,IAAI,CAON"}

package/dist/events.js

@@ -0,0 +1,57 @@
+/**
+ * engine-assistant's event contract (#696) — what a VERTICAL imports so that consuming this
+ * engine by event is checked rather than guessed.
+ *
+ * Milestones only. The thread's own record is `assistant_events`; these are what the rest of
+ * the platform learns about it. A text delta is not a platform event: forty of them make one
+ * answer, and an outbox row each would be the record written twice.
+ *
+ * **No text and no tool data ride an event.** A message, a tool input and a tool output are
+ * the person's data. So a payload names the thread, the call and the tool, and nothing else:
+ * not the approval's `preview` wording, which can restate what the person asked for, and not
+ * its digest either — a SHA-256 of a small input is recovered by guessing the input, so it
+ * is the input. Nor does a payload name the person: who a thread belongs to is the
+ * envelope's `subjectId`.
+ *
+ * **Every milestone is `pseudonymous`, keyed to the thread's subject** (`emitAssistantEvent`
+ * makes that the only way to emit one). A thread id names one person's conversation, so the
+ * outbox rows that carry it are that person's; with a `subjectId`, an erasure (K-46) redacts
+ * their payloads along with the thread's own rows.
+ *
+ * VERTICAL-FACING ONLY. A sibling engine consuming one of these must NOT import it (R1,
+ * star topology).
+ *
+ * Additive, like every other engine surface: a new event type may appear, an existing
+ * payload field does not change shape without a `schemaVersion` bump.
+ */
+import { dataSubjectId } from '@substrat-run/contracts';
+/**
+ * Every event type this engine emits, and the `schemaVersion` each is emitted at — the ONE
+ * home for that number (#1597). `emitAssistantEvent` stamps it and the manifest's `emits` is
+ * derived from it, so the two cannot drift. Bumping a version is K-39's REPLACE.
+ */
+export const assistantEventVersions = {
+    'assistant.thread-created': 1,
+    'assistant.turn-started': 1,
+    'assistant.turn-finished': 1,
+    'assistant.approval-requested': 1,
+    'assistant.approval-resolved': 1,
+    'assistant.thread-closed': 1,
+};
+/** The manifest's `events.emits`, read off {@link assistantEventVersions} — never hand-declared. */
+export const assistantEmitDeclarations = Object.entries(assistantEventVersions).map(([type, schemaVersion]) => ({ type, schemaVersion }));
+/**
+ * `ctx.emit`, with the event type and its payload welded together, so the map above is the
+ * source rather than a description nothing holds in agreement. It stamps `schemaVersion`, and
+ * makes every milestone `pseudonymous` under `subject` — the thread's owner — so an erasure
+ * of that person reaches it; there is no way to emit one as `none`.
+ */
+export function emitAssistantEvent(ctx, subject, event) {
+    ctx.emit({
+        ...event,
+        schemaVersion: assistantEventVersions[event.type],
+        piiClass: 'pseudonymous',
+        subjectId: dataSubjectId.parse(subject),
+    });
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,aAAa,EAAyB,MAAM,yBAAyB,CAAC;AA4D/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,0BAA0B,EAAE,CAAC;IAC7B,wBAAwB,EAAE,CAAC;IAC3B,yBAAyB,EAAE,CAAC;IAC5B,8BAA8B,EAAE,CAAC;IACjC,6BAA6B,EAAE,CAAC;IAChC,yBAAyB,EAAE,CAAC;CACyB,CAAC;AAExD,oGAAoG;AACpG,MAAM,CAAC,MAAM,yBAAyB,GAA8C,MAAM,CAAC,OAAO,CAChG,sBAAsB,CACvB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAqB,EACrB,OAAe,EACf,KAGC;IAED,GAAG,CAAC,IAAI,CAAC;QACP,GAAG,KAAK;QACR,aAAa,EAAE,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC;QACjD,QAAQ,EAAE,cAAc;QACxB,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;KACxC,CAAC,CAAC;AACL,CAAC"}

package/dist/files.d.ts

@@ -0,0 +1,32 @@
+/**
+ * HOST code, separate from the in-scope engine. Bind `caller` to the authenticated
+ * person and `storage` to the assistant host's system principal, in the SAME scope.
+ * Never expose `storage` itself to a browser or model tool.
+ */
+import { type AttachmentRecord } from '@substrat-run/contracts';
+import type { OpenedAttachment, ScopeAttachments, ScopeStub } from '@substrat-run/kernel';
+export declare const ASSISTANT_FILE_MAX_BYTES: number;
+export interface AssistantFileUpload {
+    threadId: string;
+    filename: string;
+    body: Uint8Array;
+}
+/**
+ * A host mounts these methods on its own authenticated routes. Bytes bypass invoke;
+ * ownership and audit checks go through the engine's real operation handlers.
+ * There is intentionally no automatic import: the host's tools preview a diff and
+ * use the existing approval/claim flow before changing domain entities.
+ */
+export declare function assistantFiles(caller: ScopeStub, storage: ScopeAttachments): {
+    upload(input: AssistantFileUpload): Promise<AttachmentRecord>;
+    list: (threadId: string) => Promise<AttachmentRecord[]>;
+    open(threadId: string, attachmentId: string): Promise<OpenedAttachment>;
+};
+/**
+ * Trusted host lifecycle hook: remove blobs BEFORE erasing a thread's owner. The
+ * kernel's subject erasure deletes engine rows, but does not shred attachment blobs.
+ * Repeatable; failed blob deletions follow the platform's orphan-sweep policy.
+ * Do not expose as an unauthenticated route.
+ */
+export declare function purgeAssistantThreadFiles(storage: ScopeAttachments, threadId: string): Promise<void>;
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAqC,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAG1F,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAGzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;CAClB;AAYD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB;kBASnD,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;qBANvC,MAAM,KAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;mBAkB3C,MAAM,gBAAgB,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;EAShF;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI1G"}