@qilin-agent/client-ui-deliverables 0.0.0-stage → 3.1.3

package/lib/types/client/host-read-store.d.ts

@@ -0,0 +1,42 @@
+/** What one store makes of its reads. */
+export interface HostReadPolicy<T> {
+    /** The state published while a request runs. */
+    loading: T;
+    /** The state a transport failure publishes. */
+    failed: T;
+    /**
+     * Whether a later request replaces a standing state with a new read.
+     * @param state - the standing state.
+     * @returns true to read again.
+     */
+    retryable(state: T): boolean;
+    /**
+     * Turn a settled response into a state.
+     * @param response - the Host's answer.
+     * @returns the state to publish.
+     */
+    decode(response: Response): Promise<T>;
+}
+/** One browser plugin's reads of one record kind. */
+export declare class HostReadStore<T> {
+    private readonly policy;
+    /** Record URLs key the state across Sessions and turns. */
+    readonly state: import("@qilin-agent/client-store").SnapshotStore<Record<string, T | undefined>>;
+    private readonly lifetime;
+    /** The connection generation the current states belong to; a reset aborts it so no older read publishes. */
+    private generation;
+    private readonly pending;
+    constructor(policy: HostReadPolicy<T>);
+    /**
+     * Read one URL unless a state the policy keeps already stands for it.
+     * @param url - the record's authenticated URL.
+     * @returns after the state is published.
+     */
+    protected loadUrl(url: string): Promise<void>;
+    /** Forget every state and abandon in-flight reads; a replaced connection may reach a Host that no longer serves them. */
+    reset(): void;
+    /** Cancel outstanding reads and wait until none can publish state. */
+    dispose(): Promise<void>;
+    private read;
+}
+//# sourceMappingURL=host-read-store.d.ts.map

package/lib/types/client/icons.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Package-local glyph for the changed-files card until the shared icon set
+ * carries it; its props already match the shared icon contract.
+ */
+import type { IconProps } from '@qilin-agent/client-ui-primitives';
+/** Angle brackets, the code mark the card's header tile shows. */
+export declare const IconCodeBracketsOutline16: ({ size, className }: IconProps) => import("react").JSX.Element;
+//# sourceMappingURL=icons.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Deliverables plugin, browser half: registers the changed-files card and
+ * delivery cards into the chat view's turn-tail list, the `changes-review`
+ * right-Sidebar tab type that reviews one turn's changed files one comparison
+ * at a time, and provides the `chatFileMentions` service that links
+ * inline-code mentions of produced or delivered files in the closing prose.
+ * All policy lives here — the supported mutation calls, mention matching, row
+ * cap, and copy — so composing this plugin out of cordis.yml removes every
+ * surface; the owning view renders an empty list and inert prose at zero cost.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import { type DeliverablesKey } from './locales.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Changed-files card, review tab, delivery card, and file-mention copy. */
+        'deliverables': DeliverablesKey;
+    }
+}
+/** Required services for the tail-slot and tab-type registrations and their dictionaries. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the dictionaries, the turn-tail entry, and the comparison tab type.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,79 @@
+/** `deliverables` namespace dictionaries: cards, comparison tab, and file-mention copy. */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "deliverables";
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'presented.nativeUnavailable': string;
+    'presented.revealError': string;
+    'presented.directoryError': string;
+    'presented.directoryOpening': string;
+    'presented.directoryOpened': string;
+    'presented.revealed': string;
+    'presented.revealing': string;
+    'presented.unavailable': string;
+    'presented.retry': string;
+    'presented.hostError': string;
+    'presented.directory': string;
+    'presented.explorer': string;
+    'presented.finder': string;
+    'presented.defaultApp': string;
+    'presented.more': string;
+    'presented.action': string;
+    'presented.preview': string;
+    'presented.previewButton': string;
+    'presented.previewCard': string;
+    'presented.all': string;
+    'presented.expandAria': string;
+    'presented.collapse': string;
+    'presented.collapseAria': string;
+    'presented.opening': string;
+    'presented.opened': string;
+    'presented.error': string;
+    'presented.file': string;
+    'row.title': string;
+    'row.running': string;
+    'row.preparing': string;
+    'row.ok': string;
+    'row.error': string;
+    'row.stopped': string;
+    'row.inspect': string;
+    'changes.title': string;
+    'changes.added': string;
+    'changes.deleted': string;
+    'changes.binary': string;
+    'changes.openReview': string;
+    'changes.all': string;
+    'changes.expandAria': string;
+    'changes.collapse': string;
+    'changes.collapseAria': string;
+    'changes.oversized': string;
+    'changes.viewDiff': string;
+    'review.title': string;
+    'review.selectFile': string;
+    'review.split': string;
+    'review.unified': string;
+    'review.splitAria': string;
+    'review.wrap': string;
+    'review.nowrap': string;
+    'review.wrapAria': string;
+    'review.openFile': string;
+    'review.openFileAria': string;
+    'diff.openNativeAria': string;
+    'diff.loading': string;
+    'diff.missing': string;
+    'diff.error': string;
+    'diff.binary': string;
+    'diff.oversized': string;
+    'diff.created': string;
+    'diff.deleted': string;
+    'diff.unchanged': string;
+    'diff.coarse': string;
+    'diff.truncated': string;
+    'diff.openNative': string;
+    'diff.openNativeError': string;
+};
+/** English dictionary (same key set). */
+export declare const en: Record<DeliverablesKey, string>;
+/** Union of this namespace's dictionary keys. */
+export type DeliverablesKey = keyof typeof zh;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/present-open.d.ts

@@ -0,0 +1,46 @@
+import type { SessionId } from '@qilin-agent/session/types';
+import { type PresentedAction, type PresentedHost } from '../presented.ts';
+/** State of the latest explicit open gesture for one saved file. */
+export type PresentedOpenPhase = 'opening' | 'opened' | 'revealing' | 'revealed' | 'error' | 'revealError' | 'nativeUnavailable';
+/** One browser plugin's file-open requests, cancelled when that plugin is disposed. */
+export declare class PresentedOpenController {
+    /** File action URLs key the state across Sessions, turns, and both clickable surfaces. */
+    readonly state: import("@qilin-agent/client-store").SnapshotStore<Record<string, PresentedOpenPhase | undefined>>;
+    /** Native destination metadata, or a retryable read failure. */
+    readonly host: import("@qilin-agent/client-store").SnapshotStore<PresentedHost | "error" | null>;
+    private loading;
+    private metadata;
+    private readonly lifetime;
+    private readonly pending;
+    /**
+     * Open a declared file once while a request for the same coordinates is pending.
+     * Failures remain visible on the card and a later gesture retries them.
+     * @param sessionId - viewed Session, including a fork's own identity.
+     * @param seq - durable delivery event sequence.
+     * @param index - original file index within that event.
+     * @param action - default application open or file-manager reveal.
+     * @returns after the Host acknowledges opening or the error state is published.
+     */
+    open(sessionId: SessionId, seq: number, index: number, action?: PresentedAction): Promise<void>;
+    /**
+     * Open one recorded changed file in the Host's default application.
+     * @param sessionId - viewed Session.
+     * @param seq - durable workspace/changes event sequence.
+     * @param index - original file index within that event.
+     * @returns after the Host acknowledges opening or the error state is published.
+     */
+    openChanged(sessionId: SessionId, seq: number, index: number): Promise<void>;
+    private openUrl;
+    /**
+     * Read the serving desktop metadata, coalescing concurrent reads; a later call retries failure.
+     * @returns after metadata or a retryable error is published.
+     */
+    loadHost(): Promise<void>;
+    /** Invalidate desktop metadata on connection replacement; mounted cards request the new Host. */
+    resetHost(): void;
+    private readHost;
+    /** Cancel outstanding requests and wait until no request can publish state. */
+    dispose(): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=present-open.d.ts.map

package/lib/types/client/review-definition.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What the `changes-review` tab type IS: the right-Sidebar review of one
+ * turn's changed files, showing one file's turn-start and turn-end
+ * comparison at a time. It claims the `qilin-resource://changes-review/session/…`
+ * addresses the changed-files card mints; the Session and the event sequence
+ * in the address identify the content, and the turn they carry names the tab.
+ * A row opens the tab with the file's index as its navigation parameter.
+ */
+import type { SidebarRightTabDefinition } from '@qilin-agent/client-ui-sidebar-right/client';
+import type { TranslateNS } from '@qilin-agent/client-locale/client';
+import type { NS } from './locales.ts';
+/** The tab kind this package owns. */
+export declare const CHANGES_REVIEW_KIND = "changes-review";
+/** This implementation's identity in the tab system, and the key its body registers under. */
+export declare const CHANGES_REVIEW_ID = "@qilin-agent/client-ui-deliverables";
+/** The file a review opens on. */
+export interface ChangesReviewParams {
+    /** Original index in the summary's files array. */
+    index?: number;
+}
+declare module '@qilin-agent/client-ui-sidebar-right/client' {
+    interface SidebarRightResourceParamsMap {
+        /** The file a review tab opens on. */
+        'changes-review': ChangesReviewParams;
+    }
+}
+/**
+ * The review type's registry definition.
+ * @param t - namespace-bound translate, read fresh on every title call.
+ * @returns the definition to register.
+ */
+export declare function changesReviewDefinition(t: TranslateNS<typeof NS>): SidebarRightTabDefinition;
+//# sourceMappingURL=review-definition.d.ts.map

package/lib/types/client/review-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The review tab's view state: which listed file is shown, whether hunks are
+ * drawn side by side, and whether long lines wrap. One bucket per tab, so two
+ * reviews in one session keep their own choices; the bucket ends with the
+ * tab record's signal.
+ */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+/** One review tab's choices. */
+export interface ReviewTabState {
+    /** Original index of the shown file in the summary's files array. */
+    index: number;
+    /** Whether deletions and additions are drawn in two columns. */
+    split: boolean;
+    /** Whether long lines wrap instead of scrolling. */
+    wrap: boolean;
+    /** The navigation revision whose file index was last applied. */
+    navigated: number;
+}
+/** Every review tab's choices, keyed by tab id. */
+export interface ReviewState {
+    byTab: Record<TabId, ReviewTabState>;
+}
+/** The review store's write set; every action names the tab it writes. */
+type ReviewActions = {
+    navigated: (draft: ReviewState, tabId: TabId, revision: number, index: number) => void;
+    selected: (draft: ReviewState, tabId: TabId, index: number) => void;
+    toggledSplit: (draft: ReviewState, tabId: TabId) => void;
+    toggledWrap: (draft: ReviewState, tabId: TabId) => void;
+    forget: (draft: ReviewState, tabId: TabId) => void;
+};
+/**
+ * Declare the review tab's store; the registration declares it as an
+ * exclusive store, so the framework mints one instance per session.
+ * @returns the store handle to declare on the registration.
+ */
+export declare function createReviewStore(): EngineStoreHandle<ReviewState, ReviewActions>;
+export {};
+//# sourceMappingURL=review-store.d.ts.map

package/lib/types/client/turn-deliverables.d.ts

@@ -0,0 +1,84 @@
+import type { TurnTailOwnerProps } from '@qilin-agent/client-ui-chat/client';
+import type { ConversationNodeDefinition } from '@qilin-agent/client-ui-conversation/client';
+import type { MarkdownFileMentions } from '@qilin-agent/client-ui-primitives';
+import type { PresentedFile } from '@qilin-agent/tool-present/types';
+/** A declared file with its authorized open coordinates. */
+export interface PresentedPath extends PresentedFile {
+    readonly seq: number;
+    readonly index: number;
+}
+interface ProducedPath {
+    readonly seq: number;
+    readonly path: string;
+}
+/** The latest `workspace/changes` announcement of one Turn; the Host serves its summary by this sequence. */
+export interface ChangesTurnData {
+    readonly seq: number;
+}
+/** Immutable produced-file facts published against one Turn. */
+export interface DeliverablesTurnData {
+    readonly produced: readonly ProducedPath[];
+    readonly presented?: readonly PresentedPath[];
+    readonly changes?: ChangesTurnData;
+}
+declare module '@qilin-agent/client-ui-conversation/client' {
+    interface ConversationTurnDataMap {
+        /** Successful mutation paths, recorded changed files, and deliveries accumulated in this Turn. */
+        deliverables: DeliverablesTurnData;
+    }
+}
+interface DeliverablesState extends DeliverablesTurnData {
+    readonly turn: number;
+    readonly calls: ReadonlyMap<string, string | null>;
+}
+/**
+ * Files produced by one Turn data value.
+ *
+ * The source is the arguments of successful `write`, `edit`, and mutating
+ * `str_replace_editor` calls, not the closing prose: a produced file must be
+ * listed whether or not the model remembered to name it. Reads, unsupported
+ * tools, malformed calls, and failed results contribute nothing. Paths keep
+ * first-seen order and appear once, so a file written and then edited in the
+ * same turn is one entry.
+ *
+ * The Conversation Location index owns turn membership before this function
+ * runs, so paths cannot spill across turns and this derivation does not infer
+ * boundaries from neighboring presentation Nodes.
+ * @param data - engine-published Deliverables data for one Turn.
+ * @param seq - closing Assistant seq; later Tool settlements are excluded.
+ * @returns Produced paths in first-seen order; empty when the turn wrote nothing.
+ */
+export declare function producedForClosing(data: Readonly<DeliverablesTurnData> | undefined, seq?: number): readonly string[];
+/**
+ * Claim the turn-tail chain only when its closing turn produced files.
+ * @param owner - Turn-tail owner currency for the closing assistant.
+ * @returns Produced paths as the component's match, or null to decline before mount.
+ */
+export declare function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[] | null;
+/** Turn-local successful mutation accumulator; it publishes no view Node. */
+export declare const deliverablesDefinition: ConversationNodeDefinition<DeliverablesState>;
+/**
+ * The turn's latest change announcement.
+ * @param owner - closing turn.
+ * @returns the announcement, or null when the Host recorded none.
+ */
+export declare function changesForClosing(owner: TurnTailOwnerProps): ChangesTurnData | null;
+/**
+ * Select the latest declaration of each path before the closing reply.
+ * @param owner - closing turn and sequence.
+ * @returns replayable deliveries in first-seen path order.
+ */
+export declare function presentedForClosing(owner: TurnTailOwnerProps): PresentedPath[];
+export { basename } from '../presented.ts';
+/**
+ * Resolves inline-code references against one turn's produced or delivered
+ * paths. Exact paths resolve directly; a basename resolves only when exactly
+ * one supplied path has that basename. Ambiguous and unknown tokens stay inert.
+ * @param paths - The turn's produced or delivered paths, already deduplicated.
+ * @param openFile - The chat view's file opener.
+ * @param label - Localizes the accessible open-label for a resolved path.
+ * @returns The resolver MarkdownText consumes; the full path rides `title`,
+ * the same disambiguator the row's chips carry.
+ */
+export declare function producedFileMentions(paths: readonly string[], openFile: (path: string) => void, label: (path: string) => string): MarkdownFileMentions;
+//# sourceMappingURL=turn-deliverables.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deliverables plugin, node half. Registers Web file-reference guidance and
+ * serves authenticated native opens of declared files. The browser
+ * half ships via exports["./client"], discovered through the package.json
+ * qilin.client declaration.
+ */
+import type { Context } from '@qilin-agent/kylin';
+/** Services required for file-reference guidance, change summaries, and authenticated native opens. */
+export declare const inject: string[];
+/**
+ * Register Web file-reference guidance and native opens for declared files.
+ * @param ctx - host context carrying the system-prompt registry.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/present-open.d.ts

@@ -0,0 +1,10 @@
+/** Serve change summaries and comparisons, and open declared or changed workspace files verified by the viewed Session's filesystem. */
+import type { Context } from '@qilin-agent/kylin';
+/**
+ * Register the deliverables routes inside Connection's authentication fence:
+ * desktop metadata, change summaries and comparisons, declared-file actions,
+ * and changed-file opening.
+ * @param ctx - Session lookup, change summaries, native opener, and route lifetime.
+ */
+export declare function registerPresentOpen(ctx: Context): void;
+//# sourceMappingURL=present-open.d.ts.map

package/lib/types/presented.d.ts

@@ -0,0 +1,60 @@
+/** Validate declared workspace paths and address their native-open actions. */
+import type { PresentedFile } from '@qilin-agent/tool-present/types';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { ToolCallId } from '@qilin-agent/llm/brand';
+/** Authenticated POST route for opening a workspace file on the Host desktop. */
+export declare const PRESENT_OPEN_PATH = "/api/present.open";
+/** Authenticated desktop availability and destination metadata. */
+export declare const PRESENT_HOST_PATH = "/api/present.host";
+/**
+ * Browser-relative form of {@link PRESENT_OPEN_PATH}; see
+ * .agents/notes/implemented/architecture/2026-09-14-web-document-relative-app-routes.md.
+ */
+export declare const PRESENT_OPEN_ROUTE: string;
+/** Browser-relative form of {@link PRESENT_HOST_PATH}. */
+export declare const PRESENT_HOST_ROUTE: string;
+/** Native file action selected by an explicit user gesture. */
+export type PresentedAction = 'open' | 'reveal';
+/** Serving Host information; file-manager names never derive from the browser's OS. */
+export interface PresentedHost {
+    name: string;
+    available: boolean;
+    fileManager: 'finder' | 'explorer' | 'directory' | null;
+}
+/**
+ * Validate desktop metadata received over HTTP.
+ * @param value - decoded response.
+ * @returns whether all displayed and actionable fields are supported.
+ */
+export declare function isPresentedHost(value: unknown): value is PresentedHost;
+/**
+ * Validate a file declaration read from a Session log.
+ * @param value - decoded durable data.
+ * @returns whether the declaration contains a path and optional description.
+ */
+export declare function isPresentedFile(value: unknown): value is PresentedFile;
+/**
+ * Build authenticated coordinates for a declared file.
+ * @param sessionId - owning Session.
+ * @param seq - deliverables/presented event sequence.
+ * @param index - original index in the event's files array.
+ * @returns document-relative file action route.
+ */
+export declare function presentedFileUrl(sessionId: SessionId, seq: number, index: number): string;
+/**
+ * Validate a delivery event before reading its turn or file declarations.
+ * @param value - decoded durable event data.
+ * @returns whether the event identifies a turn, call, and file list.
+ */
+export declare function isPresentedData(value: unknown): value is {
+    turn: number;
+    callId: ToolCallId;
+    files: unknown[];
+};
+/**
+ * Trailing path segment, the part that identifies the file at a glance.
+ * @param path - Slash- or backslash-separated path.
+ * @returns The final segment, or the whole string when separator-free.
+ */
+export declare function basename(path: string): string;
+//# sourceMappingURL=presented.d.ts.map

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@qilin-agent/client-ui-deliverables",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Changed-files card with per-file comparison tabs, delivery cards, and clickable final-response file references for Web",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-deliverables"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/api-remotes",
+        "@qilin-agent/client-connection",
+        "@qilin-agent/client-locale",
+        "@qilin-agent/client-ui-chat",
+        "@qilin-agent/client-ui-conversation",
+        "@qilin-agent/client-ui-renderer",
+        "@qilin-agent/client-ui-sidebar-right",
+        "@qilin-agent/client-ui-tool"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/client-connection": "3.1.3",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/client-store": "3.1.3",
+    "@qilin-agent/client-test-runtime": "3.1.3",
+    "@qilin-agent/client-ui-chat": "3.1.3",
+    "@qilin-agent/client-ui-conversation": "3.1.3",
+    "@qilin-agent/client-ui-dockkit": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-ui-primitives": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/client-ui-sidebar-right": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/session-query": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/client-ui-tool": "3.1.3",
+    "@qilin-agent/tool-present": "3.1.3",
+    "@qilin-agent/workspace-changes": "3.1.3",
+    "@qilin-agent/api-session-controller": "3.1.3",
+    "@qilin-agent/util-workspace-path": "3.1.3",
+    "@qilin-agent/api-workspace-files": "3.1.3",
+    "@qilin-agent/fs": "3.1.3",
+    "@qilin-agent/sandbox-policy": "3.1.3",
+    "@qilin-agent/fs-local": "3.1.3",
+    "@qilin-agent/agent": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@qilin-agent/typert-protocol": "3.1.3"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }