@particle-academy/prism-harness 0.1.0 → 0.2.0

package/README.md

@@ -71,6 +71,50 @@ and writing the new messages as one operation. Two turns landing concurrently
 would otherwise both read position 4 and both write position 5, silently losing
 a message — the race the reference tracks as prism-harness#2.
 
+## Attachments
+
+A turn can carry media alongside its prompt:
+
+```ts
+import { Image } from '@particle-academy/prism';
+
+await runtime.send(session, 'What is wrong with this layout?', undefined, undefined, [
+  Image.fromBase64(screenshot, 'image/png'),
+]);
+```
+
+Pass `prism-ts` media objects or media already serialized. Attachments are stored
+with the turn in the shape `UserMessage.fromObject()` rebuilds. Each one must be
+an image, document, audio or video that carries its bytes, a provider file id or
+document chunks. The same rules as the PHP reference and the Python port apply,
+pinned across all three by prism-parity's `harness-turn-attachments` corpus.
+
+**Refused, with a `HarnessError` whose `code` names the problem:**
+
+| Code | When |
+|---|---|
+| `attachment_by_reference` | built from a URL or read from a file |
+| `attachment_not_media` | anything other than those four media types |
+| `attachment_empty` | no bytes, no file id and no chunks |
+| `attachment_without_prompt` | attachments with an empty prompt |
+
+A refusal happens before a run starts: no run, no events, nothing in the thread.
+
+## Provider options per mode
+
+A mode can declare `provider_options`. They reach your model client unchanged,
+as `request.providerOptions`, on every step of every run in that mode. Pass them
+to your provider call (with `prism-ts`, `withProviderOptions()`):
+
+```ts
+new ModeRegistry({
+  modes: { overseer: { system_prompt: '...', provider_options: { thinking: { enabled: true } } } },
+});
+```
+
+A value that is not a map is refused when the mode is resolved, with
+`mode_malformed`.
+
 ## Agent task lists
 
 An agent given a goal has to keep working across many requests. It needs a list

package/dist/attachments.d.ts

@@ -0,0 +1,23 @@
+import type { JsonObject } from './json.js';
+/**
+ * Something a caller can attach to a turn.
+ *
+ * Either a `prism-ts` media object (anything with `toObject()`), or media
+ * already in its serialized form. This package has no dependency on `prism-ts`,
+ * so it asks the object the questions it needs rather than checking its class.
+ */
+export type Attachment = JsonObject | MediaLike;
+export interface MediaLike {
+    toObject(): JsonObject;
+    isUrl?(): boolean;
+    isFile?(): boolean;
+}
+/**
+ * Which media a turn will carry, decided before a run starts.
+ *
+ * The same rules and the same four codes as the PHP reference and the Python
+ * port, pinned across all three by prism-parity's `harness-turn-attachments`
+ * corpus. Returns the attachments serialized, in the form `prism-ts`'s
+ * `UserMessage.fromObject` rebuilds.
+ */
+export declare function admitAttachments(prompt: string, attachments: readonly unknown[]): JsonObject[];

package/dist/attachments.js

@@ -0,0 +1,73 @@
+import { HarnessError } from './errors.js';
+import { isJsonObject } from './json.js';
+const MEDIA_KINDS = new Set(['image', 'audio', 'video', 'document']);
+function isMediaLike(value) {
+    return typeof value === 'object' && value !== null && typeof value.toObject === 'function';
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+/**
+ * Bytes, decoded the way PHP's base64_decode() and Python's lenient decoder read
+ * them. A string that decodes to nothing (whitespace, or no base64 characters at
+ * all) carries nothing, however long it is.
+ */
+function carriesBytes(value) {
+    return typeof value === 'string' && Buffer.from(value, 'base64').length > 0;
+}
+/**
+ * Which media a turn will carry, decided before a run starts.
+ *
+ * The same rules and the same four codes as the PHP reference and the Python
+ * port, pinned across all three by prism-parity's `harness-turn-attachments`
+ * corpus. Returns the attachments serialized, in the form `prism-ts`'s
+ * `UserMessage.fromObject` rebuilds.
+ */
+export function admitAttachments(prompt, attachments) {
+    if (attachments.length === 0) {
+        return [];
+    }
+    if (prompt === '') {
+        throw HarnessError.attachmentWithoutPrompt();
+    }
+    return attachments.map((attachment, index) => {
+        let serialized;
+        if (isMediaLike(attachment)) {
+            // Asked of the OBJECT first. A prism-ts media built from a local path
+            // serializes as bytes with no path, so the serialized form alone could not
+            // tell that it came from a file.
+            if (attachment.isUrl?.() === true) {
+                throw HarnessError.attachmentByReference(index, 'a URL');
+            }
+            if (attachment.isFile?.() === true) {
+                throw HarnessError.attachmentByReference(index, 'a file path');
+            }
+            serialized = attachment.toObject();
+        }
+        else if (isJsonObject(attachment)) {
+            serialized = attachment;
+        }
+        else {
+            throw HarnessError.attachmentNotMedia(index, attachment === null ? 'null' : `a ${typeof attachment}`);
+        }
+        if (typeof serialized.kind !== 'string' || !MEDIA_KINDS.has(serialized.kind)) {
+            throw HarnessError.attachmentNotMedia(index, 'an object with no image, document, audio or video kind');
+        }
+        // ANY string, including the empty one. The reference's isUrl() asks whether a
+        // URL was set at all, and `fromUrl('')` is still media built from a URL.
+        if (typeof serialized.url === 'string') {
+            throw HarnessError.attachmentByReference(index, 'a URL');
+        }
+        if (typeof serialized.local_path === 'string' || typeof serialized.storage_path === 'string') {
+            throw HarnessError.attachmentByReference(index, 'a file path');
+        }
+        const chunks = serialized.chunks;
+        const carries = carriesBytes(serialized.base64) ||
+            nonEmptyString(serialized.file_id) ||
+            (serialized.kind === 'document' && Array.isArray(chunks) && chunks.length > 0);
+        if (!carries) {
+            throw HarnessError.attachmentEmpty(index);
+        }
+        return serialized;
+    });
+}

package/dist/errors.d.ts

@@ -60,7 +60,15 @@ export type HarnessErrorCode =
  * NOT in the set the Python port settled, and raised rather than dropped --
  * see `taskOutcomeInvalid` for why coercing instead is a security defect.
  */
- | 'task_outcome_invalid';
+ | 'task_outcome_invalid'
+/** A turn attachment was built from a URL or a path. */
+ | 'attachment_by_reference'
+/** A turn attachment is not an image, document, audio or video. */
+ | 'attachment_not_media'
+/** A turn attachment carries no bytes, no file id and no chunks. */
+ | 'attachment_empty'
+/** Attachments were offered with an empty prompt, which sends no user message. */
+ | 'attachment_without_prompt';
 export interface HarnessErrorOptions {
     cause?: unknown;
 }
@@ -196,4 +204,16 @@ export declare class HarnessError extends Error {
      */
     static completionToolWithoutAuthorizer(name: string): HarnessError;
     static noAgentRuntime(action: string): HarnessError;
+    /**
+     * A turn attachment built from a URL or a path.
+     *
+     * A URL from request input is somebody else's choice of address, and a path's
+     * contents would go to a third-party model. The same four attachment codes are
+     * raised by the PHP reference and the Python port.
+     */
+    static attachmentByReference(index: number, what: string): HarnessError;
+    static attachmentNotMedia(index: number, type: string): HarnessError;
+    static attachmentEmpty(index: number): HarnessError;
+    /** An empty prompt resumes a paused run and sends no user message, so attachments would vanish. */
+    static attachmentWithoutPrompt(): HarnessError;
 }

package/dist/errors.js

@@ -198,4 +198,26 @@ export class HarnessError extends Error {
     static noAgentRuntime(action) {
         return new HarnessError('no_agent_runtime', `This session cannot ${action}: it was built without an agent runtime.`);
     }
+    /**
+     * A turn attachment built from a URL or a path.
+     *
+     * A URL from request input is somebody else's choice of address, and a path's
+     * contents would go to a third-party model. The same four attachment codes are
+     * raised by the PHP reference and the Python port.
+     */
+    static attachmentByReference(index, what) {
+        return new HarnessError('attachment_by_reference', `Attachment [${index}] was built from ${what}. A turn sends media as its bytes or as a provider file id, ` +
+            'never as a URL or path for someone else to resolve. Read the content yourself and attach the bytes.');
+    }
+    static attachmentNotMedia(index, type) {
+        return new HarnessError('attachment_not_media', `Attachment [${index}] is ${type}, not an image, document, audio or video. A turn's text belongs in the prompt.`);
+    }
+    static attachmentEmpty(index) {
+        return new HarnessError('attachment_empty', `Attachment [${index}] carries nothing to send: no bytes, no file id and no chunks.`);
+    }
+    /** An empty prompt resumes a paused run and sends no user message, so attachments would vanish. */
+    static attachmentWithoutPrompt() {
+        return new HarnessError('attachment_without_prompt', 'Attachments need a prompt to travel with. An empty prompt resumes a paused run and sends no user ' +
+            'message, so these attachments would be dropped without a word.');
+    }
 }

package/dist/index.d.ts

@@ -34,3 +34,5 @@ export type { CompletionToolOptions } from './task-tools.js';
 export { SkillRegistry } from './skills.js';
 export { SubagentRunner } from './subagent-runner.js';
 export type { SubagentOutcome, SubagentResult } from './subagent-runner.js';
+export { admitAttachments } from './attachments.js';
+export type { Attachment, MediaLike } from './attachments.js';

package/dist/index.js

@@ -18,3 +18,4 @@ export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';
 export { agentCompletionTool } from './task-tools.js';
 export { SkillRegistry } from './skills.js';
 export { SubagentRunner } from './subagent-runner.js';
+export { admitAttachments } from './attachments.js';

package/dist/modes.d.ts

@@ -1,3 +1,4 @@
+import type { JsonObject } from './json.js';
 import type { Subagent } from './subagents.js';
 export interface ModeConfig {
     system_prompt?: string;
@@ -6,6 +7,8 @@ export interface ModeConfig {
     max_steps?: number;
     subagents?: Record<string, unknown>;
     requires_approval?: readonly string[];
+    /** Passed unchanged to the model client on every run in this mode. Must be a map. */
+    provider_options?: Record<string, unknown>;
 }
 export interface ModeRegistryConfig {
     default?: string;
@@ -28,11 +31,15 @@ export declare class AgentMode {
     readonly subagents: Readonly<Record<string, Subagent>>;
     /** Tools that must not run until a human says so. */
     readonly requiresApproval: readonly string[];
+    /** Options handed to the provider on every run in this mode, unchanged. */
+    readonly providerOptions: Readonly<JsonObject>;
     constructor(name: string, systemPrompt: string, tools: readonly string[], skills: readonly string[], maxSteps: number, 
     /** Nested agents this mode may call, by name. */
     subagents?: Readonly<Record<string, Subagent>>, 
     /** Tools that must not run until a human says so. */
-    requiresApproval?: readonly string[]);
+    requiresApproval?: readonly string[], 
+    /** Options handed to the provider on every run in this mode, unchanged. */
+    providerOptions?: Readonly<JsonObject>);
     /**
      * Whether a named tool needs a human before it runs IN THIS MODE.
      *

package/dist/modes.js

@@ -1,4 +1,5 @@
 import { HarnessError } from './errors.js';
+import { isJsonObject } from './json.js';
 import { subagentFromConfig } from './subagents.js';
 /**
  * What a mode lets a run do.
@@ -15,11 +16,14 @@ export class AgentMode {
     maxSteps;
     subagents;
     requiresApproval;
+    providerOptions;
     constructor(name, systemPrompt, tools, skills, maxSteps, 
     /** Nested agents this mode may call, by name. */
     subagents = {}, 
     /** Tools that must not run until a human says so. */
-    requiresApproval = []) {
+    requiresApproval = [], 
+    /** Options handed to the provider on every run in this mode, unchanged. */
+    providerOptions = {}) {
         this.name = name;
         this.systemPrompt = systemPrompt;
         this.tools = tools;
@@ -27,6 +31,7 @@ export class AgentMode {
         this.maxSteps = maxSteps;
         this.subagents = subagents;
         this.requiresApproval = requiresApproval;
+        this.providerOptions = providerOptions;
     }
     /**
      * Whether a named tool needs a human before it runs IN THIS MODE.
@@ -75,7 +80,7 @@ export class ModeRegistry {
         if (typeof prompt !== 'string' || !Number.isInteger(maxSteps) || maxSteps < 1) {
             throw HarnessError.modeMalformed(wanted, 'system_prompt must be a string and max_steps a positive integer');
         }
-        return new AgentMode(wanted, prompt, strings(mode.tools), strings(mode.skills), maxSteps, this.#subagentsFor(wanted, mode), strings(mode.requires_approval));
+        return new AgentMode(wanted, prompt, strings(mode.tools), strings(mode.skills), maxSteps, this.#subagentsFor(wanted, mode), strings(mode.requires_approval), providerOptionsFor(wanted, mode.provider_options));
     }
     /**
      * The nested agents a mode may call.
@@ -107,3 +112,18 @@ export class ModeRegistry {
 function strings(value) {
     return (value ?? []).filter((entry) => typeof entry === 'string');
 }
+/**
+ * A mode's provider options, refused rather than ignored when they are not a map.
+ *
+ * A list or a scalar would reach the provider as nothing, and the mode would run
+ * without the option its author believes is on.
+ */
+function providerOptionsFor(name, declared) {
+    if (declared === undefined) {
+        return {};
+    }
+    if (!isJsonObject(declared)) {
+        throw HarnessError.modeMalformed(name, 'provider_options must be a map of option names to values');
+    }
+    return declared;
+}

package/dist/runtime.d.ts

@@ -22,6 +22,12 @@ export interface LlmRequest {
     tools: readonly HarnessTool[];
     provider: string;
     model: string;
+    /**
+     * The mode's `provider_options`, unchanged. A client passes them to its
+     * provider call (for prism-ts, `withProviderOptions()`); the harness does not
+     * interpret them.
+     */
+    providerOptions: Readonly<JsonObject>;
 }
 export interface LlmToolCall {
     id: string;
@@ -90,7 +96,7 @@ export declare class AgentRuntime {
      * the decision, and everything before them. A new prompt there would be a
      * second instruction competing with the one the tool call came from.
      */
-    send(session: Session, prompt: string, toolNames?: readonly string[], context?: RunContext): Promise<AgentResponse>;
+    send(session: Session, prompt: string, toolNames?: readonly string[], context?: RunContext, additionalContent?: readonly unknown[]): Promise<AgentResponse>;
 }
 /**
  * Answer a pending approval, durably.

package/dist/runtime.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { admitAttachments } from './attachments.js';
 import { HarnessError } from './errors.js';
 import { RunBudget, RunContext } from './subagents.js';
 /**
@@ -40,7 +41,10 @@ export class AgentRuntime {
      * the decision, and everything before them. A new prompt there would be a
      * second instruction competing with the one the tool call came from.
      */
-    async send(session, prompt, toolNames, context) {
+    async send(session, prompt, toolNames, context, additionalContent = []) {
+        // Refused before a run exists: a bad attachment is a mistake in the call,
+        // and it should not cost a run, events or budget.
+        const attachments = admitAttachments(prompt, additionalContent);
         const mode = this.#modes.resolve(await session.mode());
         const provider = (await session.provider()) ?? 'unknown';
         const model = (await session.model()) ?? 'unknown';
@@ -64,7 +68,13 @@ export class AgentRuntime {
             at: new Date().toISOString(),
         });
         if (prompt !== '') {
-            await thread.record([{ type: 'user', content: prompt }], runId);
+            // With attachments, the shape prism-ts's UserMessage.toObject() writes: the
+            // media parts, then the turn's own text as a trailing text part, which
+            // fromObject() strips back off. Without them, unchanged.
+            const turn = attachments.length === 0
+                ? { type: 'user', content: prompt }
+                : { type: 'user', content: prompt, additional_content: [...attachments, { text: prompt }], additional_attributes: {} };
+            await thread.record([turn], runId);
         }
         try {
             return await this.#loop(session, mode, run, runId, provider, model, toolNames);
@@ -105,6 +115,7 @@ export class AgentRuntime {
                 tools: offered,
                 provider,
                 model,
+                providerOptions: mode.providerOptions,
             });
             run.ledger.recordSteps(1);
             run.ledger.recordCost(response.costUsd ?? null);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.1.0",
-  "description": "Durable agent sessions for TypeScript \u2014 threads, session state and store drivers.",
+  "version": "0.2.0",
+  "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,
   "engines": {