@klarkxy/dsh-plugin-kit 0.5.0 → 0.6.1

package/README.md

@@ -4,9 +4,7 @@
 
 [简体中文](docs/README.zh-CN.md)
 
-A shared library used by the plugins in this repository. It adds no feature of its own and does not need to be installed separately; plugins that need it install it automatically.
-
-For plugin developers, the source code and type declarations are the reference.
+Shared runtime and UI support library for the DeepSeek Harness plugins in this repository — covering the default auxiliary model, shared session settings, storage and host-client helpers, official UI styling, and subagent session detection. Plugins that depend on it install it automatically; plugin developers should refer to the source code and type declarations.
 
 ## License
 

package/docs/README.zh-CN.md

@@ -4,9 +4,7 @@
 
 [English](../README.md)
 
-本仓库插件共用的支撑库。它自身不提供功能，也不需要单独安装；需要它的插件会自动带上。
-
-插件开发者请直接参考源码和类型声明。
+本仓库 DeepSeek Harness 插件共用的运行时与界面支撑库，提供默认辅助模型、共享会话设置页、存储与前后端通信辅助、官方 UI 样式及子代理会话识别等共享能力。依赖它的插件会自动安装；插件开发者请直接参考源码和类型声明。
 
 ## 许可证
 

package/lib/auxiliary-context.d.ts

@@ -0,0 +1,42 @@
+//#region src/auxiliary-context.d.ts
+/**
+ * Auxiliary request-context packing for feature model calls.
+ *
+ * A feature may prepend stable material (session facts, its own durable
+ * records) to the live request so provider-side caching reuses one prefix.
+ * Three invariants keep this honest and testable:
+ *
+ * - Material is rebuilt by the caller from current facts on every call;
+ *   nothing here stores, accumulates or replays model outputs.
+ * - Order is caller-owned: stable material first, live request last.
+ * - A context that exceeds its byte budget fails loudly instead of
+ *   silently dropping evidence.
+ *
+ * Pure and browser-safe: no host imports.
+ */
+/** Thrown when packed context exceeds the caller's byte budget. */
+declare class AuxiliaryContextTooLargeError extends Error {
+  readonly bytes: number;
+  readonly maxBytes: number;
+  constructor(bytes: number, maxBytes: number);
+}
+/**
+ * Join stable material segments for one request. The packed text must fit
+ * `maxBytes` or the call throws — the caller decides what to drop, so
+ * evidence is never silently truncated. Empty input packs to ''.
+ */
+declare function packAuxiliaryContext(segments: readonly string[], maxBytes: number): string;
+/**
+ * Assemble the single user message for an auxiliary model call: stable
+ * material in one labelled block first, the live request last. With no
+ * context the result is byte-identical to `text`, so callers without
+ * material keep exactly the previous wire shape.
+ */
+declare function buildAuxiliaryUserText(request: {
+  feature?: string;
+  context?: string | readonly string[];
+  text: string;
+}): string;
+//#endregion
+export { AuxiliaryContextTooLargeError, buildAuxiliaryUserText, packAuxiliaryContext };
+//# sourceMappingURL=auxiliary-context.d.ts.map

package/lib/auxiliary-context.js

@@ -0,0 +1,65 @@
+//#region src/auxiliary-context.ts
+/**
+* Auxiliary request-context packing for feature model calls.
+*
+* A feature may prepend stable material (session facts, its own durable
+* records) to the live request so provider-side caching reuses one prefix.
+* Three invariants keep this honest and testable:
+*
+* - Material is rebuilt by the caller from current facts on every call;
+*   nothing here stores, accumulates or replays model outputs.
+* - Order is caller-owned: stable material first, live request last.
+* - A context that exceeds its byte budget fails loudly instead of
+*   silently dropping evidence.
+*
+* Pure and browser-safe: no host imports.
+*/
+/** Thrown when packed context exceeds the caller's byte budget. */
+var AuxiliaryContextTooLargeError = class extends Error {
+	bytes;
+	maxBytes;
+	constructor(bytes, maxBytes) {
+		super(`Auxiliary context is ${bytes} bytes, over the ${maxBytes}-byte budget.`);
+		this.name = "AuxiliaryContextTooLargeError";
+		this.bytes = bytes;
+		this.maxBytes = maxBytes;
+	}
+};
+const utf8 = new TextEncoder();
+function byteLength(text) {
+	return utf8.encode(text).byteLength;
+}
+function normalizeSegments(context) {
+	if (context === void 0) return [];
+	return (typeof context === "string" ? [context] : context).filter((segment) => typeof segment === "string" && segment.length > 0);
+}
+/**
+* Join stable material segments for one request. The packed text must fit
+* `maxBytes` or the call throws — the caller decides what to drop, so
+* evidence is never silently truncated. Empty input packs to ''.
+*/
+function packAuxiliaryContext(segments, maxBytes) {
+	if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new Error("Invalid auxiliary context budget");
+	const text = normalizeSegments(segments).join("\n");
+	if (byteLength(text) > maxBytes) throw new AuxiliaryContextTooLargeError(byteLength(text), maxBytes);
+	return text;
+}
+/** Only word characters, dots, colons and dashes are kept inside the feature attribute. */
+function featureAttribute(feature) {
+	return feature.replaceAll(/[^\w.:-]/g, "_");
+}
+/**
+* Assemble the single user message for an auxiliary model call: stable
+* material in one labelled block first, the live request last. With no
+* context the result is byte-identical to `text`, so callers without
+* material keep exactly the previous wire shape.
+*/
+function buildAuxiliaryUserText(request) {
+	const context = normalizeSegments(request.context);
+	if (!context.length) return request.text;
+	return `<auxiliary-context${request.feature ? ` feature="${featureAttribute(request.feature)}"` : ""}>\n${context.join("\n")}\n</auxiliary-context>\n<request>\n${request.text}\n</request>`;
+}
+//#endregion
+export { AuxiliaryContextTooLargeError, buildAuxiliaryUserText, packAuxiliaryContext };
+
+//# sourceMappingURL=auxiliary-context.js.map

package/lib/auxiliary-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auxiliary-context.js","names":[],"sources":["../src/auxiliary-context.ts"],"sourcesContent":["/**\n * Auxiliary request-context packing for feature model calls.\n *\n * A feature may prepend stable material (session facts, its own durable\n * records) to the live request so provider-side caching reuses one prefix.\n * Three invariants keep this honest and testable:\n *\n * - Material is rebuilt by the caller from current facts on every call;\n *   nothing here stores, accumulates or replays model outputs.\n * - Order is caller-owned: stable material first, live request last.\n * - A context that exceeds its byte budget fails loudly instead of\n *   silently dropping evidence.\n *\n * Pure and browser-safe: no host imports.\n */\n\n/** Thrown when packed context exceeds the caller's byte budget. */\nexport class AuxiliaryContextTooLargeError extends Error {\n  readonly bytes: number\n  readonly maxBytes: number\n  constructor(bytes: number, maxBytes: number) {\n    super(`Auxiliary context is ${bytes} bytes, over the ${maxBytes}-byte budget.`)\n    this.name = 'AuxiliaryContextTooLargeError'\n    this.bytes = bytes\n    this.maxBytes = maxBytes\n  }\n}\n\nconst utf8 = new TextEncoder()\n\nfunction byteLength(text: string): number {\n  return utf8.encode(text).byteLength\n}\n\nfunction normalizeSegments(context: string | readonly string[] | undefined): readonly string[] {\n  if (context === undefined) return []\n  const list: readonly string[] = typeof context === 'string' ? [context] : context\n  return list.filter(segment => typeof segment === 'string' && segment.length > 0)\n}\n\n/**\n * Join stable material segments for one request. The packed text must fit\n * `maxBytes` or the call throws — the caller decides what to drop, so\n * evidence is never silently truncated. Empty input packs to ''.\n */\nexport function packAuxiliaryContext(segments: readonly string[], maxBytes: number): string {\n  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new Error('Invalid auxiliary context budget')\n  const text = normalizeSegments(segments).join('\\n')\n  if (byteLength(text) > maxBytes) throw new AuxiliaryContextTooLargeError(byteLength(text), maxBytes)\n  return text\n}\n\n/** Only word characters, dots, colons and dashes are kept inside the feature attribute. */\nfunction featureAttribute(feature: string): string {\n  return feature.replaceAll(/[^\\w.:-]/g, '_')\n}\n\n/**\n * Assemble the single user message for an auxiliary model call: stable\n * material in one labelled block first, the live request last. With no\n * context the result is byte-identical to `text`, so callers without\n * material keep exactly the previous wire shape.\n */\nexport function buildAuxiliaryUserText(request: {\n  feature?: string\n  context?: string | readonly string[]\n  text: string\n}): string {\n  const context = normalizeSegments(request.context)\n  if (!context.length) return request.text\n  const attribute = request.feature ? ` feature=\"${featureAttribute(request.feature)}\"` : ''\n  return `<auxiliary-context${attribute}>\\n${context.join('\\n')}\\n</auxiliary-context>\\n<request>\\n${request.text}\\n</request>`\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,IAAa,gCAAb,cAAmD,MAAM;CACvD;CACA;CACA,YAAY,OAAe,UAAkB;EAC3C,MAAM,wBAAwB,MAAM,mBAAmB,SAAS,cAAc;EAC9E,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,WAAW;CAClB;AACF;AAEA,MAAM,OAAO,IAAI,YAAY;AAE7B,SAAS,WAAW,MAAsB;CACxC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC;AAC3B;AAEA,SAAS,kBAAkB,SAAoE;CAC7F,IAAI,YAAY,KAAA,GAAW,OAAO,CAAC;CAEnC,QADgC,OAAO,YAAY,WAAW,CAAC,OAAO,IAAI,QAAA,CAC9D,QAAO,YAAW,OAAO,YAAY,YAAY,QAAQ,SAAS,CAAC;AACjF;;;;;;AAOA,SAAgB,qBAAqB,UAA6B,UAA0B;CAC1F,IAAI,CAAC,OAAO,cAAc,QAAQ,KAAK,YAAY,GAAG,MAAM,IAAI,MAAM,kCAAkC;CACxG,MAAM,OAAO,kBAAkB,QAAQ,CAAC,CAAC,KAAK,IAAI;CAClD,IAAI,WAAW,IAAI,IAAI,UAAU,MAAM,IAAI,8BAA8B,WAAW,IAAI,GAAG,QAAQ;CACnG,OAAO;AACT;;AAGA,SAAS,iBAAiB,SAAyB;CACjD,OAAO,QAAQ,WAAW,aAAa,GAAG;AAC5C;;;;;;;AAQA,SAAgB,uBAAuB,SAI5B;CACT,MAAM,UAAU,kBAAkB,QAAQ,OAAO;CACjD,IAAI,CAAC,QAAQ,QAAQ,OAAO,QAAQ;CAEpC,OAAO,qBADW,QAAQ,UAAU,aAAa,iBAAiB,QAAQ,OAAO,EAAE,KAAK,GAClD,KAAK,QAAQ,KAAK,IAAI,EAAE,qCAAqC,QAAQ,KAAK;AAClH"}

package/lib/auxiliary-model-client.d.ts

@@ -0,0 +1,57 @@
+import { AuxiliaryModelDefaults } from "./contracts.js";
+import { ReactNode } from "react";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/auxiliary-model-client.d.ts
+/** The stored row; re-exported so card consumers share the contract shape. */
+type AuxiliaryModelSnapshot = AuxiliaryModelDefaults;
+declare const AUXILIARY_MODEL_SEAT_ID = "auxiliary-model";
+declare const AUXILIARY_MODEL_SEAT_ORDER = 55;
+/** Theme-token-only stylesheet: officialUiCss scope plus the shared ModelMenu recipe. */
+declare const auxiliaryModelCss: string;
+/** The client services this card reads; the shared service passes ctx.root. */
+interface AuxiliaryModelClient {
+  connection: {
+    rpc: {
+      call(channel: string, endpoint: string, payload: unknown): Promise<unknown>;
+    };
+    generation?: {
+      subscribe(listener: () => void): () => void;
+    };
+  };
+  remote?: {
+    session?: {
+      modelCatalog?: () => Promise<unknown>;
+    };
+  };
+  locale?: {
+    getSnapshot(): {
+      active: string;
+    };
+    subscribe(listener: () => void): () => void;
+  };
+}
+/**
+ * The shared card. All state comes from the shared host service over the
+ * plugin-kit RPC channel; the card only renders the stored row.
+ */
+declare function AuxiliaryModelCard({ client, subscribe }: {
+  client: AuxiliaryModelClient;
+  /** Settings-change invalidation; injected for tests without a live stream. */
+  subscribe?: (change: () => void, error?: (message: string) => void) => () => void;
+}): ReactNode;
+/**
+ * Show the shared "default auxiliary model" card while the calling plugin is
+ * enabled.
+ *
+ * `ctx` is the plugin's own client context: the card itself is retained on the
+ * shared root context for as long as any participant lives, so an arbitrary
+ * subset of enabled plugins yields the same single card. The mount's slot wait
+ * and the change-stream contribution are owned by the root service — the first
+ * participant's unload cannot take the card down. Returns a disposer; it may
+ * be invoked by both ctx.effect and an explicit caller and releases at most
+ * once, so a double call cannot unbalance the shared refcount.
+ */
+declare function registerAuxiliaryModelSettings(ctx: Context): () => void;
+//#endregion
+export { AUXILIARY_MODEL_SEAT_ID, AUXILIARY_MODEL_SEAT_ORDER, AuxiliaryModelCard, AuxiliaryModelClient, AuxiliaryModelSnapshot, auxiliaryModelCss, registerAuxiliaryModelSettings };
+//# sourceMappingURL=auxiliary-model-client.d.ts.map