@deepseek-ai/dsh-llm 0.1.2-alpha.5 → 0.1.3-alpha.2

package/lib/types/content.d.ts

@@ -1,7 +1,7 @@
 /** Content-block structure helpers. @module @deepseek-ai/dsh-llm/content */
 import type { ContentBlock } from './types.ts';
 import type { Message } from './message.ts';
-import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
+import type { AttachmentStore, FileAttachmentRef, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
 /** Execution-world path that model tools can use to read one normalized attachment. */
 export interface ImageAttachmentAccess {
     /** Absolute path to immutable normalized bytes; callers must treat it as read-only. */
@@ -57,6 +57,31 @@ export declare function offloadedImageText(ref: ImageAttachmentRef, access?: Ima
  * @returns whether any nested block is an image.
  */
 export declare function contentHasImage(content: readonly ContentBlock[]): boolean;
+/**
+ * True when typed model content contains a file block, walking nested
+ * tool-result content on the same recursion every file policy shares.
+ * @param content - typed model content blocks.
+ * @returns whether any nested block is a file.
+ */
+export declare function contentHasFile(content: readonly ContentBlock[]): boolean;
+/**
+ * Stable model-facing handle for one durable file reference: the address of
+ * the verbatim stored copy and the instruction to read it on demand. This is
+ * the only representation a provider ever receives for a file.
+ * @param ref - durable verbatim file reference.
+ * @param readonlyPath - execution-world path of the stored copy, when resolvable.
+ * @returns deterministic handle text naming the file, its size, and its address.
+ */
+export declare function fileHandleText(ref: FileAttachmentRef, readonlyPath: string | undefined): string;
+/**
+ * Project durable file history into deterministic handle text for every model
+ * route. Unlike images, no provider receives file blocks natively, so this
+ * projection is unconditional in request assembly.
+ * @param messages - complete request history.
+ * @param resolvePath - resolve one reference's current execution-world read path.
+ * @returns the original list without files, otherwise shallow message copies with handle text.
+ */
+export declare function projectFilesToText(messages: readonly Message[], resolvePath: (ref: FileAttachmentRef) => string | undefined): readonly Message[];
 /** Byte accounting and quantized removal policy for one request representation. */
 export interface RequestImageOffloadPolicy {
     /** Image count accepted by the route; omission leaves count unbounded. */

package/lib/types/content.js

@@ -89,6 +89,69 @@ export function contentHasImage(content) {
     return content.some(block => block.type === 'image'
         || (block.type === 'tool-result' && contentHasImage(block.content)));
 }
+/**
+ * True when typed model content contains a file block, walking nested
+ * tool-result content on the same recursion every file policy shares.
+ * @param content - typed model content blocks.
+ * @returns whether any nested block is a file.
+ */
+export function contentHasFile(content) {
+    return content.some(block => block.type === 'file'
+        || (block.type === 'tool-result' && contentHasFile(block.content)));
+}
+/**
+ * Stable model-facing handle for one durable file reference: the address of
+ * the verbatim stored copy and the instruction to read it on demand. This is
+ * the only representation a provider ever receives for a file.
+ * @param ref - durable verbatim file reference.
+ * @param readonlyPath - execution-world path of the stored copy, when resolvable.
+ * @returns deterministic handle text naming the file, its size, and its address.
+ */
+export function fileHandleText(ref, readonlyPath) {
+    const digest = String(ref.attachmentId).slice('sha256:'.length, 'sha256:'.length + 8);
+    const identity = `File ${quoted(ref.name)} (${ref.bytes} bytes, sha256:${digest})`;
+    if (readonlyPath === undefined) {
+        return `[${identity} was uploaded, but the current execution environment cannot access a readable path. Report that limitation if its contents are needed; do not claim to have read it.]`;
+    }
+    return `[${identity}: verbatim read-only copy saved at ${quoted(readonlyPath)}. Read that path with your file tools when its contents are needed; copy it to a writable location before modifying it. When delegating file work, include this saved path in the delegation prompt; only subagents sharing this execution environment can read it.]`;
+}
+/** Replace every file occurrence, including nested tool results, with handle text. */
+function replaceFilesWithHandles(blocks, resolvePath) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'file') {
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: fileHandleText(block.attachment, resolvePath(block.attachment)) });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceFilesWithHandles(block.content, resolvePath);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/**
+ * Project durable file history into deterministic handle text for every model
+ * route. Unlike images, no provider receives file blocks natively, so this
+ * projection is unconditional in request assembly.
+ * @param messages - complete request history.
+ * @param resolvePath - resolve one reference's current execution-world read path.
+ * @returns the original list without files, otherwise shallow message copies with handle text.
+ */
+export function projectFilesToText(messages, resolvePath) {
+    if (!messages.some(message => contentHasFile(message.content)))
+        return messages;
+    return messages.map((message) => {
+        const content = replaceFilesWithHandles(message.content, resolvePath);
+        return content === message.content ? message : { ...message, content };
+    });
+}
 /** Base64 length of raw image bytes, including padding. */
 function base64Length(bytes) {
     return Math.ceil(bytes / 3) * 4;

package/lib/types/index.d.ts

@@ -12,12 +12,14 @@ import type { ResolvedRetryPolicy } from './retry-policy.ts';
 import type { ProviderRequestId } from './brand.ts';
 import type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
 import { HarnessError } from './error.ts';
+import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment';
 export * from './attribution.ts';
 export * from './brand.ts';
 export * from './error.ts';
 export * from './api-key.ts';
 export * from './types.ts';
 export * from './content.ts';
+export * from './assistant-stream.ts';
 export * from './message.ts';
 export * from './retry-policy.ts';
 export { BlockAssembler } from './assembler.ts';
@@ -322,6 +324,13 @@ export declare class LlmRuntime extends TypertRemoteService {
      * @returns the owning adapter's image pricing for the route, when declared.
      */
     imageRequestPricing(provider: string, model: string): LlmImageRequestPricing | undefined;
+    /**
+     * Resolve the exact text one durable file occurrence contributes to every
+     * provider request in the current execution environment.
+     * @param ref - durable verbatim file reference from model history.
+     * @returns the same deterministic handle text used at adapter dispatch.
+     */
+    fileRequestText(ref: FileAttachmentRef): string;
     /** Detach typed adapter-owned modality metadata. */
     private detachedModalities;
     /**
@@ -370,6 +379,11 @@ export declare class LlmRuntime extends TypertRemoteService {
     private registration;
     /** Remove replay state whose historical route is owned by another adapter. */
     private forAdapter;
+    /**
+     * Resolve the current execution-world read path of one durable file
+     * reference through the mounted attachment and filesystem providers.
+     */
+    private fileReadPath;
     /**
      * Final adapter boundary. Adapter selection, dispatch, iterator construction,
      * and iteration failures become one terminal failure chunk. Middleware and

package/lib/types/index.js

@@ -47,13 +47,14 @@ import { callConfigEquals } from "./call-config.js";
 import { HarnessError, INVALID_CREDENTIAL_CODE } from "./error.js";
 import { normalizeLlmFailure } from "./adapter-failure.js";
 import { normalizeApiKey } from "./api-key.js";
-import { contentHasImage, projectImagesForTextModel } from "./content.js";
+import { contentHasFile, contentHasImage, fileHandleText, projectFilesToText, projectImagesForTextModel, } from "./content.js";
 export * from "./attribution.js";
 export * from "./brand.js";
 export * from "./error.js";
 export * from "./api-key.js";
 export * from "./types.js";
 export * from "./content.js";
+export * from "./assistant-stream.js";
 export * from "./message.js";
 export * from "./retry-policy.js";
 export { BlockAssembler } from "./assembler.js";
@@ -529,6 +530,15 @@ let LlmRuntime = (() => {
         imageRequestPricing(provider, model) {
             return this.adapters.get(provider)?.adapter.imageRequestPricing(provider, model);
         }
+        /**
+         * Resolve the exact text one durable file occurrence contributes to every
+         * provider request in the current execution environment.
+         * @param ref - durable verbatim file reference from model history.
+         * @returns the same deterministic handle text used at adapter dispatch.
+         */
+        fileRequestText(ref) {
+            return fileHandleText(ref, this.fileReadPath(ref));
+        }
         /** Detach typed adapter-owned modality metadata. */
         detachedModalities(modalities) {
             return modalities === undefined ? undefined : [...modalities];
@@ -769,6 +779,27 @@ let LlmRuntime = (() => {
             const filtered = { ...options, messages };
             return Object.isFrozen(options) ? deepFreeze(filtered) : filtered;
         }
+        /**
+         * Resolve the current execution-world read path of one durable file
+         * reference through the mounted attachment and filesystem providers.
+         */
+        fileReadPath(ref) {
+            let hostPath;
+            try {
+                hostPath = this.ctx.get('attachments')?.fileHostPath(ref);
+            }
+            catch {
+                // A malformed durable reference degrades this occurrence to the no-path
+                // handle instead of failing every later request over the same log.
+                return undefined;
+            }
+            if (hostPath === undefined)
+                return undefined;
+            // Structural face: dsh-llm cannot depend on the filesystem package, and
+            // only this one mapping method is consumed.
+            const fs = this.ctx.get('fs');
+            return fs?.processPathFromHostPath(hostPath);
+        }
         /**
          * Final adapter boundary. Adapter selection, dispatch, iterator construction,
          * and iteration failures become one terminal failure chunk. Middleware and
@@ -801,13 +832,21 @@ let LlmRuntime = (() => {
                     : Object.isFrozen(options)
                         ? deepFreeze({ ...options, ...resolvedConfig })
                         : { ...options, ...resolvedConfig };
-                const projectedOptions = modelInfo.inputModalities !== undefined
+                // Files are never dispatched natively: every route receives handle text.
+                let projectedMessages = resolvedOptions.messages;
+                if (projectedMessages.some(message => contentHasFile(message.content))) {
+                    projectedMessages = projectFilesToText(projectedMessages, ref => this.fileReadPath(ref));
+                }
+                if (modelInfo.inputModalities !== undefined
                     && !modelInfo.inputModalities.includes('image')
-                    && resolvedOptions.messages.some(message => contentHasImage(message.content))
-                    ? Object.isFrozen(resolvedOptions)
-                        ? deepFreeze({ ...resolvedOptions, messages: projectImagesForTextModel(resolvedOptions.messages) })
-                        : { ...resolvedOptions, messages: projectImagesForTextModel(resolvedOptions.messages) }
-                    : resolvedOptions;
+                    && projectedMessages.some(message => contentHasImage(message.content))) {
+                    projectedMessages = projectImagesForTextModel(projectedMessages);
+                }
+                const projectedOptions = projectedMessages === resolvedOptions.messages
+                    ? resolvedOptions
+                    : Object.isFrozen(resolvedOptions)
+                        ? deepFreeze({ ...resolvedOptions, messages: projectedMessages })
+                        : { ...resolvedOptions, messages: projectedMessages };
                 const stream = dispatch(this.forAdapter(projectedOptions, adapter));
                 iterator = stream[Symbol.asyncIterator]();
             }

package/lib/types/types.d.ts

@@ -4,7 +4,7 @@
  * mapped interfaces make the content, source, and finish unions extensible.
  */
 import type { Branded } from '@deepseek-ai/dsh-brand';
-import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
 import type { ToolCallId, ProviderRequestId, ReasoningEffortId } from './brand.ts';
 import type { Message } from './message.ts';
 declare module '@deepseek-ai/cordis' {
@@ -56,6 +56,18 @@ export interface ImageBlock {
     /** Immutable bytes and intrinsic display metadata owned by the attachment service. */
     attachment: ImageAttachmentRef;
 }
+/**
+ * A durable verbatim file reference, valid in user content. Files never reach
+ * a provider natively: request assembly projects every occurrence to
+ * deterministic handle text (name, byte size, and the read-only saved path),
+ * so adapters and providers see text in its place while the durable log keeps
+ * the structured reference for presentation and authorization.
+ */
+export interface FileBlock {
+    type: 'file';
+    /** Immutable verbatim bytes and display metadata owned by the attachment service. */
+    attachment: FileAttachmentRef;
+}
 /** A tool invocation requested by the model. */
 export interface ToolCallBlock {
     type: 'tool-call';
@@ -80,6 +92,7 @@ export interface ContentBlockMap {
     'text': TextBlock;
     'reasoning': ReasoningBlock;
     'image': ImageBlock;
+    'file': FileBlock;
     'tool-call': ToolCallBlock;
     'tool-result': ToolResultBlock;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm",
   "description": "Provider-neutral LLM service interface for the DeepSeek Harness",
-  "version": "0.1.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -34,6 +34,10 @@
       "types": "./lib/types/message.d.ts",
       "default": "./lib/types/message.js"
     },
+    "./assistant-stream": {
+      "types": "./lib/types/assistant-stream.d.ts",
+      "default": "./lib/types/assistant-stream.js"
+    },
     "./typert": {
       "types": "./lib/typert.host.d.ts",
       "default": "./lib/typert.host.js"
@@ -61,16 +65,16 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-crypto": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-util-crypto": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.3-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.5",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }