@crosery/dsh-viewer 0.0.0-stage → 0.3.0

package/lib/types/convert.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Office and OpenDocument conversion: turn a format no browser renders into
+ * one every browser renders.
+ *
+ * The target is always PDF. A pure front-end path exists (`docx-preview` for
+ * Word, `exceljs` + a grid for Excel) but does not survive this plugin's
+ * constraints: the browser half is a lazy-CJS bundle whose module table answers
+ * only the shell baseline, so every dependency would have to be inlined, and
+ * there is no free PPTX renderer to inline in the first place. One converter
+ * producing one format also means the card has exactly one document code path.
+ *
+ * Conversion costs seconds, so the cache is the real feature. The key covers
+ * the converter version as well as the file identity, because the same bytes
+ * through a newer LibreOffice are a different artifact and a stale hit would be
+ * invisible. The key must also be stable across restarts, or nothing is ever
+ * hit twice and the directory only grows; `cache.ts` bounds it either way.
+ *
+ * Two converters. From 0.1.6-alpha.2 the harness composes its own
+ * `officeToPdf` service with a bundled LibreOffice kit, so a desktop user with
+ * no LibreOffice installed still gets a preview of the six Office formats it
+ * accepts; {@link convertWithOfficeToPdf} drives it. Every other document
+ * format, and every older train, uses a locally installed LibreOffice through
+ * {@link convertDocument}.
+ * @module @crosery/dsh-viewer/convert
+ */
+/** Wall-clock budget for one conversion. A cold LibreOffice start is seconds. */
+export declare const CONVERT_TIMEOUT_MS = 120000;
+/** What a converted document is served as. */
+export declare const CONVERTED_MEDIA_TYPE = "application/pdf";
+/** A resolved converter: its binary and the version string that keys the cache. */
+export interface Converter {
+    binary: string;
+    version: string;
+}
+/**
+ * Locate LibreOffice and read its version, once per process.
+ *
+ * The version is part of the cache key, so it has to come from the binary
+ * rather than be assumed; a machine that upgrades LibreOffice mid-session
+ * simply starts writing artifacts under a new key.
+ * @returns the converter, or `undefined` when no LibreOffice is installed.
+ */
+export declare function resolveConverter(): Promise<Converter | undefined>;
+/** Reset the memoized probe. Test seam; production resolves once per process. */
+export declare function resetConverterProbe(): void;
+/**
+ * Content-addressed artifact name for one source file.
+ *
+ * Keyed on path plus mtime plus size rather than on a digest of the bytes: a
+ * multi-hundred-megabyte presentation should not be read twice just to decide
+ * whether it was already converted, and the triple changes on every edit that
+ * matters.
+ * @param converter - the resolved converter, whose version joins the key.
+ * @param sourcePath - absolute path of the source document.
+ * @param mtimeMs - source modification time.
+ * @param size - source byte length.
+ * @returns the artifact's basename, extension included.
+ */
+export declare function artifactName(converter: Converter, sourcePath: string, mtimeMs: number, size: number): string;
+/**
+ * Convert one document to PDF, or return the cached artifact.
+ * @param sourcePath - absolute path of the source, in the Host's own filesystem.
+ * @param cacheDir - directory owning converted artifacts.
+ * @param signal - cancellation for the whole operation.
+ * @returns the artifact's absolute path.
+ * @throws when no converter is installed, or when LibreOffice produced nothing.
+ */
+export declare function convertDocument(sourcePath: string, cacheDir: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Extensions the harness's own Office converter accepts (`dsh-office-to-pdf`,
+ * shipped with 0.1.6-alpha.2 and later). Everything else a `document` card
+ * shows — RTF and the OpenDocument trio — still goes through LibreOffice.
+ */
+export declare const OFFICE_EXTENSIONS: readonly ["doc", "docx", "xls", "xlsx", "ppt", "pptx"];
+/** One extension {@link OfficeToPdfLike.convert} accepts. */
+export type OfficeExtension = typeof OFFICE_EXTENSIONS[number];
+/**
+ * The slice of the harness `officeToPdf` service this plugin calls, declared
+ * structurally.
+ *
+ * Not imported, not even as a type: `@deepseek-ai/dsh-office-to-pdf` does not
+ * exist on the trains before 0.1.6, so naming it would fail the typecheck of
+ * every older train this plugin still supports, and a value import would fail
+ * the whole entry at ESM link time there. The service is read by name through
+ * `ctx.get` and narrowed with {@link officeToPdfOf}.
+ */
+export interface OfficeToPdfLike {
+    /**
+     * The provider's resolved configuration — fonts, fallbacks, image
+     * resolution, limits. Read only to key the cache: see {@link officeConverterIdentity}.
+     */
+    readonly config?: unknown;
+    /**
+     * Convert Office bytes. The provider owns queueing, the bundled engine and
+     * its own content cache; the caller owns authorization and the source read.
+     */
+    convert(request: {
+        readonly extension: OfficeExtension;
+        readonly priority: 'foreground' | 'background';
+        readonly source: {
+            readonly key: string;
+            readonly version: string;
+            readonly bytes?: number;
+            read(signal: AbortSignal, maxBytes: number): Promise<{
+                readonly bytes: Uint8Array;
+                readonly version: string;
+            }>;
+        };
+    }, signal?: AbortSignal): Promise<{
+        readonly pdf: Uint8Array;
+    }>;
+}
+/**
+ * Narrow an optional service value to {@link OfficeToPdfLike}.
+ * @param service - whatever `ctx.get('officeToPdf')` returned.
+ * @returns the converter, or `undefined` when this train composes none.
+ */
+export declare function officeToPdfOf(service: unknown): OfficeToPdfLike | undefined;
+/**
+ * The extension `officeToPdf` would accept for this path, if any.
+ * @param sourcePath - the document's path.
+ * @returns the bare lowercased extension, or `undefined` for a LibreOffice-only format.
+ */
+export declare function officeExtensionOf(sourcePath: string): OfficeExtension | undefined;
+/** The source one {@link convertWithOfficeToPdf} call converts. */
+export interface OfficeSource {
+    /** The Host's own path of the document; keys the artifact and the provider's dedup. */
+    path: string;
+    /** The filesystem freshness token observed when the call resolved the file. */
+    version: string;
+    /** Byte size, when the backend reported one. */
+    bytes?: number;
+    /**
+     * Read the document's bytes, bounded by the provider's reservation.
+     * @param signal - the provider's conversion lifetime.
+     * @param maxBytes - the capacity the provider reserved for this source.
+     */
+    read(signal: AbortSignal, maxBytes: number): Promise<Uint8Array>;
+}
+/**
+ * A stable identity for the bundled converter, for the artifact key.
+ *
+ * Not the provider's `generation`: that is `randomUUID()` per provider
+ * instance, so keying on it made every restart a cold cache — the cache was
+ * never hit across restarts and only grew. The provider replaces its
+ * generation when its configuration is replaced, so the configuration itself
+ * is the stable half of the same idea: different fonts or rendering settings
+ * are a different artifact, a restart is not. What it cannot see is a harness
+ * upgrade that ships a new engine under an unchanged configuration; such an
+ * artifact is still a faithful render of unchanged bytes, and it ages out of
+ * the cache like any other.
+ * @param converter - the harness `officeToPdf` service.
+ * @returns a string that changes exactly when the provider's configuration does.
+ */
+export declare function officeConverterIdentity(converter: OfficeToPdfLike): string;
+/**
+ * Artifact name for one conversion through the bundled converter.
+ *
+ * Keyed on the converter's identity as well as on the source identity, for the
+ * same reason the LibreOffice key carries the LibreOffice version: the same
+ * bytes through different fonts or rendering settings are a different PDF.
+ * @param identity - {@link officeConverterIdentity} of the provider.
+ * @param source - the converted document.
+ * @returns the artifact's basename, extension included.
+ */
+export declare function officeArtifactName(identity: string, source: Pick<OfficeSource, 'path' | 'version' | 'bytes'>): string;
+/**
+ * Convert one Office document through the harness's bundled converter, or
+ * return the cached artifact.
+ *
+ * The provider hands the PDF back as bytes, but the asset route serves files:
+ * the bytes are written into this plugin's own cache and signed there, like a
+ * LibreOffice artifact, through {@link placeArtifact}.
+ * @param converter - the harness `officeToPdf` service.
+ * @param source - the document and its bounded reader.
+ * @param cacheDir - directory owning converted artifacts.
+ * @param signal - cancellation for the whole operation.
+ * @returns the artifact's absolute path.
+ * @throws when the format is not one the provider accepts, or the provider refuses or fails.
+ */
+export declare function convertWithOfficeToPdf(converter: OfficeToPdfLike, source: OfficeSource, cacheDir: string, signal?: AbortSignal): Promise<string>;

package/lib/types/display-file.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The `display_file` tool: put a file on the user's screen.
+ *
+ * The difference from the shipped `read_image` is one deliberate inversion.
+ * `read_image` exists to put an image into MODEL context, so it refuses outright
+ * on a route that declares no image input, and it handles images only. This tool
+ * exists to put a file on the SCREEN, so a text-only route is a normal outcome
+ * rather than a refusal, and every medium a browser can play is in scope —
+ * video, audio, PDF and HTML have no representation in model context at all and
+ * would otherwise be undisplayable.
+ *
+ * That is why the durable facts ride `output.presentationMeta`. An image block
+ * is model-facing and exists only for four raster types on one kind of route;
+ * the meta is UI-facing, persists with `tool/result`, and therefore rebuilds
+ * the card when the session is reopened.
+ * @module @crosery/dsh-viewer/display-file
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import { type DisplayValue, type ModelImage } from './contract.ts';
+/** Live settings and key material {@link applyDisplayTool} reads per call. */
+export interface DisplayToolOptions {
+    /** Whether an image-capable route may also receive the image itself. */
+    feedModel: () => boolean;
+    /** The harness asset MAC key, or `undefined` while it is still loading. */
+    secret: () => Buffer | undefined;
+    /** Directory owning converted document artifacts. */
+    cacheDir: string;
+}
+/**
+ * Whether the call's routed model accepts image input.
+ *
+ * Resolution mirrors the shipped `read_image` gate — request-header config
+ * first, then the agent's own options — but the outcome is a boolean, not a
+ * refusal: an unresolvable route simply means "not image-capable", which
+ * degrades to a screen-only display instead of failing a call that would
+ * otherwise have worked.
+ * @param ctx - the plugin context used to reach the optional `llm` service.
+ * @param exec - the execution whose calling agent names the route.
+ * @returns whether an image block may be emitted for this call.
+ */
+export declare function routeAcceptsImages(ctx: Context, exec: ToolExecution): Promise<boolean>;
+/**
+ * Project a durable attachment reference into the plugin's wire shape.
+ * @param ref - the reference the attachment service published.
+ * @returns the card-facing image facts.
+ */
+export declare function modelImageOf(ref: ImageAttachmentRef): ModelImage;
+/**
+ * Re-brand the plugin's wire shape back into an attachment reference.
+ * @param image - the canonical image facts.
+ * @returns the branded reference an `ImageBlock` carries.
+ */
+export declare function attachmentRefOf(image: ModelImage): ImageAttachmentRef;
+/**
+ * Format the model-facing envelope. Pure, and — for every medium except an
+ * in-context raster — the only thing the model receives, so it states plainly
+ * what is on the user's screen and that the model itself cannot see it.
+ * @param value - the canonical outcome.
+ * @returns the envelope body.
+ */
+export declare function formatDisplayOutput(value: DisplayValue): string;
+/**
+ * Register `display_file` into the given context.
+ *
+ * The composing plugin owns the service gates: `src/index.ts` calls this inside
+ * the `fs` injection, and execution treats `attachments` as optional so a
+ * deployment with no durable store still displays every medium — it just cannot
+ * put a raster into model context.
+ * @param ctx - the registration scope; execution uses its `fs` service plus the
+ *   optional `attachments`/`llm` services.
+ * @param options - live settings reads and the asset MAC key.
+ * @returns the disposer that unregisters the tool, so a settings change can
+ *   remove it from the model's schema list rather than leave it there refusing.
+ */
+export declare function applyDisplayTool(ctx: Context, options: DisplayToolOptions): () => void;

package/lib/types/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Host half of the viewer plugin: a `display_file` tool the model calls to put
+ * a file on the user's screen, and the signed HTTP route that carries the bytes.
+ *
+ * Why a route at all, when the harness already has a durable attachment service:
+ * that service is images-only, by design (`saveImage`, `readImage`,
+ * `ImageAttachmentLimits.mediaTypes`). Video, audio, PDF and HTML have no
+ * representation in it and no representation in model context either, so the
+ * only way to get them in front of the user is to serve their bytes to the page.
+ * Serving them by signed reference — rather than by a path the browser supplies
+ * — is what keeps that route from being an arbitrary-file-read endpoint.
+ *
+ * The two paths are complementary, not redundant: an admissible raster on a
+ * vision route still goes through the attachment store, because that is the only
+ * way it also reaches the model.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ViewerSettings } from './contract.ts';
+export { ASSET_ROUTE, DISPLAY_TOOL, VIEWER_SETTINGS_NAMESPACE, classifyPath, extensionOf, formatBytes, isOpaqueMediaPath, modelImageMediaTypeForPath, } from './contract.ts';
+export type { DisplayValue, ModelImage, ViewerKind, ViewerSettings } from './contract.ts';
+export { ViewerSettingsSchema } from './settings.ts';
+export { assetUrlFor, verifyAssetRequest } from './asset-token.ts';
+export { guardHeaders, parseRange } from './asset-route.ts';
+export { artifactName, convertDocument, resolveConverter } from './convert.ts';
+export { isMisdirectedRead, mediaReadValue, readPathOf } from './read-redirect.ts';
+export { applySupersedeReadImage } from './supersede-read-image.ts';
+/**
+ * Settings namespace this plugin owns, as the settings service keys it.
+ *
+ * Plain string rather than a branded one since 0.1.2 removed the `settingsNamespace`
+ * constructor that produced the brand. Consumers hand it to `ctx.settings`, which
+ * validates it at registration either way.
+ */
+export declare const VIEWER_NAMESPACE = "crosery-viewer";
+export declare const name = "@crosery/dsh-viewer";
+/**
+ * Required services — deliberately the smallest set that lets the tool exist.
+ *
+ * `webServer` is NOT here even though the asset route is the transport for
+ * every non-raster medium. An entry that never activates is a hard boot failure
+ * (`dsh: 1 entry did not activate`), not a graceful skip, so requiring it would
+ * make this bundle un-composable with `dsh-headless` or `acp` rather than
+ * merely inert there. It is injected as a nested scope below instead.
+ *
+ * `attachments` and `llm` are likewise optional and read through `ctx.get`: a
+ * deployment without a durable store still displays everything it can reach —
+ * it just cannot put an image into model context.
+ */
+export declare const inject: string[];
+export type Config = ViewerSettings;
+export declare const Config: import("@deepseek-ai/schemastery").default<ViewerSettings>;
+/** Callbacks a mount invokes. Identical on every harness train that has a mount. */
+export interface SettingsHooks {
+    /** Receive the authoritative value: the resolved section while one is attached. */
+    setSource(current: () => ViewerSettings): void;
+    /** Re-judge derived state after an attach, a detach, or a committed change. */
+    onChange(): void;
+}
+/**
+ * Mount the `crosery-viewer` namespace over whichever settings API exists.
+ *
+ * Only called while a settings service is present: a composition without one
+ * keeps the composition entry as the sole source, which `reconcile()` in
+ * {@link apply} establishes on its own.
+ *
+ * @param ctx - plugin context: the mount's owner, and the injection parent.
+ * @param config - composition entry config; both the `base` layer and the
+ *   fallback value once the settings service detaches.
+ * @param hooks - source and change callbacks.
+ */
+export declare function mountSettingsSection(ctx: Context, config: ViewerSettings, hooks: SettingsHooks): void;
+/**
+ * Mount the settings section, the asset route, the tool, and the read redirect.
+ * @param ctx - plugin context.
+ * @param config - composition entry config, used as the settings `base` layer.
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/read-redirect.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Keeping `read` off opaque media — without turning it into a failure.
+ *
+ * The shipped `read` is a UTF-8 decode. Pointed at a PNG or an MP4 it does not
+ * fail: it returns thousands of replacement characters, which the model then
+ * tries to interpret. That is worse than an error, because the model has no
+ * signal that it read nothing.
+ *
+ * Worse still, the shipped filesystem provider does not even get that far: it
+ * samples the head of the file and throws `FS_NOT_TEXT` (`cannot read "…":
+ * binary file`) on a NUL byte. So a `read` aimed at a PNG paints a RED FAILURE
+ * ROW into the transcript with or without this plugin — for a file that exists,
+ * is perfectly readable, and is one tool call away from being on screen.
+ *
+ * Neither obvious correction removes that row. A `tools/pre-execute` denial
+ * materializes its own `isError`. A `tools/post-execute` decision cannot help
+ * either: replacing a value is explicitly refused on a failed result, and
+ * replacing content leaves `isError` set.
+ *
+ * The correction therefore runs in `tools/execute`, the around-dispatch
+ * waterfall, and does NOT delegate — `next()` is never called, so the doomed
+ * read performs no filesystem I/O at all. The authored result is what makes
+ * this work: the registry feeds a wrapper's returned result through
+ * `normalizeDispatchResult`, which for a success re-runs the owning tool's
+ * `output.render` AND its `output.presentationMeta` over the authored value.
+ * Replacing the value therefore replaces the persisted read metadata too, so
+ * the shipped read card — which rebuilds itself from that metadata — renders
+ * this plugin's one-line pointer as an ordinary SUCCESSFUL read.
+ * @module @crosery/dsh-viewer/read-redirect
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * The replacement `read` value for one misdirected call.
+ *
+ * Shaped to the shipped `read` tool's own output schema — `path`, `offset`,
+ * `lines`, `totalLines` — because the registry validates the replacement
+ * against that schema before projecting it. One line of explanation reads
+ * correctly in every surface the value reaches: as the model's tool output, as
+ * the read card's single content line, and in a replayed session.
+ * @param filePath - the path the model asked to read.
+ * @returns the canonical value to substitute.
+ */
+export declare function mediaReadValue(filePath: string): {
+    path: string;
+    offset: number;
+    lines: {
+        number: number;
+        text: string;
+    }[];
+    totalLines: number;
+};
+/**
+ * Read the `file_path` argument out of one `read` call.
+ *
+ * The arguments arrive as losslessly parsed JSON of whatever the model emitted,
+ * so nothing about their shape is guaranteed; anything that is not a non-empty
+ * string path is left for the tool's own validation to reject.
+ * @param args - the parsed call arguments.
+ * @returns the path, or `undefined` when the call names none.
+ */
+export declare function readPathOf(args: unknown): string | undefined;
+/**
+ * Whether one pending call is a text read aimed at opaque media.
+ * @param name - the wire tool name.
+ * @param args - the parsed call arguments.
+ * @returns true when the dispatch should be replaced with the display pointer.
+ */
+export declare function isMisdirectedRead(name: string, args: unknown): boolean;
+/** Wire name of the harness's own deliverable tool (`dsh-tool-present`, 0.1.7). */
+export declare const PRESENT_TOOL = "present";
+/**
+ * Where the display guidance goes: directly after the shipped read guidance.
+ *
+ * Up to 0.1.1 tool guidance sat at 100–199 with `tool:read` at 100. From 0.1.2
+ * orders are allocated centrally (`TOOL_READ` is 1100) behind
+ * `getSectionOrder`; a hard-coded 101 there would put this section ahead of
+ * every tool's guidance instead of beside the read tool's.
+ * @param registry - the `systemPrompt` service.
+ * @returns the order to register at.
+ */
+export declare function displaySectionOrder(registry: unknown): number;
+/**
+ * The guidance one prompt assembly receives.
+ *
+ * Empty whenever the scope cannot call `display_file` — the tool switched off
+ * in settings, or restricted away for this agent — so the model is never told
+ * about a tool it does not have. Where the harness also offers `present`, the
+ * three ways of putting a file in front of the user are divided explicitly:
+ * without that, a model reading both this section and the harness's own
+ * deliverable guidance tends to display, embed and present the same file.
+ *
+ * The redirect is described only while it is on: with `redirectRead` off, a
+ * `read` of a binary file fails or returns undecodable text, and a prompt that
+ * promised a pointer back would be the model's only, wrong, expectation.
+ * @param visible - whether a tool is visible in the assembling scope.
+ * @param redirecting - whether `read` on binary media is currently redirected.
+ * @returns the section text, or `''`.
+ */
+export declare function displaySectionText(visible: (tool: string) => boolean, redirecting: boolean): string;
+/**
+ * Install the correction and the prompt section that makes it unnecessary.
+ *
+ * The section is the primary mechanism — a model told about `display_file` up
+ * front rarely reaches the correction — and the correction is the backstop for
+ * the calls that get there anyway.
+ * @param ctx - the plugin context; both registrations are effects on it.
+ * @param enabled - live read of the `redirectRead` setting.
+ */
+export declare function applyReadRedirect(ctx: Context, enabled: () => boolean): void;

package/lib/types/read-target.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Path resolution shared by the display tool and the read-redirect policy.
+ *
+ * `dsh-tool-fs` keeps its own `read-target`/`session-cwd` modules private (its
+ * package entry exports only `apply`/`Config`), so the session-cwd rule is
+ * restated here rather than imported. Keeping it byte-for-byte compatible
+ * matters: a path this plugin resolved differently from `read` would display a
+ * different file than the one the model believes it named.
+ * @module @crosery/dsh-viewer/read-target
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsInfo, FsTarget } from '@deepseek-ai/dsh-fs';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/**
+ * The session workspace cwd for this call, or `undefined` when none applies.
+ *
+ * Non-agent callers get `undefined` on purpose: the fallback belongs to the
+ * filesystem provider, not to a tool reading `process.cwd()` at its boundary.
+ * @param exec - the tool execution; only its optional `agent` is read.
+ * @param requestedPath - the path about to be resolved; parent traversal makes a
+ *   symlinked cwd's filesystem identity observable, so the cwd is canonicalized
+ *   in exactly that case.
+ * @returns the calling agent's session cwd, or `undefined`.
+ */
+export declare function sessionCwd(exec: ToolExecution, requestedPath: string): string | undefined;
+/**
+ * Resolve a model-supplied path, observe absence, and require a regular file.
+ * @param ctx - the plugin context supplying `fs` and the observation event.
+ * @param exec - the current execution, for session cwd and cancellation.
+ * @param requestedPath - the raw path the model supplied.
+ * @returns the resolved target and its single stat result.
+ * @throws {FsError} when the path is absent or is not a regular file.
+ */
+export declare function resolveDisplayTarget(ctx: Context, exec: ToolExecution, requestedPath: string): Promise<{
+    target: FsTarget;
+    info: FsInfo;
+}>;

package/lib/types/settings.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Host-side settings schema over the shared contract. Only the Node half
+ * imports this module, so the validator never reaches the browser bundle.
+ */
+import z from '@deepseek-ai/schemastery';
+import { type ViewerSettings } from './contract.ts';
+/**
+ * Durable schema for the viewer's settings: the `crosery-viewer` section up to
+ * 0.1.6, and the plugin entry's own Config (entry id `viewer`) from 0.1.7.
+ *
+ * Every field defaults to the behavior the plugin exists to provide, so an
+ * empty composition row is the intended configuration and each flag is a way to
+ * give one piece back.
+ *
+ * The descriptions document each field wherever the schema is projected — on
+ * 0.1.7, the JSON Schema `dsh --dump-config-schema` prints for profile entries.
+ * They do not make a settings form: 0.1.7's Settings page builds forms only
+ * from volatile fields, and none of these is. They are English only:
+ * schemastery can carry a locale dictionary, but no first-party Config uses one
+ * and nothing guarantees every consumer resolves it, so a dictionary risks
+ * rendering as an unreadable object where a string always reads.
+ */
+export declare const ViewerSettingsSchema: z<ViewerSettings>;

package/lib/types/supersede-read-image.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Making `display_file` the single image entry point.
+ *
+ * `read_image` and `display_file` overlap on exactly one thing — putting a
+ * raster into model context — and a model presented with both will reasonably
+ * use both: `read_image` "to look at it", then `display_file` "to show it to
+ * the user". Observed in a real session on a 1672x941 PNG: the same 2.2 MB
+ * image was ingested TWICE in one turn, and the transcript showed two
+ * identical-looking cards. No prompt fixes this reliably, because both tools
+ * genuinely do what the model thinks they do.
+ *
+ * So one of them stops being visible. `display_file` is the strict superset: it
+ * handles every medium, works on text-only routes (where `read_image` refuses
+ * outright), and still feeds an admissible raster into context on a vision
+ * route. Hiding it is therefore a pure removal of duplication, not of ability.
+ *
+ * The mechanism is forced by the registry: `tools.restrict()` refuses a
+ * context-global call outright ("a context-global restriction would mask every
+ * agent"), so the restriction is applied per agent, on `agent.ctx`.
+ * @module @crosery/dsh-viewer/supersede-read-image
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Hide `read_image` from every agent while this plugin owns image display.
+ *
+ * Two triggers, because one is not enough. `agent/created` covers agents made
+ * after the tool exists; `tools/change` covers the race in the other order —
+ * `read_image` is registered behind an async service injection, so an agent
+ * created first would otherwise keep seeing it for its whole life. Agents that
+ * already carry the restriction are skipped, so the retry is idempotent.
+ * @param ctx - the plugin context; both listeners are effects on it.
+ * @param enabled - live read of the `supersedeReadImage` setting.
+ */
+export declare function applySupersedeReadImage(ctx: Context, enabled: () => boolean): void;