@artenx/dshb 0.1.15 → 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 } from "@deepseek-ai/dsh-attachment";
 //#region ../../node_modules/@deepseek-ai/dsh-brand/lib/types/index.d.ts
 /**
  * Duplicate-install-safe nominal primitive helpers.
@@ -35,6 +34,7 @@ interface TypertOwnedValue<Value> extends Disposable {
 declare const LOOKUP_HOST: unique symbol;
 declare const LOOKUP_WIRE: unique symbol;
 declare const CONTEXT_WIRE: unique symbol;
+declare const RESOURCE_ID: unique symbol;
 /** Type-level association between a Host object and its wire identity. */
 interface TypertLookup<Host, Wire> {
   readonly [LOOKUP_HOST]: Host;
@@ -54,6 +54,21 @@ type TypertContextWire<ContextType> = ContextType extends TypertContext<infer Wi
 interface TypertLookupMap {}
 /** Merge-extensible scoped Context declarations. */
 interface TypertContextMap {}
+/** Type-level association between a resource kind and its identity type. */
+interface TypertResource<Id> {
+  readonly [RESOURCE_ID]: Id;
+}
+/** Extract the identity type associated with one resource declaration. */
+type TypertResourceId<Resource> = Resource extends TypertResource<infer Id> ? Id : never;
+/**
+ * Merge-extensible resource kinds whose identities a Remote call or forwarded
+ * event may carry. The package that owns an identity type declares its kind;
+ * the value is that kind's identity type, a string type such as a branded id.
+ * `global` names the built-in identity-less resource and is never a kind here.
+ */
+interface TypertResourceMap {}
+/** One declared resource kind. */
+type TypertResourceKind = Extract<keyof TypertResourceMap, string>;
 /** Awaitable disposer returned by Cordis-owned Typert registrations. */
 type TypertDisposer = () => Promise<void>;
 type StringKeyOf<Value> = Extract<keyof Value, string>;
@@ -67,31 +82,31 @@ interface TypertSchema<Output = unknown> {
   parse(value: unknown): Output;
 }
 /** Codec attached to one invocation parameter or result. */
-type TypertCodec = {
+type TypertCodec<Value = unknown> = (TypertRemoteValue<Value> & {
   readonly mode: 'strict';
   readonly typeSymbol: string;
-  /** Materialize and return the process-realm schema on first boundary use. */
-  readonly create: () => TypertSchema;
   /**
    * Decode a unary result whose fields require type-specific handling.
    * @param value - result reconstructed by the RPC carrier.
    * @returns the validated result, retaining native byte views.
    */
-  readonly decode?: (value: unknown) => unknown;
+  readonly decode?: ((value: unknown) => unknown) | undefined;
   /**
    * Project typed binary fields into RPC result attachments.
    * @param value - native unary result.
    * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
    * @returns JSON metadata with untouched JSON subtrees retained.
    */
-  readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown;
-} | {
+  readonly encode?: ((value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown) | undefined;
+}) | {
   readonly mode: 'src-json';
 };
 /** One ordered business parameter in a Remote invocation. */
 interface InvocationParameterDescriptor {
   /** Source-level parameter name. */
   readonly name: string;
+  /** Source parameter documentation, independent of JSON Schema support. */
+  readonly description?: string;
   /** Required key in the wire `args` object. */
   readonly wire: string;
   /** Whether the value is JSON or requires a registered Host lookup. */
@@ -158,6 +173,8 @@ interface InvocationDescriptor {
   };
   /** Codec for the unary result or each yielded stream item. */
   readonly result: TypertCodec;
+  /** Source-owned method documentation; ordinary methods need not have JSDoc. */
+  readonly description?: string;
   /** Source declaration used only for diagnostics. */
   readonly sourceLocation?: InvocationSourceLocation;
 }
@@ -168,19 +185,46 @@ interface InvocationDescriptor {
  */
 type PeerId = Branded<'PeerId'>;
 /**
- * One Peer's session on this Host. Connection owns it: `ctx` is the Cordis
+ * Merge-extensible caller identities. Each driver declares its own entry.
+ * Every entry is a JSON value with a unique literal `kind`, carries no
+ * credential, and is safe to persist in a Session log.
+ */
+interface PrincipalMap {
+  /** The local user who owns this Host. */
+  owner: {
+    readonly kind: 'owner';
+  };
+}
+/** One caller identity; the authorization layer reads only this. */
+type Principal = PrincipalMap[keyof PrincipalMap];
+/**
+ * One Peer's session on this Host. Its creator owns it: `ctx` is the Cordis
  * scope that owns connection-lifetime registrations and is disposed with the
- * Peer. Who the Peer is and what it may do are not recorded here.
+ * Peer, and `principal` is the caller identity fixed when the Peer was created.
  */
 interface PeerScope {
   readonly id: PeerId;
+  /** Connection-lifetime registrations; disposed with the Peer. */
   readonly ctx: Context;
+  /** Caller identity fixed at creation by in-process Host code; no wire field can set it. */
+  readonly principal: Principal;
+  /** Aborted once the Peer is disposed; Remote streams that speak for the Peer end with it. */
+  readonly signal: AbortSignal;
+  /** Whether the Peer may open a forwarded-event stream; this does not grant business permissions. */
+  readonly interactions: 'answer' | 'none';
   /**
    * Tear down every registration made through `ctx`.
    * @returns settles once the scope has quiesced; racing calls share one completion.
    */
   dispose(): Promise<void>;
 }
+/** Carrier capacity for buffered uplink frames of one logical stream. */
+interface RemoteUplinkWindow {
+  /** Maximum complete encoded frame bytes waiting for the Host consumer. */
+  readonly maxBytes: number;
+  /** UTF-8 envelope bytes added to a compact JSON item with a present value field. */
+  readonly frameOverheadBytes: number;
+}
 /**
  * The context of one Remote call, reachable inside the receiving method as
  * `this.ctx.invocation`. The Gateway derives the receiver from a Context that
@@ -194,10 +238,12 @@ interface RemoteInvocation {
   };
   /** Cordis service key of the receiving Service. */
   readonly service: string;
-  /** Peer the call speaks for; an in-process carrier speaks for the operator. */
+  /** Peer the call speaks for; every carrier names it explicitly. */
   readonly peer: PeerScope;
   /** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
   readonly signal: AbortSignal;
+  /** Carrier frame capacity; absent when the carrier imposes no encoded-frame inbox limit. */
+  readonly uplinkWindow?: RemoteUplinkWindow | undefined;
   /**
    * The Client's uplink items for this call. Available once; a second call
    * throws. With an uplink codec on the descriptor every item is decoded to
@@ -218,18 +264,33 @@ interface TypertRemoteContribution {
   /** Consumer-side invocation descriptors generated from that package. */
   readonly descriptors: readonly InvocationDescriptor[];
 }
+/** Generated parser and optional lossless tool-schema projection of one Remote value. */
+interface TypertRemoteValue<Value = unknown> {
+  /** Materialize the generated parser without loading the owning Service. */
+  readonly create: () => TypertSchema<Value>;
+  /** Source-owned value documentation, independent of tool projection support. */
+  readonly description?: string | undefined;
+  /** Present when the value is representable in the tool-schema subset without losing constraints; may be derived lazily. */
+  readonly jsonSchema?: Readonly<Record<string, unknown>> | undefined;
+  /** Projection failure for consumers that require JSON Schema; parsing remains available. */
+  readonly jsonSchemaError?: string | undefined;
+}
 /**
  * Resolve one validated wire identity, synchronously or asynchronously.
  * @param id - validated wire identity.
  * @returns the Host object, or `undefined` when unavailable.
  */
 type TypertLookupResolver<Host = unknown, Wire = unknown> = (id: Wire) => Host | undefined | Promise<Host | undefined>;
+/** Resource kinds whose identity type is a wire identity; every kind for a type-erased provider. */
+type TypertResourceKindFor<Wire> = unknown extends Wire ? TypertResourceKind : { [Kind in TypertResourceKind]: [Wire] extends [TypertResourceId<TypertResourceMap[Kind]>] ? Kind : never; }[TypertResourceKind];
 /** Runtime provider for one declared Host object lookup. */
 interface TypertLookupProvider<Host = unknown, Wire = unknown> {
   /** Source parameter name recognized by the SRC weak parser. */
   readonly parameter: string;
   /** Wire field replacing the Host object parameter. */
   readonly wire: string;
+  /** Resource kind the wire identity names; a parameter of this lookup carries that resource. */
+  readonly resource?: TypertResourceKindFor<Wire>;
   /** Canonical Host type symbol used by strict generation. */
   readonly hostTypeSymbol: string;
   /** Canonical wire type symbol used by strict generation. */
@@ -260,6 +321,8 @@ interface TypertHostContextAdapter<Wire = unknown> {
   readonly wire: string;
   /** Canonical wire type symbol used by strict generation. */
   readonly wireTypeSymbol: string;
+  /** Resource kind the wire identity names; a call scoped to this Context carries that resource. */
+  readonly resource?: TypertResourceKindFor<Wire>;
   /**
    * Resolve a validated wire identity to a live Host Context.
    * @param id - validated wire identity.
@@ -286,7 +349,7 @@ interface TypertClientContextAdapter<Wire = unknown> {
 }
 /** Notification emitted after a Typert runtime registry changes. */
 interface TypertRegistryChange {
-  readonly kind: 'local' | 'remote' | 'lookup' | 'host-context' | 'client-context';
+  readonly kind: 'local' | 'remote' | 'lookup' | 'host-context' | 'client-context' | 'resource';
   readonly key: string;
 }
 /** Listener for one Typert runtime registry. */
@@ -396,7 +459,7 @@ interface TypertContextRegistry {
    */
   registerClient<K extends StringKeyOf<TypertContextMap>>(key: K, adapter: TypertClientContextAdapter<TypertContextWire<TypertContextMap[K]>>): TypertDisposer;
   /**
-   * Look up a Host Context adapter.
+   * Look up a Host Context adapter; a configured resolver keeps the adapter's declaration and `resource`.
    * @param key - descriptor Context key.
    * @returns the adapter, or `undefined` when absent.
    */
@@ -414,12 +477,49 @@ interface TypertContextRegistry {
    */
   subscribe(listener: TypertRegistryListener): TypertDisposer;
 }
+/** Default wire field of one resource kind. */
+interface TypertResourceDeclaration {
+  /** Top-level or first-object wire field holding one identity of the kind. */
+  readonly field: string;
+}
+/** One registered resource kind with its default wire field. */
+interface TypertResourceEntry extends TypertResourceDeclaration {
+  /** Registered resource kind. */
+  readonly kind: string;
+}
+/** Runtime registry of resource kinds' default wire fields. */
+interface TypertResourceRegistry {
+  /**
+   * Register one kind's default wire field for the calling fiber. Only the
+   * domain that owns the kind registers it.
+   * @param kind - merge-declared resource kind.
+   * @param declaration - the kind's default wire field.
+   * @returns disposer withdrawing the exact registration.
+   * @throws Error when the kind is already registered or is `global`, the built-in resource kind.
+   */
+  register(kind: TypertResourceKind, declaration: TypertResourceDeclaration): TypertDisposer;
+  /**
+   * Look up one kind's declaration.
+   * @param kind - resource kind.
+   * @returns the live declaration, or `undefined` when unregistered.
+   */
+  get(kind: string): TypertResourceDeclaration | undefined;
+  /** @returns a registration-order snapshot of registered kinds with their fields. */
+  entries(): readonly TypertResourceEntry[];
+  /**
+   * Observe later resource-kind changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypertRegistryListener): TypertDisposer;
+}
 /** Minimal Typert runtime consumed through dependency inversion. */
 interface TypertRegistryContract {
   readonly local: TypertLocalRegistry;
   readonly remotes: TypertRemoteRegistry;
   readonly lookups: TypertLookupRegistry;
   readonly contexts: TypertContextRegistry;
+  readonly resources: TypertResourceRegistry;
 }
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -453,11 +553,318 @@ declare abstract class TypertRemoteService<out T = never> extends Service<T> {
    * Register the Service and bind the same key to Typert Gateway.
    * @param ctx - owning Cordis Context.
    * @param serviceKey - exact Cordis service key and default wire namespace.
-   * @param options - optional distinct wire namespace.
+   * @param options - optional wire namespace.
    */
   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'>;
@@ -703,9 +1110,8 @@ interface ToolRemovalBlock {
 }
 /**
  * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support. Developer tool-change blocks are
- * reserved for Session V4 persistence; providers and UI reject them until
- * their producers and consumers are implemented together.
+ * with adapter, UI, and compaction support. Tool-change blocks belong to
+ * developer messages; `projectToolUpdates` selects what each route receives.
  */
 interface ContentBlockMap {
   'text': TextBlock;
@@ -838,9 +1244,26 @@ interface LlmConfigurableProvider {
    * from outside.
    */
   declared?: boolean;
+  /**
+   * Route endpoint the adapter uses when the profile sets no `baseURL`; the
+   * adapter may still send an individual model to that model's own endpoint.
+   * Absent when the route has no fixed endpoint.
+   */
+  defaultBaseURL?: string;
+  /** Environment variables used to construct a provider endpoint; absent when none are reported. */
+  baseURLEnv?: readonly string[];
+  /** Authentication the adapter performs when the profile names no credential reference; absent when it reports none. */
+  nativeAuth?: LlmNativeAuth;
   /** Configuration diagnostic for repair; unaffected models may remain serviceable. */
   error?: string;
 }
+/** Authentication a provider route performs without a credential reference in its profile. */
+interface LlmNativeAuth {
+  /** Environment variables the route's authentication reads, in lookup order; empty when it reads none. */
+  env: readonly string[];
+  /** Whether a stored OAuth sign-in can authenticate the route. */
+  oauth: boolean;
+}
 /**
  * One interrogation of a provider endpoint that configuration has not stored
  * yet. Configuration surfaces send the draft a user is still editing, so the
@@ -920,7 +1343,7 @@ interface LlmReasoningEffortInfo {
 }
 /** Selectable reasoning efforts for one exact provider/model route. */
 interface LlmModelReasoningInfo {
-  /** Supported efforts in adapter-preferred display order. */
+  /** Supported efforts from least to greatest selectable reasoning effort, not predicted token use or latency. */
   efforts: readonly LlmReasoningEffortInfo[];
   /**
    * Adapter-configured default materialized into requests when callers omit
@@ -935,6 +1358,16 @@ interface LlmModelReasoningInfo {
  * can follow the cached history instead of rewriting message 0.
  */
 type SystemPromptUpdate = 'in-history';
+/**
+ * How a model accepts native tool declarations that change mid-conversation.
+ * `'addition-only'`: the model reads a `tool-addition` block in a later
+ * developer message as activating a tool declared with `deferLoading`, so an
+ * added tool follows the cached history instead of rewriting the declaration
+ * list. `'in-history'`: the model additionally reads `tool-removal` blocks,
+ * so a removed tool keeps its declaration and the removal follows the history.
+ * Absent means every request declares the complete current tool list.
+ */
+type ToolUpdate = 'in-history' | 'addition-only';
 /** Exact-route model metadata resolved by its owning adapter. */
 interface LlmResolvedModelInfo extends LlmModelInfo {
   /** Provider-owned context capacity when known. */
@@ -945,6 +1378,8 @@ interface LlmResolvedModelInfo extends LlmModelInfo {
   reasoning?: LlmModelReasoningInfo;
   /** Declared mid-conversation system prompt handling; absent means only a leading system message is read. */
   systemPromptUpdate?: SystemPromptUpdate;
+  /** Declared mid-conversation tool declaration handling; absent means every request declares the complete tool list. */
+  toolUpdate?: ToolUpdate;
 }
 /**
  * Adapter-private lossless-JSON state for replaying a successful response,
@@ -1033,6 +1468,18 @@ interface RequestUserInput {
 }
 /** A durable conversation message or a user input used only for one request. */
 type RequestMessage = Message | RequestUserInput;
+/** Logged tool declarations and update identities since the last declaration reset. */
+interface ToolHistory {
+  /** Complete active declarations at the start of this history. */
+  readonly tools: readonly ToolSchema[];
+  /** Ordered developer messages, with additions resolved from their historical headers. */
+  readonly updates: readonly {
+    /** Identity used to locate this update in the derived request history. */
+    readonly messageId: MessageId;
+    /** Added definitions resolved from the event's referenced request header. */
+    readonly additions: readonly ToolSchema[];
+  }[];
+}
 /** A single model request, fully assembled. */
 interface GenerateOptions {
   /** Registered provider route selecting the adapter instance. */
@@ -1054,6 +1501,8 @@ interface GenerateOptions {
   system?: string;
   /** Tool schemas (adapters map to the provider's `tools` field). */
   tools?: ToolSchema[];
+  /** Session-folded tool history used for route projection; omission sends complete declarations without tool updates. */
+  toolHistory?: ToolHistory;
   temperature?: number;
   maxTokens?: number;
   /**
@@ -1070,8 +1519,8 @@ interface GenerateOptions {
   sessionId?: Branded<'SessionId'>;
   /**
    * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata or purpose-specific
-   * generation policy. Ordinary conversation requests leave it unset.
+   * map the purpose to model-hidden transport metadata. Ordinary conversation
+   * requests leave it unset.
    */
   purpose?: 'compaction' | 'session-title';
 }
@@ -1407,20 +1856,33 @@ interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {
 type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;
 //#endregion
 //#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/call-config.d.ts
+/** Concrete generation settings; omitted controls use the selected route's defaults. */
+interface LlmCallControls {
+  reasoningEffort?: ReasoningEffortId;
+  temperature?: number;
+  maxTokens?: number;
+  stop?: string[];
+}
 /**
  * Provider, model, reasoning effort, and sampling scalars of one conversation's
  * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
  * the loop builds requests from the logged header rather than accepting these
  * per call.
  */
-interface LlmCallConfig {
+interface LlmCallConfig extends LlmCallControls {
   provider: string;
   model: string;
-  reasoningEffort?: ReasoningEffortId;
-  temperature?: number;
-  maxTokens?: number;
-  stop?: string[];
 }
+/**
+ * Synchronous, pure configuration of one call before defaults and validation.
+ * Compose functions in the desired order; later writes replace earlier ones.
+ * The returned controls cannot change the captured route. Errors reject
+ * preparation before dispatch; only the resolved configuration is recordable.
+ * @param controls - detached, deeply frozen proposed controls, without defaults.
+ * @param model - detached, deeply frozen metadata from the captured adapter generation.
+ * @returns concrete controls; omitted fields receive the route's defaults.
+ */
+type ConfigureCall = (controls: Readonly<LlmCallControls>, model: Readonly<LlmResolvedModelInfo>) => LlmCallControls;
 /**
  * Effective config fields supplied by exact-model adapter resolution rather
  * than by the caller's request proposal.
@@ -1463,6 +1925,8 @@ interface PreparedLlmCall {
   readonly inputModalities?: readonly ModelModality[];
   /** Exact model system prompt update mode captured with the adapter dispatch generation. */
   readonly systemPromptUpdate?: SystemPromptUpdate;
+  /** Exact model tool update mode captured with the adapter dispatch generation. */
+  readonly toolUpdate?: ToolUpdate;
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
   readonly adapterDefaults: LlmCallConfigAdapterDefaults;
   /**
@@ -1510,10 +1974,20 @@ declare abstract class LlmAdapter {
    * @returns route-owned image pricing, or `undefined` when the route declares none.
    */
   imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined;
+  /**
+   * Resolve the image dimensions and byte target this adapter sends to the model.
+   * The default preserves normalized images; adapters that resize must override it.
+   * @param _provider - registered provider route.
+   * @param _model - exact model id.
+   * @param image - normalized image whose request projection is being resolved.
+   * @returns the same target used by request serialization, before provider-internal processing.
+   */
+  imageRequestTarget(_provider: string, _model: string, image: ImageAttachmentRef): ImageRequestTarget;
   /**
    * List models this adapter can currently advertise for one owned provider.
-   * The result is advisory: an adapter may accept unlisted model ids, and
-   * consumers must not turn absence into request rejection.
+   * Core routing accepts unlisted model ids; catalog-driven entry points such
+   * as the GUI may require membership. Adapters used there must advertise
+   * their available models; the base empty catalog offers no GUI selection.
    * @param _provider - one provider route owned by this adapter.
    * @returns discoverable models in adapter-preferred order.
    */
@@ -1690,6 +2164,14 @@ 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 image projection for an exact registered model route.
+   * @param provider - registered provider route.
+   * @param model - exact model id.
+   * @param image - normalized image reference.
+   * @returns dimensions and byte target used by the adapter's request serializer.
+   */
+  imageRequestTarget(provider: string, model: string, image: ImageAttachmentRef): ImageRequestTarget;
   /**
    * Resolve the exact text one durable file occurrence contributes to every
    * provider request in the current execution environment.
@@ -1701,7 +2183,8 @@ declare class LlmRuntime extends TypertRemoteService {
   private detachedModalities;
   /**
    * Discover models advertised by one registered provider. Catalog membership
-   * is advisory and never changes routing or request validation.
+   * does not constrain core routing. Catalog-driven entry points may restrict
+   * selection and submission to the advertised models.
    * @param provider - registered provider route to inspect.
    * @returns detached model metadata in adapter-preferred order.
    */
@@ -1737,11 +2220,15 @@ declare class LlmRuntime extends TypertRemoteService {
    * Resolve one call under its current adapter registration. The returned
    * one-shot handle keeps that registration across header logging and dispatch,
    * so HMR cannot combine one adapter's capability result with another adapter.
-   * @param config - provider/model route and optional request controls.
+   * An optional synchronous callback selects concrete controls using captured
+   * model metadata. Defaults and validation apply to its result. Callback
+   * failures and cancellation reject preparation before dispatch.
+   * @param config - provider/model route and optional concrete request controls.
    * @param signal - optional cancellation for adapter-owned capability lookup.
+   * @param configure - pure control selection, called once before defaults and validation.
    * @returns a prepared config and its registration-bound stream entry point.
    */
-  prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>;
+  prepareCall(config: LlmCallConfig, signal?: AbortSignal, configure?: ConfigureCall): Promise<PreparedLlmCall>;
   private registration;
   /** Remove replay state whose historical route is owned by another adapter. */
   private forAdapter;