@modelprofile.com/flexharness 12.3.0 → 12.5.0

package/dist_ts_compaction/smartagent.compaction.d.ts

@@ -26,6 +26,12 @@ export interface ICompactMessagesOptions {
      * cost more than the history saves. A context compactor passes its options' `tools` through.
      */
     tools?: plugins.ToolSet;
+    /**
+     * Reads the attachments the history names by a URL of one of its schemes, so the summary call
+     * sends them as the turns do. A context compactor passes its options' `attachmentResolver`
+     * through.
+     */
+    attachmentResolver?: plugins.IAgentAttachmentResolver;
 }
 /**
  * Compacts a message history into a summary.

package/dist_ts_compaction/smartagent.compaction.js

@@ -90,6 +90,8 @@ export async function compactMessages(model, messages, options = {}) {
             },
         })
         : model;
+    // The summary's attempts read each attachment once.
+    const download = plugins.createAttachmentDownload(options.attachmentResolver, options.abortSignal);
     // The summary is asked for in the shape of a turn, the tools offered as the turns offer them. A
     // model that calls a tool instead of answering is asked again with tool use turned off, which
     // keeps the tool definitions and so still the cached tools and instructions.
@@ -104,6 +106,7 @@ export async function compactMessages(model, messages, options = {}) {
                 ...(tools ? { tools, ...(toolChoice ? { toolChoice } : {}) } : {}),
                 ...(options.providerOptions ? { providerOptions: options.providerOptions } : {}),
                 abortSignal: options.abortSignal,
+                ...(download ? { experimental_download: download } : {}),
                 onError: ({ error }) => {
                     streamError ??= error;
                 },
@@ -147,4 +150,4 @@ function summaryMessages(summary) {
         },
     ];
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5jb21wYWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfY29tcGFjdGlvbi9zbWFydGFnZW50LmNvbXBhY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsTUFBTSxpQkFBaUIsR0FBRzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7SUFvQnRCLENBQUM7QUFFTCw0RkFBNEY7QUFDNUYsTUFBTSx1QkFBdUIsR0FBRywyRUFBMkUsQ0FBQztBQUU1Ryw2RUFBNkU7QUFDN0UsTUFBTSxhQUFhLEdBQUcseURBQXlELENBQUM7QUErQmhGOzs7OztHQUtHO0FBQ0gsS0FBSyxVQUFVLHFCQUFxQixDQUFDLEtBQXNCLEVBQUUsUUFBZ0M7SUFDM0YsSUFBSSxTQUFTLEdBQUcsQ0FBQyxDQUFDO0lBQ2xCLEtBQUssTUFBTSxDQUFDLElBQUksRUFBRSxVQUFVLENBQUMsSUFBSSxNQUFNLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUM7UUFDdkQsTUFBTSxNQUFNLEdBQUcsVUFBVSxDQUFDLElBQUksS0FBSyxVQUFVLENBQUMsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLE1BQU0sT0FBTyxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQUMsV0FBVyxDQUFDLENBQUMsVUFBVSxDQUFDO1FBQzVILFNBQVMsSUFBSSxJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsQ0FBQyxVQUFVLENBQUMsV0FBVyxJQUFJLEVBQUUsRUFBRSxNQUFNLElBQUksSUFBSSxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDbkcsQ0FBQztJQUNELE9BQU8sU0FBUyxJQUFJLENBQUMsR0FBRyxJQUFJLENBQUMsU0FBUyxDQUFDLFFBQVEsQ0FBQyxDQUFDLE1BQU0sQ0FBQztBQUMxRCxDQUFDO0FBRUQsNkZBQTZGO0FBQzdGLFNB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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5jb21wYWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfY29tcGFjdGlvbi9zbWFydGFnZW50LmNvbXBhY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsTUFBTSxpQkFBaUIsR0FBRzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7SUFvQnRCLENBQUM7QUFFTCw0RkFBNEY7QUFDNUYsTUFBTSx1QkFBdUIsR0FBRywyRUFBMkUsQ0FBQztBQUU1Ryw2RUFBNkU7QUFDN0UsTUFBTSxhQUFhLEdBQUcseURBQXlELENBQUM7QUFxQ2hGOzs7OztHQUtHO0FBQ0gsS0FBSyxVQUFVLHFCQUFxQixDQUFDLEtBQXNCLEVBQUUsUUFBZ0M7SUFDM0YsSUFBSSxTQUFTLEdBQUcsQ0FBQyxDQUFDO0lBQ2xCLEtBQUssTUFBTSxDQUFDLElBQUksRUFBRSxVQUFVLENBQUMsSUFBSSxNQUFNLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUM7UUFDdkQsTUFBTSxNQUFNLEdBQUcsVUFBVSxDQUFDLElBQUksS0FBSyxVQUFVLENBQUMsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLE1BQU0sT0FBTyxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQUMsV0FBVyxDQUFDLENBQUMsVUFBVSxDQUFDO1FBQzVILFNBQVMsSUFBSSxJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsQ0FBQyxVQUFVLENBQUMsV0FBVyxJQUFJLEVBQUUsRUFBRSxNQUFNLElBQUksSUFBSSxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDbkcsQ0FBQztJQUNELE9BQU8sU0FBUyxJQUFJLENBQUMsR0FBRyxJQUFJLENBQUMsU0FBUyxDQUFDLFFBQVEsQ0FBQyxDQUFDLE1BQU0sQ0FBQztBQUMxRCxDQUFDO0FBRUQsNkZBQTZGO0FBQzdGLFNB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

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "12.3.0",
+  "version": "12.5.0",
   "type": "module",
   "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
   "main": "./dist_ts/index.js",
@@ -91,8 +91,8 @@
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@modelprofile.com/flexharness-agent": "12.3.0",
-    "@modelprofile.com/flexharness-models": "12.3.0",
+    "@modelprofile.com/flexharness-agent": "12.5.0",
+    "@modelprofile.com/flexharness-models": "12.5.0",
     "@push.rocks/smartrequest": "^5.5.1",
     "ai": "^7.0.111",
     "zod": "^4.6.5"

package/readme.md

@@ -578,10 +578,32 @@ console.log(result.usage);
 `TFlexPrompt` is deliberately JSON-safe. It accepts a string or an ordered array of:
 
 - `{ type: 'text', text }`
-- `{ type: 'image', data, mediaType?, name? }`
-- `{ type: 'file', data, mediaType, name? }`
+- `{ type: 'image', data, mediaType?, name?, sizeBytes? }`
+- `{ type: 'file', data, mediaType, name?, sizeBytes? }`
 
-Attachment `data` is a string containing base64, a data URL, or a remote URL. Public input never requires `Buffer` or `URL` objects. Remote URL strings are converted only at the private AgentSession invocation boundary.
+Attachment `data` is a string containing base64, a data URL, a remote URL, or a reference. Public input never requires `Buffer` or `URL` objects. Remote URL strings are converted only at the private AgentSession invocation boundary.
+
+A reference is a URL of a scheme the harness's `attachmentResolver` reads, for files the host keeps itself, such as uploads too large to travel inline:
+
+```typescript
+const harness = new FlexHarness({
+  // ...
+  attachmentResolver: {
+    schemes: ['exampleattachment'],
+    async resolve({ scopeId, scope, storageKey, sessionId, url, abortSignal }) {
+      const upload = await uploads.read(storageKey, sessionId, url.pathname, abortSignal);
+      return { data: upload.bytes, mediaType: upload.mediaType };
+    },
+  },
+});
+
+await harness.prompt(scopeId, sessionId, [
+  { type: 'text', text: 'Book this receipt.' },
+  { type: 'file', data: 'exampleattachment:3f2a', mediaType: 'application/pdf', name: 'receipt.pdf', sizeBytes: 48231 },
+]);
+```
+
+The history keeps the reference, never the bytes. Each model call that sends it, the turns' and a compaction's summary call alike, asks the resolver for the bytes and sends them to the provider; the steps of one turn ask once per reference. The resolver receives the scope and session the reference is sent in, so it reads only that conversation's files, and a reference it cannot read fails the turn. Schemes are lowercase, without the colon, and cannot be `data`, `file`, `http` or `https`; the harness refuses a malformed resolver with `FlexHarnessValidationError` when it is made. `sizeBytes`, which a reference states because the harness cannot count its bytes, is accepted on references only; a URL of a scheme the resolver does not name is no reference and is sent as before.
 
 Attachment payloads are never copied into public audit messages or events. Public attachment parts contain metadata only:
 
@@ -590,7 +612,7 @@ Attachment payloads are never copied into public audit messages or events. Publi
   type: 'attachment',
   partId: '...',
   attachmentType: 'file',
-  source: 'inline-base64', // or data-url / remote-url
+  source: 'inline-base64', // or data-url / remote-url / reference
   sizeBytes: 48231,        // omitted when it cannot be determined
   mediaType: 'application/pdf',
   name: 'invoice.pdf',
@@ -1038,7 +1060,7 @@ A `contextCompactor` states which model to compact with from the model the compa
 
 A compactor uses `resolvedModel.model` directly, and resolves `modelHint` the way its model resolver resolves a prompt's `modelHint`. Only when neither member is present, because nothing dispatched states a model, does the host choose the compaction model itself.
 
-A `context-overflow` or `context-budget` compaction also carries `system` and `providerOptions`: the instructions and the provider options (cache options applied, so `store: false` on OpenAI) the run's turns are sent with. A `context-budget` compaction on a provider that caches the prefix also carries the turns' `tools`. `compactMessages()` sends its summary call with them as one streamed call, the shape of every turn, with the tools' definitions but none of their code, so a compactor that passes its options through repeats the run's prefix and reads it from the provider's prompt cache; definitions that outweigh the history nine times are left out. Without `system` it sends its own instructions.
+A `context-overflow` or `context-budget` compaction also carries `system` and `providerOptions`: the instructions and the provider options (cache options applied, so `store: false` on OpenAI) the run's turns are sent with. A `context-budget` compaction on a provider that caches the prefix also carries the turns' `tools`. `compactMessages()` sends its summary call with them as one streamed call, the shape of every turn, with the tools' definitions but none of their code, so a compactor that passes its options through repeats the run's prefix and reads it from the provider's prompt cache; definitions that outweigh the history nine times are left out. Without `system` it sends its own instructions. With an `attachmentResolver` on the harness, every compaction also carries `attachmentResolver`, bound to the session, so `compactMessages()` sends the history's referenced files as the turns do.
 
 ```typescript
 agentSessionPolicy: {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '12.3.0',
+  version: '12.5.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

package/ts/classes.flexharness.core.ts

@@ -55,6 +55,7 @@ import { hydrateAgentMessages } from './utils.prompt.js';
 import { createProjectionChange, freezeProjectionEntries } from './utils.projectionchange.js';
 import {
   normalizeAgentSessionPolicy,
+  normalizeAttachmentResolver,
   normalizeBuiltInTools,
   normalizeSlashCommands,
   normalizeToolCatalogOptions,
@@ -151,6 +152,9 @@ export class FlexHarnessCore<TScope> {
   public readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
   private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
   public readonly delegatedRunAdmissionProvider: IFlexHarnessOptions<TScope>['delegatedRunAdmissionProvider'];
+  private readonly attachmentResolver: IFlexHarnessOptions<TScope>['attachmentResolver'];
+  /** The URL protocols, colon included, of the attachment references prompts may carry. */
+  public readonly attachmentReferenceProtocols: ReadonlySet<string>;
   public readonly stores: IFlexHarnessStores;
   public readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
   public readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
@@ -206,6 +210,8 @@ export class FlexHarnessCore<TScope> {
     this.resourceToolProviderResolver = options.resourceToolProviderResolver;
     this.executionContextProvider = options.executionContextProvider;
     this.delegatedRunAdmissionProvider = options.delegatedRunAdmissionProvider;
+    this.attachmentReferenceProtocols = normalizeAttachmentResolver(options.attachmentResolver);
+    this.attachmentResolver = options.attachmentResolver;
     this.stores = requireHarnessStores(options.stores ?? new InMemoryFlexHarnessStores());
     this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
     this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
@@ -743,6 +749,21 @@ export class FlexHarnessCore<TScope> {
         sessionId,
         eventStore,
         executionContext: contextualExecutionContext,
+        ...(this.attachmentResolver
+          ? {
+              attachmentResolver: {
+                schemes: [...this.attachmentReferenceProtocols].map((protocol) => protocol.slice(0, -1)),
+                resolve: ({ url, abortSignal }) => this.attachmentResolver!.resolve({
+                  scopeId,
+                  scope,
+                  storageKey: state.storageKey,
+                  sessionId,
+                  url,
+                  ...(abortSignal ? { abortSignal } : {}),
+                }),
+              },
+            }
+          : {}),
         contextBuilder: ({ events }) => hydrateAgentMessages(
           (this.agentSessionPolicy.contextBuilder ?? ((options) => plugins.buildModelMessages(options.events)))({
             events: this.reversions.filterReversionContextEvents(stored, events),

package/ts/classes.flexharness.prompts.ts

@@ -73,7 +73,7 @@ export class FlexHarnessPromptQueue<TScope> {
     debounceMs?: number,
   ): number {
     return jsonBytes({
-      prompt: normalizeFlexPrompt(prompt),
+      prompt: normalizeFlexPrompt(prompt, this.core.attachmentReferenceProtocols),
       options: cloneSerializable(options),
       scheduleKey,
       debounceMs,
@@ -225,7 +225,7 @@ export class FlexHarnessPromptQueue<TScope> {
     validateIdentifier(steer.steerId, 'steerId');
     requireTransferIdentifier(steer.steerId, 'steerId');
     this.core.assertOpen();
-    const prompt = normalizeFlexPrompt(steer.prompt);
+    const prompt = normalizeFlexPrompt(steer.prompt, this.core.attachmentReferenceProtocols);
     const byteSize = this.promptAdmissionByteSize(steer.prompt, {});
     const { state } = await this.core.resolveState(scopeId);
     this.core.assertStateAcceptingWork(state);
@@ -323,7 +323,7 @@ export class FlexHarnessPromptQueue<TScope> {
     queued?: IQueuedPrompt;
   }> {
     this.core.assertOpen();
-    const normalizedPrompt = normalizeFlexPrompt(prompt);
+    const normalizedPrompt = normalizeFlexPrompt(prompt, this.core.attachmentReferenceProtocols);
     const normalizedOptions = cloneSerializable(options);
     const byteSize = this.promptAdmissionByteSize(prompt, options, scheduleKey, debounceMs);
     const releasePendingAdmission = this.reservePendingPromptAdmission(byteSize);

package/ts/classes.flexharness.runs.ts

@@ -706,7 +706,7 @@ export class FlexHarnessRuns<TScope> {
         partId: plugins.crypto.randomUUID(),
         type: 'attachment' as const,
         attachmentType: part.type,
-        ...describeAttachment(part),
+        ...describeAttachment(part, this.core.attachmentReferenceProtocols),
       };
     });
   }

package/ts/classes.flexharness.slashcommands.ts

@@ -345,7 +345,7 @@ export class FlexHarnessSlashCommands<TScope> {
         ? FLEX_SLASH_COMMAND_INITIALIZE_TEMPLATE
         : registration!.template!;
       const expanded = expandSlashCommandTemplate(template, parsed.rawArguments, parsed.arguments);
-      normalizeFlexPrompt(expanded);
+      normalizeFlexPrompt(expanded, this.core.attachmentReferenceProtocols);
       this.requireSlashCommandPromptAvailable(
         state,
         stored,

package/ts/classes.flexharness.subagents.ts

@@ -84,7 +84,7 @@ export class FlexHarnessSubagents<TScope> {
     validateUtf8String(taskId, 'taskId', maxSubagentTaskIdBytes, true);
     validateIdentifier(steer.steerId, 'steerId');
     requireTransferIdentifier(steer.steerId, 'steerId');
-    const prompt = normalizeFlexPrompt(steer.prompt);
+    const prompt = normalizeFlexPrompt(steer.prompt, this.core.attachmentReferenceProtocols);
     const byteSize = this.core.prompts.promptAdmissionByteSize(steer.prompt, {});
     this.core.assertStateAcceptingWork(parent.state);
     const child = parent.state.activeRuns.get(taskId);

package/ts/interfaces.ts

@@ -39,18 +39,27 @@ export interface IFlexTextPromptPart {
   text: string;
 }
 
+/**
+ * `data` is base64, a data URL, an `http(s)` URL, or a reference: a URL of a scheme the
+ * harness's `attachmentResolver` reads, such as `exampleattachment:3f2a`.
+ */
 export interface IFlexImagePromptPart {
   type: 'image';
   data: string;
   mediaType?: string;
   name?: string;
+  /** The attachment's size, for a reference only: the transcript shows it. */
+  sizeBytes?: number;
 }
 
+/** `data` takes the forms an image part's does. */
 export interface IFlexFilePromptPart {
   type: 'file';
   data: string;
   mediaType: string;
   name?: string;
+  /** The attachment's size, for a reference only: the transcript shows it. */
+  sizeBytes?: number;
 }
 
 export type TFlexPromptPart = IFlexTextPromptPart | IFlexImagePromptPart | IFlexFilePromptPart;
@@ -129,7 +138,7 @@ export type TFlexActivityStatus =
   | 'cancelled';
 export type TFlexMessageStatus = 'streaming' | 'completed' | 'failed' | 'cancelled';
 export type TFlexToolPartStatus = 'running' | 'completed' | 'failed' | 'cancelled';
-export type TFlexAttachmentSource = 'inline-base64' | 'data-url' | 'remote-url';
+export type TFlexAttachmentSource = 'inline-base64' | 'data-url' | 'remote-url' | 'reference';
 
 export interface IFlexTextMessagePart {
   partId: string;
@@ -1859,6 +1868,28 @@ export interface IFlexBuiltInToolsOptions {
   projectManagement?: IFlexProjectManagementBuiltInToolsOptions;
 }
 
+/** What an attachment resolver is asked for: the attachment `url` names, for one session. */
+export interface IFlexAttachmentRequest<TScope = unknown> extends IFlexAgentContextInvocation<TScope> {
+  readonly url: URL;
+  readonly abortSignal?: AbortSignal;
+}
+
+/**
+ * Reads the attachments that prompts name by a URL of the host's own scheme, such as
+ * `exampleattachment:3f2a`, instead of carrying their content. The transcript keeps the URL, and
+ * each model call that sends the attachment, compaction's included, reads its content here, so
+ * neither the session's stores nor its prompts hold the bytes.
+ */
+export interface IFlexAttachmentResolver<TScope = unknown> {
+  /** The URL schemes it reads, without the colon, in lowercase: `exampleattachment`. */
+  schemes: readonly string[];
+  /**
+   * Returns the attachment's content for the session asking. Check that the session may read it,
+   * and throw when it may not or the attachment is gone: the model call fails with the error.
+   */
+  resolve(request: IFlexAttachmentRequest<TScope>): Promise<plugins.IAgentResolvedAttachment>;
+}
+
 export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
@@ -1867,6 +1898,8 @@ export interface IFlexHarnessOptions<TScope> {
   resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
   executionContextProvider?: IFlexExecutionContextProvider<TScope>;
   delegatedRunAdmissionProvider?: IFlexDelegatedRunAdmissionProvider<TScope>;
+  /** Lets prompts name attachments by reference; see {@link IFlexAttachmentResolver}. */
+  attachmentResolver?: IFlexAttachmentResolver<TScope>;
   stores?: IFlexHarnessStores;
   agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
   toolOutputLimits?: IFlexJsonLimits;

package/ts/plugins.ts

@@ -96,6 +96,7 @@ import {
   AgentPendingInputQueue,
   applyAgentEventChange,
   assertAgentEventChange,
+  assertAttachmentResolver,
   AgentPendingInputRejectedError,
   AgentSession,
   AgentToolCallScheduler,
@@ -117,6 +118,7 @@ export {
   AgentPendingInputQueue,
   applyAgentEventChange,
   assertAgentEventChange,
+  assertAttachmentResolver,
   AgentPendingInputRejectedError,
   AgentSession,
   AgentToolCallScheduler,
@@ -134,6 +136,7 @@ export {
 };
 export type {
   IAgentAppliedInput,
+  IAgentResolvedAttachment,
   ISmartAiCacheDispatch,
   IAgentEventArchive,
   IAgentEventChange,

package/ts/readme.md

@@ -578,10 +578,32 @@ console.log(result.usage);
 `TFlexPrompt` is deliberately JSON-safe. It accepts a string or an ordered array of:
 
 - `{ type: 'text', text }`
-- `{ type: 'image', data, mediaType?, name? }`
-- `{ type: 'file', data, mediaType, name? }`
+- `{ type: 'image', data, mediaType?, name?, sizeBytes? }`
+- `{ type: 'file', data, mediaType, name?, sizeBytes? }`
 
-Attachment `data` is a string containing base64, a data URL, or a remote URL. Public input never requires `Buffer` or `URL` objects. Remote URL strings are converted only at the private AgentSession invocation boundary.
+Attachment `data` is a string containing base64, a data URL, a remote URL, or a reference. Public input never requires `Buffer` or `URL` objects. Remote URL strings are converted only at the private AgentSession invocation boundary.
+
+A reference is a URL of a scheme the harness's `attachmentResolver` reads, for files the host keeps itself, such as uploads too large to travel inline:
+
+```typescript
+const harness = new FlexHarness({
+  // ...
+  attachmentResolver: {
+    schemes: ['exampleattachment'],
+    async resolve({ scopeId, scope, storageKey, sessionId, url, abortSignal }) {
+      const upload = await uploads.read(storageKey, sessionId, url.pathname, abortSignal);
+      return { data: upload.bytes, mediaType: upload.mediaType };
+    },
+  },
+});
+
+await harness.prompt(scopeId, sessionId, [
+  { type: 'text', text: 'Book this receipt.' },
+  { type: 'file', data: 'exampleattachment:3f2a', mediaType: 'application/pdf', name: 'receipt.pdf', sizeBytes: 48231 },
+]);
+```
+
+The history keeps the reference, never the bytes. Each model call that sends it, the turns' and a compaction's summary call alike, asks the resolver for the bytes and sends them to the provider; the steps of one turn ask once per reference. The resolver receives the scope and session the reference is sent in, so it reads only that conversation's files, and a reference it cannot read fails the turn. Schemes are lowercase, without the colon, and cannot be `data`, `file`, `http` or `https`; the harness refuses a malformed resolver with `FlexHarnessValidationError` when it is made. `sizeBytes`, which a reference states because the harness cannot count its bytes, is accepted on references only; a URL of a scheme the resolver does not name is no reference and is sent as before.
 
 Attachment payloads are never copied into public audit messages or events. Public attachment parts contain metadata only:
 
@@ -590,7 +612,7 @@ Attachment payloads are never copied into public audit messages or events. Publi
   type: 'attachment',
   partId: '...',
   attachmentType: 'file',
-  source: 'inline-base64', // or data-url / remote-url
+  source: 'inline-base64', // or data-url / remote-url / reference
   sizeBytes: 48231,        // omitted when it cannot be determined
   mediaType: 'application/pdf',
   name: 'invoice.pdf',
@@ -1038,7 +1060,7 @@ A `contextCompactor` states which model to compact with from the model the compa
 
 A compactor uses `resolvedModel.model` directly, and resolves `modelHint` the way its model resolver resolves a prompt's `modelHint`. Only when neither member is present, because nothing dispatched states a model, does the host choose the compaction model itself.
 
-A `context-overflow` or `context-budget` compaction also carries `system` and `providerOptions`: the instructions and the provider options (cache options applied, so `store: false` on OpenAI) the run's turns are sent with. A `context-budget` compaction on a provider that caches the prefix also carries the turns' `tools`. `compactMessages()` sends its summary call with them as one streamed call, the shape of every turn, with the tools' definitions but none of their code, so a compactor that passes its options through repeats the run's prefix and reads it from the provider's prompt cache; definitions that outweigh the history nine times are left out. Without `system` it sends its own instructions.
+A `context-overflow` or `context-budget` compaction also carries `system` and `providerOptions`: the instructions and the provider options (cache options applied, so `store: false` on OpenAI) the run's turns are sent with. A `context-budget` compaction on a provider that caches the prefix also carries the turns' `tools`. `compactMessages()` sends its summary call with them as one streamed call, the shape of every turn, with the tools' definitions but none of their code, so a compactor that passes its options through repeats the run's prefix and reads it from the provider's prompt cache; definitions that outweigh the history nine times are left out. Without `system` it sends its own instructions. With an `attachmentResolver` on the harness, every compaction also carries `attachmentResolver`, bound to the session, so `compactMessages()` sends the history's referenced files as the turns do.
 
 ```typescript
 agentSessionPolicy: {

package/ts/utils.harnessoptions.ts

@@ -1,4 +1,5 @@
 import { FlexHarnessValidationError } from './errors.js';
+import * as plugins from './plugins.js';
 import {
   FLEX_CODE_MODE_DEFAULT_LIMITS,
   FLEX_CODE_MODE_MAXIMUM_LIMITS,
@@ -10,6 +11,7 @@ import {
 } from './interfaces.js';
 import type {
   IFlexAgentSessionPolicy,
+  IFlexAttachmentResolver,
   IFlexCallbackLimits,
   IFlexHarnessOptions,
   IFlexHarnessStores,
@@ -500,6 +502,19 @@ export function normalizeAgentSessionPolicy<TScope>(
   };
 }
 
+/** The URL protocols, colon included, of the references an attachment resolver reads. */
+export function normalizeAttachmentResolver<TScope>(
+  resolver: IFlexAttachmentResolver<TScope> | undefined,
+): ReadonlySet<string> {
+  if (resolver === undefined) return new Set();
+  try {
+    plugins.assertAttachmentResolver(resolver);
+  } catch (error) {
+    throw new FlexHarnessValidationError((error as Error).message, { cause: error });
+  }
+  return new Set(resolver.schemes.map((scheme) => `${scheme}:`));
+}
+
 export function requireHarnessStores(stores: IFlexHarnessStores): IFlexHarnessStores {
   const projectManagement = stores?.projectManagement;
   if (

package/ts/utils.json.ts

@@ -864,7 +864,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       if (!['image', 'file'].includes(String(part.attachmentType))) {
         throw new FlexHarnessStoreFormatError(`${partPath}.attachmentType is invalid.`);
       }
-      if (!['inline-base64', 'data-url', 'remote-url'].includes(String(part.source))) {
+      if (!['inline-base64', 'data-url', 'remote-url', 'reference'].includes(String(part.source))) {
         throw new FlexHarnessStoreFormatError(`${partPath}.source is invalid.`);
       }
       if (part.sizeBytes !== undefined) {

package/ts/utils.prompt.ts

@@ -52,7 +52,39 @@ function toAgentData(data: string): string | URL {
   return data;
 }
 
-function validatePart(value: unknown, index: number): TFlexPromptPart {
+/** Whether `data` is a reference: a URL of one of `referenceProtocols`. */
+export function isAttachmentReference(data: string, referenceProtocols: ReadonlySet<string>): boolean {
+  if (referenceProtocols.size === 0) return false;
+  try {
+    return referenceProtocols.has(new URL(data).protocol);
+  } catch {
+    return false;
+  }
+}
+
+function validateSizeBytes(
+  value: Record<string, unknown>,
+  data: string,
+  referenceProtocols: ReadonlySet<string>,
+  path: string,
+): number | undefined {
+  if (value.sizeBytes === undefined) return undefined;
+  if (!isAttachmentReference(data, referenceProtocols)) {
+    throw new FlexHarnessValidationError(
+      `${path}.sizeBytes is supported only for an attachment reference.`,
+    );
+  }
+  if (!Number.isSafeInteger(value.sizeBytes) || (value.sizeBytes as number) < 0) {
+    throw new FlexHarnessValidationError(`${path}.sizeBytes must be a non-negative integer.`);
+  }
+  return value.sizeBytes as number;
+}
+
+function validatePart(
+  value: unknown,
+  index: number,
+  referenceProtocols: ReadonlySet<string>,
+): TFlexPromptPart {
   const path = `prompt[${index}]`;
   if (!isPlainObject(value)) {
     throw new FlexHarnessValidationError(`${path} must be a plain object.`);
@@ -65,26 +97,30 @@ function validatePart(value: unknown, index: number): TFlexPromptPart {
     };
   }
   if (value.type === 'image') {
-    rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name'], path);
+    rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name', 'sizeBytes'], path);
     const part: IFlexImagePromptPart = {
       type: 'image',
       data: requireNonEmptyString(value.data, `${path}.data`),
     };
     const mediaType = validateOptionalString(value.mediaType, `${path}.mediaType`);
     const name = validateOptionalString(value.name, `${path}.name`);
+    const sizeBytes = validateSizeBytes(value, part.data, referenceProtocols, path);
     if (mediaType) part.mediaType = mediaType;
     if (name) part.name = name;
+    if (sizeBytes !== undefined) part.sizeBytes = sizeBytes;
     return part;
   }
   if (value.type === 'file') {
-    rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name'], path);
+    rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name', 'sizeBytes'], path);
     const part: IFlexFilePromptPart = {
       type: 'file',
       data: requireNonEmptyString(value.data, `${path}.data`),
       mediaType: requireNonEmptyString(value.mediaType, `${path}.mediaType`),
     };
     const name = validateOptionalString(value.name, `${path}.name`);
+    const sizeBytes = validateSizeBytes(value, part.data, referenceProtocols, path);
     if (name) part.name = name;
+    if (sizeBytes !== undefined) part.sizeBytes = sizeBytes;
     return part;
   }
   throw new FlexHarnessValidationError(`${path}.type must be text, image, or file.`);
@@ -122,7 +158,14 @@ function toStoredModelParts(parts: TFlexPromptPart[]): TFlexAgentPrompt {
   }) as TFlexAgentPrompt;
 }
 
-export function normalizeFlexPrompt(prompt: TFlexPrompt): INormalizedFlexPrompt {
+/**
+ * Validates a prompt. `referenceProtocols` are the URL protocols, colon included, of the
+ * attachment references the harness's attachment resolver reads.
+ */
+export function normalizeFlexPrompt(
+  prompt: TFlexPrompt,
+  referenceProtocols: ReadonlySet<string>,
+): INormalizedFlexPrompt {
   try {
     assertJsonSerializable(prompt, '$prompt');
   } catch (error) {
@@ -142,7 +185,7 @@ export function normalizeFlexPrompt(prompt: TFlexPrompt): INormalizedFlexPrompt
   if (!Array.isArray(prompt) || prompt.length === 0) {
     throw new FlexHarnessValidationError('prompt must be a string or a non-empty array of parts.');
   }
-  const parts = prompt.map(validatePart);
+  const parts = prompt.map((part, index) => validatePart(part, index, referenceProtocols));
   return {
     modelMessage: {
       role: 'user',

package/ts/utils.transfer.ts

@@ -10,6 +10,7 @@ import type {
   TFlexPromptPart,
 } from './interfaces.js';
 import { cloneSerializable, deepFreeze } from './utils.json.js';
+import { isAttachmentReference } from './utils.prompt.js';
 import { validateIdentifier } from './utils.validation.js';
 
 export interface IRunResultProjection {
@@ -126,11 +127,15 @@ function base64Size(data: string): number | undefined {
 
 export function describeAttachment(
   part: Exclude<TFlexPromptPart, { type: 'text' }>,
+  referenceProtocols: ReadonlySet<string>,
 ): Omit<IFlexAttachmentMessagePart, 'partId' | 'type' | 'attachmentType'> {
   let source: TFlexAttachmentSource = 'inline-base64';
   let sizeBytes: number | undefined;
   let inferredMediaType: string | undefined;
-  if (/^data:/i.test(part.data)) {
+  if (isAttachmentReference(part.data, referenceProtocols)) {
+    source = 'reference';
+    sizeBytes = part.sizeBytes;
+  } else if (/^data:/i.test(part.data)) {
     source = 'data-url';
     const commaIndex = part.data.indexOf(',');
     if (commaIndex >= 0) {

package/ts_chat_harness/functions.intents.ts

@@ -45,6 +45,12 @@ export interface IFlexHarnessSendIntentOptions {
    * accounts or reasoning efforts encodes them in its own hint scheme here.
    */
   modelHint?: string;
+  /**
+   * The prompt parts of the message's attachments, in their order, as the host made them, such as
+   * references to the files the tab uploaded to it. Without them, each attachment is sent with the
+   * content the composer read.
+   */
+  attachmentParts?: readonly TFlexPromptPart[];
 }
 
 function base64Utf8(text: string): string {
@@ -103,9 +109,12 @@ export function flexHarnessSendIntent(
   detail: plugins.IHarnessComposerSendDetail,
   options: IFlexHarnessSendIntentOptions = {},
 ): TFlexHarnessChatIntent {
+  if (options.attachmentParts && options.attachmentParts.length !== detail.attachments.length) {
+    throw new Error('Each attachment needs one prompt part.');
+  }
   const prompt: TFlexPromptPart[] = [
     ...(detail.text.length > 0 ? [{ type: 'text' as const, text: detail.text }] : []),
-    ...detail.attachments.map(attachmentToPromptPart),
+    ...(options.attachmentParts ?? detail.attachments.map(attachmentToPromptPart)),
   ];
   const modelHint = options.modelHint ?? detail.model;
   const promptOptions: IFlexPromptOptions = modelHint === undefined ? {} : { modelHint };

package/ts_chat_harness/readme.md

@@ -89,7 +89,7 @@ The intent functions map component events to plain `TFlexHarnessChatIntent` valu
 
 Intents are untrusted client input: a client can name any `scopeId` and `sessionId`. Before calling `runFlexHarnessChatIntent`, the server authenticates the caller and checks, or replaces, the intent's target with a session the caller may act on. The harness itself checks only that a permission belongs to the session the intent names, not who is asking.
 
-- `harness-send`: text and attachments become prompt parts. A text attachment is sent as a UTF-8 file part; when its media type does not already name text (`text/*`, JSON, XML, YAML, CSV or a `+json`, `+xml` or `+yaml` type), it gains `charset=utf-8`, for example `application/x-openscad; charset=utf-8`, so a provider that reads only some files natively can still send it as text; a truncated attachment, or one without a payload, throws. A message sent while idle, queued behind the running turn, or delivered as `next-turn` becomes `enqueuePrompt`. A steer joins the running turn, `transcript.activeQueueId`, through `steerPrompt`, and answers on that turn's model; with no running turn, or when its turn ended before the harness took it, it is the next turn's input and is queued with the prompt options. A steer id comes from `crypto.randomUUID()`, which browsers offer only in secure contexts (HTTPS or localhost). The composer's `model` becomes the prompt's `modelHint`; a host that offers accounts or reasoning efforts passes its own `modelHint`.
+- `harness-send`: text and attachments become prompt parts. A text attachment is sent as a UTF-8 file part; when its media type does not already name text (`text/*`, JSON, XML, YAML, CSV or a `+json`, `+xml` or `+yaml` type), it gains `charset=utf-8`, for example `application/x-openscad; charset=utf-8`, so a provider that reads only some files natively can still send it as text; a truncated attachment, or one without a payload, throws. A host that makes the attachments' prompt parts itself, such as references to files the tab uploaded to it, passes them as `attachmentParts`, one per attachment in order. A message sent while idle, queued behind the running turn, or delivered as `next-turn` becomes `enqueuePrompt`. A steer joins the running turn, `transcript.activeQueueId`, through `steerPrompt`, and answers on that turn's model; with no running turn, or when its turn ended before the harness took it, it is the next turn's input and is queued with the prompt options. A steer id comes from `crypto.randomUUID()`, which browsers offer only in secure contexts (HTTPS or localhost). The composer's `model` becomes the prompt's `modelHint`; a host that offers accounts or reasoning efforts passes its own `modelHint`.
 - `harness-permission-response`: `reject` rejects; an approval with `remember` is `always`, otherwise `once`. A request with `requiresExplicitResponse` refuses `always`.
 - `harness-abort`: `abort()` of the session.
 

package/ts_chat_harness_server/classes.chathub.ts

@@ -87,7 +87,11 @@ export class FlexHarnessChatHub<TContext> {
     this.titleOf = optionsArg.titleOf ?? titleFromMessage;
     this.directory = optionsArg.directory ?? new FlexHarnessChatScopeDirectory(this.harness);
     this.listsFromHarness = !optionsArg.directory;
-    this.gate = new FlexHarnessChatTurnGate<TContext>(this.harness, this.limits);
+    this.gate = new FlexHarnessChatTurnGate<TContext>(
+      this.harness,
+      this.limits,
+      optionsArg.attachmentPart?.bind(optionsArg),
+    );
     this.sessionLists = new FlexHarnessChatSessionLists(this.peers);
     this.unsubscribe = this.harness.subscribe((eventArg) => this.takeEvent(eventArg));
     this.sweepTimer = setInterval(() => void this.forgetClosedTabs(), this.limits.sweepIntervalMs);