@artenx/dshb 0.1.16 → 0.1.17

package/lib/core/workspace-instruction-context.d.ts

@@ -1,6 +1,5 @@
 import { SessionInstructionSnapshot, SessionInstructionSnapshotStore, WorkspaceInstructionStore } from "./workspace-instructions.js";
 import { Context, Service } from "@deepseek-ai/cordis";
-import { FileAttachmentRef, ImageAttachmentRef, ImageRequestTarget } from "@deepseek-ai/dsh-attachment";
 //#region ../../node_modules/@deepseek-ai/dsh-brand/lib/types/index.d.ts
 /**
  * Duplicate-install-safe nominal primitive helpers.
@@ -559,6 +558,313 @@ declare abstract class TypertRemoteService<out T = never> extends Service<T> {
   protected constructor(ctx: Context, serviceKey: string, options?: TypertGatewayBindingOptions);
 }
 //#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/error.d.ts
+declare const ATTACHMENT_ERROR_CODES: readonly ["TOO_MANY_IMAGES", "IMAGES_TOO_LARGE", "UNSUPPORTED_IMAGE_TYPE", "INVALID_IMAGE_BASE64", "INVALID_IMAGE", "IMAGE_TYPE_MISMATCH", "IMAGE_TOO_LARGE", "IMAGE_TOO_MANY_PIXELS", "IMAGE_DIMENSION_TOO_LARGE", "INVALID_FILE_BASE64", "INVALID_ATTACHMENT_REF", "ATTACHMENT_CORRUPT", "ATTACHMENT_WRITE_FAILED", "ATTACHMENT_NOT_FOUND", "ATTACHMENT_READ_FAILED", "ATTACHMENT_PROJECTION_UNSUPPORTED", "ATTACHMENT_FILES_UNSUPPORTED"];
+/** Stable attachment failure codes used for protocol error routing. */
+type AttachmentErrorCode = typeof ATTACHMENT_ERROR_CODES[number];
+/**
+ * Stable failures suitable for host RPC error mapping.
+ *
+ * Deliberately re-implements the `HarnessError` shape instead of extending it:
+ * the base lives in `@deepseek-ai/dsh-llm`, which itself depends on this
+ * package (`ImageBlock` references `ImageAttachmentRef`), so sharing the base
+ * would create a dependency cycle. Consumers route on `code`, never on the
+ * prototype chain, so the shapes stay interchangeable at the wire boundary.
+ */
+declare class AttachmentError extends Error {
+  /** Stable machine-routing failure code. */
+  readonly code: AttachmentErrorCode;
+  /**
+   * @param message - human-readable failure description without raw bytes or host paths.
+   * @param code - stable machine-routing code.
+   * @param options - optional chained cause.
+   */
+  constructor(message: string, code: AttachmentErrorCode, options?: ErrorOptions);
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/brand.d.ts
+/** Opaque content-addressed identifier for one immutable attachment object. */
+type AttachmentId = Branded<'AttachmentId'>;
+/**
+ * Brand a validated storage identifier.
+ * @param value - backend-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+declare function AttachmentId(value: string): AttachmentId;
+/** Opaque deterministic identity for one request-image transformation. */
+type ImageVariantId = Branded<'ImageVariantId'>;
+/**
+ * Brand a validated request-image transformation identifier.
+ * @param value - attachment-provider-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+declare function ImageVariantId(value: string): ImageVariantId;
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/types.d.ts
+/** Raster image formats accepted by the version-one attachment path. */
+type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Durable, serializable reference to one immutable normalized image. */
+interface ImageAttachmentRef {
+  /** Opaque storage identifier; never a filesystem path or bearer URL. */
+  attachmentId: AttachmentId;
+  /** Media type verified from the stored bytes. */
+  mediaType: ImageMediaType;
+  /** Exact encoded byte length. */
+  bytes: number;
+  /** Intrinsic encoded width in pixels. */
+  width: number;
+  /** Intrinsic encoded height in pixels. */
+  height: number;
+  /** Optional display name stripped of local path information. */
+  name?: string;
+  /**
+   * Input dimensions after applying EXIF orientation and before normalization
+   * scaling. Present only when normalization reduced the image.
+   */
+  originalDimensions?: {
+    width: number;
+    height: number;
+  };
+}
+/**
+ * Durable, serializable reference to one verbatim stored file. Files are
+ * stored byte-for-byte with no normalization; `attachmentId` is the sha256
+ * digest of exactly those bytes.
+ */
+interface FileAttachmentRef {
+  /** Opaque content-addressed storage identifier; never a filesystem path or bearer URL. */
+  attachmentId: AttachmentId;
+  /** Sanitized display filename, also the stored object's leaf name. */
+  name: string;
+  /** Exact byte length. */
+  bytes: number;
+}
+/** Base64-encoded file upload accompanying one wire request. */
+interface EncodedFileAttachment {
+  /** Canonical base64 encoding of the file bytes. */
+  data: string;
+  /** Optional display name; it is never interpreted as a path. */
+  name?: string;
+}
+/** Request to durably commit one file verbatim. */
+interface SaveFileAttachment {
+  data: Uint8Array;
+  /** Optional browser/provider display name; it is never interpreted as a path. */
+  name?: string;
+}
+/** Request to durably commit one file from bounded byte chunks. */
+interface SaveFileStreamAttachment {
+  /** Exact file bytes in order; providers must not retain the complete sequence in memory. */
+  data: AsyncIterable<Uint8Array>;
+  /** Optional cancellation for source reads and storage writes. */
+  signal?: AbortSignal;
+  /** Optional browser/provider display name; it is never interpreted as a path. */
+  name?: string;
+}
+/** Deployment-resolved limits used by upload admission and request buffering. */
+interface ImageAttachmentLimits {
+  maxImageBytes: number;
+  maxImagesPerMessage: number;
+  maxMessageImageBytes: number;
+  maxImagePixels: number;
+  /** Maximum intrinsic width and maximum intrinsic height in pixels for one image. */
+  maxImageDimension: number;
+  mediaTypes: readonly ImageMediaType[];
+}
+/**
+ * Browser-submitted prompt content accepted by Host prompt endpoints; the
+ * accepting Host promotes image parts to durable references through
+ * `ctx.attachments.admitPromptContent()` before any message is created, so a wire caller can
+ * never cite an attachment it did not upload.
+ */
+type PromptContentPart = {
+  readonly type: 'text';
+  readonly text: string;
+} | {
+  readonly type: 'image';
+  readonly mediaType: ImageMediaType;
+  readonly data: string;
+  readonly name?: string;
+};
+/** Host prompt content whose file receipts are resolved and whose image bytes await admission. */
+type AttachmentAdmissionPart = PromptContentPart | {
+  readonly type: 'file';
+  readonly attachment: FileAttachmentRef;
+};
+/** Host-admitted prompt content with every attachment represented by its durable reference. */
+type AdmittedPromptContentPart = {
+  readonly type: 'text';
+  readonly text: string;
+} | {
+  readonly type: 'image';
+  readonly attachment: ImageAttachmentRef;
+} | {
+  readonly type: 'file';
+  readonly attachment: FileAttachmentRef;
+};
+/** Request to validate and durably commit one image. */
+interface SaveImageAttachment {
+  data: Uint8Array;
+  /** Caller-declared media type, checked against fully decoded bytes. */
+  mediaType: ImageMediaType;
+  /** Optional browser/provider display name; it is never interpreted as a path. */
+  name?: string;
+}
+/** Stored image bytes returned after reference and digest verification. */
+interface StoredImageAttachment {
+  ref: ImageAttachmentRef;
+  data: Uint8Array;
+}
+/** Deterministic request-image target selected by one exact model route for one attachment. */
+interface ImageRequestTarget {
+  /** Target width in pixels; a target above the source keeps the source width. */
+  width: number;
+  /** Target height in pixels; a target above the source keeps the source height. */
+  height: number;
+  /** Encoded-byte target before base64 expansion or Files API upload; the smallest quality-ladder output is kept when no quality fits. */
+  maxBytes: number;
+}
+/** Cached request version derived from one provider-independent normalized attachment. */
+interface RequestImageAttachment {
+  /** Cache and upload-index key over the attachment id, policy, and fixed encoder parameters. */
+  variantId: ImageVariantId;
+  /** Durable normalized attachment from which this request version was derived. */
+  attachment: ImageAttachmentRef;
+  /** Encoded request bytes. */
+  data: Uint8Array;
+  mediaType: ImageMediaType;
+  bytes: number;
+  width: number;
+  height: number;
+  /** Provider-compatible sample depth proven after request encoding. */
+  depth: 'uchar';
+  /** Provider-compatible color space proven after request encoding. */
+  space: 'srgb';
+  /** Whether the encoded request version retains an alpha channel. */
+  hasAlpha: boolean;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/index.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    attachments: AttachmentStore;
+  }
+}
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+declare abstract class AttachmentStore extends Service {
+  constructor(ctx: Context);
+  /** Deployment-resolved image policy used by authoritative and fast-path validation. */
+  abstract readonly imageLimits: ImageAttachmentLimits;
+  /**
+   * Validate one image without persisting it.
+   * Batch callers validate every member before saving any member.
+   * @param input - encoded bytes, declared media type, and optional display name.
+   * @returns completion after the encoded raster has been fully decoded.
+   */
+  abstract validateImage(input: SaveImageAttachment): Promise<void>;
+  /**
+   * Validate one ordered image batch before committing any member.
+   * Validation failures start no writes; storage failures return no partial
+   * references, although already published content-addressed objects may stay
+   * unreachable until a future retention policy collects them.
+   * @param inputs - encoded images in their owning message order.
+   * @returns durable references in the exact input order.
+   */
+  protected validateImageBatch(inputs: readonly SaveImageAttachment[]): void;
+  /**
+   * Validate and durably commit one ordered image batch.
+   * @param inputs - encoded images in owning-message order.
+   * @returns durable normalized attachment references in the same order after every member succeeds.
+   */
+  saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
+  /**
+   * Admit one Host prompt and replace each uploaded image with its durable reference.
+   * Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
+   * @param content - prompt parts in message order after file receipt resolution.
+   * @returns admitted prompt parts in the same order as `content`.
+   * @throws AttachmentError when the image batch is refused.
+   */
+  admitPromptContent(content: readonly AttachmentAdmissionPart[]): Promise<AdmittedPromptContentPart[]>;
+  /**
+   * Decode and durably commit one canonical base64 file upload.
+   * @param input - canonical base64 bytes and optional display name.
+   * @returns the durable content-addressed file reference.
+   * @throws AttachmentError when the encoding or storage operation is refused.
+   */
+  admitEncodedFile(input: EncodedFileAttachment): Promise<FileAttachmentRef>;
+  /**
+   * Identify a failure emitted by this attachment capability by its stable code.
+   * @param error - value caught from an attachment operation.
+   * @returns whether the value is an attachment failure.
+   */
+  isAttachmentError(error: unknown): error is AttachmentError;
+  /**
+   * Validate and durably commit one image before its owning session event is appended.
+   * The returned reference describes the persisted normalized image. When
+   * normalization reduces the raster, its `originalDimensions` records the
+   * orientation-applied input dimensions.
+   * @param input - encoded bytes, declared media type, and optional display name.
+   * @returns the durable content-addressed normalized image reference.
+   */
+  abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
+  /**
+   * Read one image and verify that bytes still match the recorded reference.
+   * @param ref - durable reference from the session log.
+   * @param signal - optional cancellation for backend read and verification work.
+   * @returns the verified bytes and normalized attachment reference.
+   * @throws the signal reason when aborted, or a storage error when verification fails.
+   */
+  abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+  /**
+   * Locate the provider-owned normalized object in the harness host filesystem.
+   * @param ref - durable normalized attachment reference.
+   * @returns an absolute host path, or undefined when this backend is not host-file-backed.
+   * @throws an AttachmentError when the durable reference is invalid.
+   */
+  imageHostPath(ref: ImageAttachmentRef): string | undefined;
+  /**
+   * Durably commit one file byte-for-byte before its owning session event is
+   * appended. Files carry no admission limits: any byte content and length is
+   * accepted, and the stored object is the exact submitted bytes. Backends
+   * without verbatim file storage keep this default rejection.
+   * @param input - exact bytes and optional display name.
+   * @returns the durable content-addressed file reference.
+   */
+  saveFile(input: SaveFileAttachment): Promise<FileAttachmentRef>;
+  /**
+   * Durably commit one file byte-for-byte from bounded chunks. Providers must
+   * apply backpressure and must not collect the complete file in memory.
+   * Backends without streamed verbatim storage keep this default rejection.
+   * @param input - ordered exact bytes, optional cancellation, and display name.
+   * @returns the durable content-addressed file reference.
+   */
+  saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>;
+  /**
+   * Read and verify one verbatim stored file as bounded chunks. Providers must
+   * not collect the complete file in memory. Backends without verbatim file
+   * reads keep this default rejection.
+   * @param ref - durable reference from the session log.
+   * @param signal - optional cancellation for backend reads and verification work.
+   * @returns exact file bytes in order; integrity failures reject the iteration.
+   */
+  readFileStream(ref: FileAttachmentRef, signal?: AbortSignal): AsyncIterable<Uint8Array>;
+  /**
+   * Locate the verbatim stored file object in the harness host filesystem.
+   * @param ref - durable file reference.
+   * @returns an absolute host path, or undefined when this backend is not host-file-backed.
+   * @throws an AttachmentError when the durable reference is invalid.
+   */
+  fileHostPath(ref: FileAttachmentRef): string | undefined;
+  /**
+   * Generate or read one deterministic model-request version from the stored normalized image.
+   * @param ref - durable provider-independent normalized attachment reference.
+   * @param target - route-chosen dimensions and byte target; an unmet byte target yields the smallest ladder output.
+   * @param signal - optional cancellation.
+   * @returns request bytes and the cache/upload identity covering every transform input.
+   */
+  readImageRequest(ref: ImageAttachmentRef, target: ImageRequestTarget, signal?: AbortSignal): Promise<RequestImageAttachment>;
+}
+//#endregion
 //#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/brand.d.ts
 /** Stable identity carried by one message across inbox, log, and model-request boundaries. */
 type MessageId = Branded<'MessageId'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artenx/dshb",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Routes DSH filesystem, shell, subprocess, and PTY operations to local, SSH, and Docker execution nodes, with a node registry, an authentication gate, a mobile-aware management UI, and per-workspace custom project instructions.",
   "type": "module",
   "main": "lib/index.js",
@@ -81,10 +81,7 @@
       ]
     },
     "compatibility": {
-      "dshReleases": {
-        "0.1.7-rc.1": "compatible",
-        "0.2.1-rc.2": "compatible"
-      },
+      "dshReleases": ">=0.1.7-rc.1 <0.2.1-rc.2",
       "nodeVersions": ">=22.13"
     }
   },
@@ -94,22 +91,22 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-ui-settings": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-layout": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-workspace": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-cmdline": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-credentials": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-fs": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-fs-sandbox": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-host-directory-picker": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-shell": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-bash-sandbox": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-subprocess": "=0.1.7-rc.1 || =0.2.1-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "=0.1.7-rc.1 || =0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-workspace": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-cmdline": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-credentials": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-fs": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-fs-sandbox": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-host-directory-picker": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-sandbox": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-shell": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-bash-sandbox": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": ">=0.1.7-rc.1 <0.2.1-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": ">=0.1.7-rc.1 <0.2.1-rc.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
@@ -138,7 +135,7 @@
   },
   "engines": {
     "node": ">=22.13",
-    "dsh": "=0.1.7-rc.1 || =0.2.1-rc.2"
+    "dsh": ">=0.1.7-rc.1 <0.2.1-rc.2"
   },
   "sideEffects": false,
   "keywords": [