@qilin-agent/client-ui-plan 0.0.0-stage → 3.1.4

package/lib/index.js

@@ -0,0 +1,13 @@
+//#region lib/types/index.js
+/**
+* Plan control plugin, node half. Pure UI plugin: the empty apply exists so
+* the plugin appears in the host cordis.yml / Loader; the browser half ships
+* via exports["./client"], discovered through the package.json qilin.client
+* declaration. Plan behavior itself (the /plan command, the plan projection
+* unit, the policy section) is owned by `@qilin-agent/plan-mode`,
+* composed independently on the host roster.
+*/
+/** Host plugin body — no host-side behavior for this surface plugin. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,26 @@
+import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { ToolCallId } from '@qilin-agent/llm/brand';
+import type { createPlanReviewStore } from './review-store.ts';
+/** Session-bound navigation for logged plans. */
+export interface PlanOpenInjected {
+    /** Open or focus the exact submitted plan. */
+    openPlan: (callId: ToolCallId) => void;
+}
+/** Session-bound preview navigation for one pending review. */
+export interface PlanReviewOpenInjected {
+    /** Open the logged plan, or the request's temporary document when no invocation exists. */
+    openReview: (review: PropsRuntime<'conversation.plan-review.actions'>['review'], requestKey: string) => void;
+}
+/**
+ * Render the completed Turn's submitted plans in invocation order.
+ * @param props - Logged plan, localized copy, and Session-bound navigation.
+ * @returns keyboard-accessible plan cards, or null for a Turn without plans.
+ */
+export declare function PlanCards({ turn, useChat, openPlan, t }: PropsRuntime<'conversation.chat.turnTail'> & InjectFace<PlanOpenInjected> & PropsLocale<'plan'>): import("react").JSX.Element | null;
+/**
+ * Open each pending plan automatically and retain a manual opener without answering it.
+ * @param props - Review identity, Session store, localized copy, and navigation.
+ * @returns an opener for either logged or temporary plan text.
+ */
+export declare function PlanReviewOpen({ review, requestKey, openReview, t, useStore, actions }: PropsRuntime<'conversation.plan-review.actions'> & InjectFace<PlanReviewOpenInjected> & PropsLocale<'plan'> & PropsStore<ReturnType<typeof createPlanReviewStore>>): import("react").JSX.Element;
+//# sourceMappingURL=PlanCard.d.ts.map

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

@@ -0,0 +1,11 @@
+import type { InjectFace, PropsLocale, PropsRuntime } from '@qilin-agent/client-ui-slots';
+import type { PlanChipInjected } from './index.ts';
+/** Full plan-seat component props: runtime share (standard kit + locked owner prop) & injected share & the locale seat. */
+export type PlanChipProps = PropsRuntime<'conversation.input.plan'> & InjectFace<PlanChipInjected> & PropsLocale<'plan'>;
+/**
+ * Plan-mode status over the host-computed `plan` projection. The chip renders
+ * only while the effective target is plan mode (`pending ? !active : active`
+ * — a folded host value, not client optimism) and executes /plan off.
+ */
+export declare function PlanChip({ useProjection, locked, exitPlanMode, t }: PlanChipProps): import("react").JSX.Element | null;
+//# sourceMappingURL=PlanModeControl.d.ts.map

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

@@ -0,0 +1,16 @@
+import type { PropsLocale, PropsRuntime } from '@qilin-agent/client-ui-slots';
+type PlanPreviewProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsLocale<'plan'>;
+/**
+ * Render the submitted plan with its complete Markdown and a copy action.
+ * @param props - Framework-bound tab identity, resource, and copy.
+ * @returns the plan document or a localized loading/failure state.
+ */
+export declare function PlanPreview({ useTabInfo, useResource, t }: PlanPreviewProps): import("react").JSX.Element;
+/**
+ * Display a plan icon and the heading in its tab after resource recovery.
+ * @param props - Framework-bound tab identity and resource reader.
+ * @returns a decorative plan icon followed by the recovered title or initial localized label.
+ */
+export declare function PlanTitle({ useTabInfo, useResource }: PropsRuntime<'sidebar.right.pane.tab.title'>): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=PlanPreview.d.ts.map

package/lib/types/client/failure-line.d.ts

@@ -0,0 +1,11 @@
+/** Localized plan-owned failures and unmodified external diagnostics. */
+import type { RemoteFailure } from '@qilin-agent/typert-protocol';
+import type { TranslateNS } from '@qilin-agent/client-locale/client';
+/**
+ * Explain a failed plan read in the current locale.
+ * @param t - Plan namespace translator.
+ * @param failure - Failure reported by the resource provider.
+ * @returns localized plan copy, or the external failure's diagnostic.
+ */
+export declare function planFailureLine(t: TranslateNS<'plan'>, failure: RemoteFailure): string;
+//# sourceMappingURL=failure-line.d.ts.map

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

@@ -0,0 +1,25 @@
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import { type PlanKey } from './locales.ts';
+export type { PlanKey } from './locales.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The composer plan chip's copy. */
+        plan: PlanKey;
+    }
+}
+/** Injected business face of the composer plan seat. */
+export interface PlanChipInjected {
+    /**
+     * Leave plan mode by executing /plan off.
+     * @returns null on admitted execution; a user-visible failure line otherwise.
+     */
+    exitPlanMode: () => Promise<string | null>;
+}
+/** Services for plan controls, Conversation projection, and resource navigation. */
+export declare const inject: string[];
+/**
+ * Register plan controls, permanent Chat cards, and sidebar document reading.
+ * @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,48 @@
+/** `plan` namespace dictionaries (the composer plan chip's copy). */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'chip.label': string;
+    'preview.title': string;
+    'preview.document': string;
+    'preview.action': string;
+    'preview.open': string;
+    'preview.full': string;
+    'preview.openNamed': string;
+    'preview.loading': string;
+    'preview.failed': string;
+    'preview.invalidAddress': string;
+    'preview.historyUnavailable': string;
+    'preview.notFound': string;
+    'preview.unavailable': string;
+    'preview.expired': string;
+    'chip.on.aria': string;
+    'chip.on.title': string;
+    'chip.off.aria': string;
+    'chip.off.title': string;
+    'chip.exitFailed': string;
+};
+/** The plan namespace key union. */
+export type PlanKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'chip.label': string;
+    'preview.title': string;
+    'preview.document': string;
+    'preview.action': string;
+    'preview.open': string;
+    'preview.full': string;
+    'preview.openNamed': string;
+    'preview.loading': string;
+    'preview.failed': string;
+    'preview.invalidAddress': string;
+    'preview.historyUnavailable': string;
+    'preview.notFound': string;
+    'preview.unavailable': string;
+    'preview.expired': string;
+    'chip.on.aria': string;
+    'chip.on.title': string;
+    'chip.off.aria': string;
+    'chip.off.title': string;
+    'chip.exitFailed': string;
+};
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,11 @@
+import type { ConversationNodeDefinition } from '@qilin-agent/client-ui-conversation/client';
+import { type SubmittedPlan } from './plan.ts';
+declare module '@qilin-agent/client-ui-chat/client' {
+    interface ChatNodeDataMap {
+        /** Complete plan submitted through exit_plan_mode, including rejected or dismissed reviews. */
+        'submitted-plan': SubmittedPlan;
+    }
+}
+/** One card per invocation; a later PTC settlement retains the original card position. */
+export declare const planDefinition: ConversationNodeDefinition<SubmittedPlan>;
+//# sourceMappingURL=plan-definition.d.ts.map

package/lib/types/client/plan-resource.d.ts

@@ -0,0 +1,32 @@
+/** Read immutable plan arguments from a Session snapshot and earlier history pages. */
+import type { Context } from '@qilin-agent/kylin';
+import type { ResourceProvider } from '@qilin-agent/client-resources/client';
+import { type SubmittedPlan } from './plan.ts';
+declare module '@qilin-agent/typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** The resource URL does not identify a plan invocation. */
+        'plan/invalid-address': Record<string, never>;
+        /** Session history ended before an opening snapshot. */
+        'plan/unavailable': Record<string, never>;
+        /** The Session has no readable plan for this invocation. */
+        'plan/not-found': Record<string, never>;
+        /** The Session history read failed. */
+        'plan/read-failed': Record<string, never>;
+    }
+}
+declare module '@qilin-agent/client-ui-slots' {
+    interface ResourceProtocolMap {
+        /** Immutable Markdown from a logged exit_plan_mode invocation. */
+        plan: SubmittedPlan;
+    }
+}
+/**
+ * Bind plan reads to the generated Session Remote face.
+ * Opening a follow reads projections and may activate a prepared Session on the Host.
+ * Generated Remote streams can throw carrier failures; the provider reports failed
+ * reads as resource failure frames and preserves Remote error codes.
+ * @param remote - Existing Session history API.
+ * @returns a provider whose reads stop after finding the exact invocation.
+ */
+export declare function planResourceProvider(remote: Pick<Context['remote']['session'], 'follow' | 'page'>): ResourceProvider<'plan'>;
+//# sourceMappingURL=plan-resource.d.ts.map

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

@@ -0,0 +1,39 @@
+/** Plan text and resource identities derived from logged native or PTC calls. */
+import type { ToolCallId } from '@qilin-agent/llm/brand';
+import type { SessionAddress } from '@qilin-agent/api-session-controller/types';
+/** Complete Markdown and the heading displayed by a plan preview. */
+export interface PlanDocument {
+    readonly markdown: string;
+    readonly title: string;
+}
+/** One submitted plan, identified by its originating tool invocation. */
+export interface SubmittedPlan extends PlanDocument {
+    readonly callId: ToolCallId;
+}
+/** A saved sidebar resource names one invocation in one Session. */
+export interface PlanAddress {
+    readonly session: SessionAddress;
+    readonly callId: ToolCallId;
+}
+/**
+ * Read a complete plan from untrusted logged arguments.
+ * @param event - Native call or PTC dispatch event from Session history.
+ * @returns the submitted plan, or undefined for unrelated or malformed data.
+ */
+export declare function submittedPlan(event: {
+    readonly type: string;
+    readonly data: unknown;
+}): SubmittedPlan | undefined;
+/**
+ * Encode the durable identity of a plan without retaining its text in layout storage.
+ * @param target - Session and tool-call identity.
+ * @returns the plan resource address.
+ */
+export declare function planAddress(target: PlanAddress): string;
+/**
+ * Validate a saved or caller-supplied plan resource address.
+ * @param address - Address submitted to the sidebar or resource provider.
+ * @returns the decoded identity, or undefined for an unsupported address.
+ */
+export declare function parsePlanAddress(address: string): PlanAddress | undefined;
+//# sourceMappingURL=plan.d.ts.map

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

@@ -0,0 +1,25 @@
+/** Temporary review previews carry their document in in-memory tab navigation. */
+import type { SessionId } from '@qilin-agent/session/types';
+import type { PlanDocument } from './plan.ts';
+declare module '@qilin-agent/client-ui-sidebar-right/client' {
+    interface SidebarRightResourceParamsMap {
+        /** Review text without a logged invocation; never persisted in sidebar layout. */
+        'plan-review': {
+            planReview: PlanDocument;
+        };
+    }
+}
+/**
+ * Name one temporary review within its browser lifetime and Session.
+ * @param sessionId - Session displaying the review.
+ * @param requestKey - Browser-unique pending request identity.
+ * @returns the address used to focus or reopen its preview.
+ */
+export declare function reviewPreviewAddress(sessionId: SessionId, requestKey: string): string;
+/**
+ * Recognize temporary plan navigation without interpreting it as logged history.
+ * @param address - Saved or caller-supplied navigation address.
+ * @returns whether the address identifies a temporary review preview.
+ */
+export declare function isReviewPreviewAddress(address: string): boolean;
+//# sourceMappingURL=review-preview.d.ts.map

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

@@ -0,0 +1,15 @@
+/** Session-owned memory of pending plans already opened automatically. */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+interface PlanReviewState {
+    opened: Partial<Record<string, true>>;
+}
+type PlanReviewActions = {
+    markOpened: (draft: PlanReviewState, reviewKey: string) => void;
+};
+/**
+ * Keep manual sidebar closure effective across review component remounts.
+ * @returns a transient store handle whose instances belong to Session scopes.
+ */
+export declare function createPlanReviewStore(): EngineStoreHandle<PlanReviewState, PlanReviewActions>;
+export {};
+//# sourceMappingURL=review-store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Plan control plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader; the browser half ships
+ * via exports["./client"], discovered through the package.json qilin.client
+ * declaration. Plan behavior itself (the /plan command, the plan projection
+ * unit, the policy section) is owned by `@qilin-agent/plan-mode`,
+ * composed independently on the host roster.
+ */
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@qilin-agent/client-ui-plan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Plan mode controls, persistent transcript plan cards, and sidebar Markdown previews",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-plan"
+  },
+  "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-locale",
+        "@qilin-agent/client-ui-conversation",
+        "@qilin-agent/client-ui-sidebar-right",
+        "@qilin-agent/client-ui-chat",
+        "@qilin-agent/client-ui-user-questions",
+        "@qilin-agent/client-resources",
+        "@qilin-agent/api-session-controller"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/api-remotes": "3.1.4",
+    "@qilin-agent/client-test-runtime": "3.1.4",
+    "@qilin-agent/client-locale": "3.1.4",
+    "@qilin-agent/client-ui-conversation": "3.1.4",
+    "@qilin-agent/client-ui-primitives": "3.1.4",
+    "@qilin-agent/plan-mode": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-ui-slots": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/api-session-controller": "3.1.4",
+    "@qilin-agent/client-ui-chat": "3.1.4",
+    "@qilin-agent/client-ui-sidebar-right": "3.1.4",
+    "@qilin-agent/client-resources": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/typert-protocol": "3.1.4",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/client-ui-user-questions": "3.1.4",
+    "@qilin-agent/client-ui-session": "3.1.4",
+    "@qilin-agent/util-crypto": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }