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

package/dist/shapes.js

@@ -0,0 +1,134 @@
+/**
+ * The published shapes and the declared inputs of engine-assistant, in one place so the
+ * in-scope functions in `index.ts` and the declared operations in `operations.ts` read the
+ * same definition rather than two that drift.
+ *
+ * Published shapes are camelCase projections; the stored rows (snake_case) are in
+ * `entities.ts`. A caller never sees a row.
+ */
+import { z } from '@substrat-run/contracts';
+import { ASSISTANT_MESSAGE_FILES_MAX, assistantStreamBody, assistantStreamEvent } from '@substrat-run/contracts/assistant-stream';
+/**
+ * The longest an event body may serialise to, in UTF-8 bytes: the Durable Object row limit
+ * is in bytes. A large tool result belongs in the operation that produced it, by id.
+ */
+export const MAX_EVENT_BYTES = 64 * 1024;
+/**
+ * The longest a user's message may be, in UTF-8 bytes of its text AS SERIALISED (escapes
+ * included). Half the event bound, so a message that passes the input schema always fits in
+ * its `user-message` event: a message is refused as a message, at the boundary, never as an
+ * oversized event further in.
+ */
+export const MAX_MESSAGE_BYTES = 32 * 1024;
+/** UTF-8 byte length of a string, without a platform encoder (module code has none in its types). */
+export function utf8Length(s) {
+    let bytes = 0;
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        bytes += cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+const threadId = z.string().min(1).max(64);
+const runId = z.string().min(1).max(64);
+const callId = z.string().min(1).max(64);
+const deployedVersion = z.string().min(1).max(128);
+/** One thread, projected. */
+export const thread = z.object({
+    id: z.string(),
+    /** The principal the thread belongs to. */
+    subject: z.string(),
+    title: z.string().nullable(),
+    status: z.enum(['open', 'closed']),
+    createdAt: z.string(),
+    lastEventAt: z.string(),
+    closedAt: z.string().nullable(),
+});
+export const createThreadInput = z.object({ title: z.string().max(200).optional() });
+export const listThreadsInput = z.object({
+    /** Another principal's threads: needs `assistant:audit`. Unset means the caller's own. */
+    subject: z.string().min(1).optional(),
+    status: z.enum(['open', 'closed']).optional(),
+});
+export const threadIdInput = z.object({ threadId });
+/** A bounded read of the record, by the cursor a client resumes after. */
+export const readEventsInput = z.object({
+    threadId,
+    /** Events strictly after this `seq`. 0 reads from the start. */
+    after: z.number().int().nonnegative().default(0),
+    limit: z.number().int().min(1).max(1000).default(500),
+});
+export const eventsPage = z.object({
+    events: z.array(assistantStreamEvent),
+    /** The `seq` of the last event returned, or `after` when there were none. */
+    lastSeq: z.number().int().nonnegative(),
+});
+export const sendMessageInput = z.object({
+    threadId,
+    // 32 000 characters is the stream protocol's own bound on `user-message`; the byte bound is
+    // the engine's, and is what a message in a wide script meets first.
+    text: z
+        .string()
+        .max(32_000)
+        .superRefine((text, ctx) => {
+        const bytes = utf8Length(JSON.stringify(text));
+        if (bytes > MAX_MESSAGE_BYTES) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `the message is ${bytes} bytes; a message may be at most ${MAX_MESSAGE_BYTES} bytes — send it in shorter parts`,
+            });
+        }
+    })
+        .default(''),
+    /** IDs of files already uploaded to THIS thread. Metadata is resolved by the engine. */
+    attachmentIds: z.array(z.string().min(1).max(64)).min(1).max(ASSISTANT_MESSAGE_FILES_MAX).optional(),
+}).superRefine((input, ctx) => {
+    if (!input.text.length && !input.attachmentIds?.length) {
+        ctx.addIssue({ code: 'custom', message: 'send text or at least one file' });
+    }
+    if (input.attachmentIds && new Set(input.attachmentIds).size !== input.attachmentIds.length) {
+        ctx.addIssue({ code: 'custom', path: ['attachmentIds'], message: 'a file may appear only once in a message' });
+    }
+});
+export const sentMessage = z.object({ firstSeq: z.number().int().positive(), lastSeq: z.number().int().positive() });
+export const resolveApprovalInput = z.object({
+    threadId,
+    callId,
+    /** The digest the user was shown: the request's `digest`. */
+    digest: z.string().regex(/^[0-9a-f]{64}$/),
+    approved: z.boolean(),
+    /**
+     * The deployed version the answer arrives under, as the HOST knows it (never the client):
+     * an approval given under another version than the request was made under is refused.
+     */
+    version: deployedVersion,
+});
+export const resolvedApproval = z.object({ seq: z.number().int().positive() });
+export const acquireRunInput = z.object({
+    threadId,
+    runId,
+    /** A holder that has not beaten for this long may be replaced. Default 15 s. */
+    staleMs: z.number().int().min(500).max(600_000).optional(),
+});
+export const acquiredRun = z.object({ tookOver: z.boolean() });
+export const releaseRunInput = z.object({ threadId, runId });
+export const releasedRun = z.object({ released: z.boolean() });
+export const appendEventsInput = z.object({
+    threadId,
+    runId,
+    events: z.array(assistantStreamBody).min(1).max(200),
+});
+export const appendedEvents = z.object({ events: z.array(assistantStreamEvent) });
+export const claimExecutionInput = z.object({
+    threadId,
+    runId,
+    callId,
+    /** The operation the host is about to run: it must be the one the user approved. */
+    operation: z.string().min(1).max(128),
+    /** The deployed version the host runs it under: it must be the one the request was made under. */
+    version: deployedVersion,
+    /** The input the host is about to execute: it must hash to what the user approved. */
+    input: z.unknown(),
+});
+export const claimedExecution = z.object({ claimed: z.literal(true) });
+//# sourceMappingURL=shapes.js.map

package/dist/shapes.js.map

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

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@substrat-run/engine-assistant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.27",
+  "description": "Substrat engine: the assistant's record — chat threads as an append-only event log, a single-writer run lease, and tool calls whose gated writes need an approval bound to the exact input",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/substrat-run/substrat.git",
+    "directory": "engines/assistant"
+  },
+  "homepage": "https://substrat.net/engines",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./files": {
+      "types": "./dist/files.d.ts",
+      "default": "./dist/files.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@substrat-run/contracts": "^0.175.0",
+    "@substrat-run/kernel": "^0.175.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.0",
+    "vitest": "^5.0.5",
+    "zod": "^4.4.3",
+    "@substrat-run/engine-test-kit": "^0.3.102",
+    "@substrat-run/contract-tests": "^0.175.0",
+    "@substrat-run/model-emit": "0.11.5"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.0"
+  },
+  "substrat": {
+    "conformance": "test/conformance.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run"
+  }
 }