@yadsh/dsh-qa-surface 0.5.0 → 0.6.1

package/lib/types/qa-tools/activation-manager.d.ts

@@ -0,0 +1,47 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaToolActivation, QaToolActivationOrigin, QaToolActivationResult, QaToolDescriptor } from "./types.js";
+export interface QaToolActivationManagerOptions {
+    /** Live catalog; read per activation so a reload sees the new set. */
+    readonly catalog: readonly QaToolDescriptor[];
+    readonly catalogVersion: string;
+    readonly logger: PluginLogger;
+}
+/**
+ * Per-agent runtime ownership of the QA tool registrations.
+ *
+ * One agent's tools exist only while that agent is live: activation registers
+ * the whole catalog through the agent's own scoped context, and disposal
+ * unwinds the exact disposers `tools.register()` returned. State is a WeakMap
+ * keyed by the live agent, so nothing has to be keyed by id and a stale agent
+ * can never be mistaken for a resumed one.
+ */
+export declare class QaToolActivationManager implements QaToolActivation {
+    private readonly options;
+    private readonly states;
+    constructor(options: QaToolActivationManagerOptions);
+    /**
+     * Register the whole catalog on one agent, all or nothing.
+     *
+     * A failed registration unwinds every tool this attempt registered and leaves
+     * the agent inactive: a partially attached QA surface would be worse than
+     * none, because the model would see a tool it cannot rely on.
+     * @param agent - the live agent receiving the tools.
+     * @param origin - why activation ran, for the operator log.
+     * @returns the outcome; `failed` carries the original error for the caller to report.
+     */
+    activate(agent: Agent, origin: QaToolActivationOrigin): QaToolActivationResult;
+    /** Whether this agent currently has the QA tools registered. */
+    isActive(agent: Agent): boolean;
+    /** Names registered on this agent; the admission guard evaluates this per call. */
+    activeToolNames(agent: Agent): readonly string[];
+    /**
+     * Unregister one agent's QA tools and forget its state. Safe to call more
+     * than once, and safe for an agent that never activated.
+     * @param agent - the agent whose registrations must be unwound.
+     */
+    disposeAgent(agent: Agent): void;
+    /** Dispose in reverse registration order, containing individual failures. */
+    private rollback;
+}
+//# sourceMappingURL=activation-manager.d.ts.map

package/lib/types/qa-tools/catalog.d.ts

@@ -0,0 +1,40 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { QaToolDescriptor } from "./types.js";
+/**
+ * Deterministic catalog identity. The durable activation marker is derived from
+ * the session log rather than stored, so this version is not compared against a
+ * persisted record; it is reported by `qa_tools_selfcheck` and by the operator
+ * log so a catalog change is visible in a running deployment.
+ *
+ * Bump it whenever the catalog's tool set or their schemas change.
+ */
+export declare const QA_TOOL_CATALOG_VERSION = "1";
+/** One QA tool reports the activation state of whichever agent calls it. */
+export interface QaToolsSelfcheckDeps {
+    readonly catalogVersion: string;
+    readonly activationMode: string;
+    /** Names the catalog contributes, in catalog order. */
+    readonly catalogTools: () => readonly string[];
+    /** Names currently registered on the calling agent. */
+    readonly activeTools: (agent: Agent) => readonly string[];
+    /** Whether the calling agent's session shows the activation skill was loaded. */
+    readonly skillLoaded: (agent: Agent) => boolean;
+}
+/**
+ * Build the shipped QA tool catalog.
+ *
+ * Side-effect free: constructing it registers nothing with `ctx.tools`. The
+ * activation manager owns every registration.
+ */
+export declare function createQaToolCatalog(deps: QaToolsSelfcheckDeps): readonly QaToolDescriptor[];
+/** QA tool names, in catalog order; the admission gate treats them as dynamic. */
+export declare function qaToolNames(catalog: readonly QaToolDescriptor[]): string[];
+/**
+ * Validate the catalog before it is registered anywhere: names must be unique
+ * and non-empty. Called once at activation preflight so a broken catalog fails
+ * before the first registration rather than halfway through.
+ * @param catalog - descriptors to validate.
+ * @throws when two descriptors share a name or a name is empty.
+ */
+export declare function assertValidQaToolCatalog(catalog: readonly QaToolDescriptor[]): void;
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/qa-tools/durable-marker.d.ts

@@ -0,0 +1,16 @@
+import type { Session } from "@deepseek-ai/dsh-session";
+/**
+ * Whether one session's log shows the configured skill was successfully loaded.
+ *
+ * Pairs each `tool/call` for the `skill` tool with its `tool/result`, then reads
+ * the loaded skill's name from the canonical rendered content. The rendered
+ * block is the only record of the returned skill identity that survives to the
+ * log — `tool/result` stores the model-facing message, not the tool's canonical
+ * value — and the pair closes only on a non-error result, so a refused or
+ * failed load never counts.
+ * @param session - the live session to inspect.
+ * @param skillName - the configured activation skill name.
+ * @returns whether that skill was loaded and its result succeeded.
+ */
+export declare function sessionLoadedSkill(session: Pick<Session, "snapshotEvents">, skillName: string): boolean;
+//# sourceMappingURL=durable-marker.d.ts.map

package/lib/types/qa-tools/index.d.ts

@@ -0,0 +1,40 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaToolActivation } from "./types.js";
+export interface QaToolsOptions {
+    readonly logger: PluginLogger;
+    readonly dynamicActivation: boolean;
+    readonly activationSkill: string;
+    readonly activationMode: string;
+    readonly activationPresets: readonly string[];
+}
+/**
+ * The QA tool subsystem: one catalog, one per-agent activation manager, and the
+ * two edges that drive it — the skill-result detector and the agent lifecycle.
+ *
+ * `dsh-qa-surface` owns the tools but never registers them at boot. Nothing in
+ * the catalog reaches the model until an agent it belongs to loads the
+ * activation skill, so the initial request of a session carries only the
+ * composition's own schemas.
+ */
+export declare class QaTools implements QaToolActivation {
+    private readonly ctx;
+    private readonly options;
+    private readonly manager;
+    private readonly detector;
+    private readonly lifecycle;
+    private readonly catalogTools;
+    constructor(ctx: Context, options: QaToolsOptions);
+    /** Names currently registered on one agent; the admission guard reads this per call. */
+    activeToolNames(agent: Agent): readonly string[];
+    dispose(): void;
+    /**
+     * The preset gate. An empty `activationPresets` leaves it open, which is only
+     * coherent when this plugin serves a single agent composition; naming the QA
+     * preset keeps an unrelated DSH agent from unlocking the same catalog by
+     * loading a skill of the same name.
+     */
+    private isManagedAgent;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/qa-tools/lifecycle.d.ts

@@ -0,0 +1,44 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaToolActivationManager } from "./activation-manager.js";
+export interface QaToolActivationLifecycleOptions {
+    readonly manager: QaToolActivationManager;
+    readonly logger: PluginLogger;
+    /** Whether this agent's composition participates in QA tool activation. */
+    readonly isManagedAgent: (agent: Agent) => boolean;
+    /**
+     * `true` waits for the activation skill; `false` attaches the catalog to
+     * every managed agent as soon as it is created.
+     */
+    readonly dynamicActivation: boolean;
+    /** The skill name whose load unlocks the tools in dynamic mode. */
+    readonly activationSkill: string;
+}
+/**
+ * Owns the arrival and departure edges of one agent's QA tool surface.
+ *
+ * Arrival: in dynamic mode a resumed session is recognized by the durable
+ * marker in its own log and gets its current catalog back before the first
+ * model step, while a fresh session waits for the detector. In immediate mode
+ * every managed agent is served at creation.
+ *
+ * Departure: the exact registrations this plugin made are unwound when the
+ * agent is disposed, so an agent that leaves never leaves a scoped tool behind.
+ */
+export declare class QaToolActivationLifecycle {
+    private readonly ctx;
+    private readonly options;
+    private readonly disposers;
+    constructor(ctx: Context, options: QaToolActivationLifecycleOptions);
+    /**
+     * Restore a resumed activation, or attach immediately in the compatibility
+     * mode. A fresh managed session ends this handler inactive by design: the
+     * tools arrive when the model loads the activation skill.
+     */
+    private onAgentCreated;
+    private attach;
+    private onAgentDisposed;
+    dispose(): void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/types/qa-tools/types.d.ts

@@ -0,0 +1,45 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * One entry of the QA tool catalog.
+ *
+ * `group` and `tags` are passive metadata: the MVP activation policy activates
+ * the whole catalog and never filters on them. They exist so a later
+ * `activationMode` can select subsets without touching the tool definitions.
+ */
+export interface QaToolDescriptor {
+    readonly definition: ToolDefinition;
+    /** Capability bucket reserved for a future grouped activation mode. */
+    readonly group?: string;
+    /** Free-form labels reserved for a future search/unlock mode. */
+    readonly tags?: readonly string[];
+}
+/** Why one activation ran; the origin only shapes logging and the event guard. */
+export type QaToolActivationOrigin = "skill" | "restore" | "immediate";
+/** Runtime activation state of one live agent. */
+export interface QaToolActivationState {
+    status: "inactive" | "activating" | "active";
+    /** Catalog version whose tools are registered; set once `status` is active. */
+    catalogVersion?: string | undefined;
+    /** Exact disposers returned by `tools.register()`, in registration order. */
+    disposers: (() => void)[];
+}
+/** Outcome of one activation attempt. */
+export type QaToolActivationResult = {
+    readonly status: "activated";
+    readonly count: number;
+} | {
+    readonly status: "already-active";
+} | {
+    readonly status: "failed";
+    readonly error: unknown;
+};
+/** The activation subsystem's observable surface, injected into the admission gate. */
+export interface QaToolActivation {
+    /**
+     * Names currently registered on one live agent. The admission guard evaluates
+     * this per execution, so a tool becomes callable exactly when it appears here.
+     */
+    activeToolNames(agent: Agent): readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/secure-session.d.ts

@@ -1,3 +1,4 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
@@ -25,7 +26,15 @@ export declare class QaPolicyAdmission {
     private readonly config;
     private readonly logger;
     private readonly accounts?;
+    /**
+     * Names the QA tool catalog attached to one agent after its activation
+     * skill loaded. Read per execution, so a tool becomes callable exactly when
+     * it is registered and stops being callable once the agent is disposed.
+     */
+    private readonly dynamicToolNames;
     private readonly appliedPolicies;
+    /** Host-trusted principal-scoped plugin tools enabled outside static config. */
+    private readonly principalScopedTools;
     /**
      * Sessions the QA surface has attested. The provenance note is written for
      * exactly these, and a delegated child resolves through its root session, so
@@ -34,15 +43,35 @@ export declare class QaPolicyAdmission {
     private readonly attested;
     private readonly workspaceAccess;
     private readonly disposeWorkspaceGuard;
-    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined);
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined, 
+    /**
+     * Names the QA tool catalog attached to one agent after its activation
+     * skill loaded. Read per execution, so a tool becomes callable exactly when
+     * it is registered and stops being callable once the agent is disposed.
+     */
+    dynamicToolNames?: (agent: Agent) => readonly string[]);
+    /**
+     * Add tools whose own executor resolves the QA principal server-side.
+     * Enabling the contributing plugin is the operator decision; model arguments
+     * still cannot select an owner. The returned disposer mirrors tool lifetime.
+     */
+    registerPrincipalScopedTools(names: readonly string[]): () => void;
+    /**
+     * Validate deployment-owned facts before a Host session is materialized.
+     * Agent-scoped facts (preset composition and tools) remain in secureSession,
+     * but a missing Workspace or mismatched permission preset must not leave a
+     * newly-created, permanently unusable chat behind.
+     */
+    preflightDeployment(): void;
     /**
      * The mounted attachment store's verbatim root, when the backend exposes
      * one. It sits outside every workspace, so the per-user fence would
      * otherwise deny the model the exact file an upload produced and the prompt
      * points it at. A backend without a resolvable root simply keeps the fence
      * closed — attachments then only work where reads are not fenced per user.
+     * Source preview asks for the same root, so one upload is readable by both.
      */
-    private attachmentRoot;
+    attachmentRoot(): string | undefined;
     /**
      * The live agent for one session, resuming a Session the Host has not
      * materialized in this process.
@@ -63,6 +92,8 @@ export declare class QaPolicyAdmission {
      */
     private liveAgent;
     secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
+    /** Resolve the deployment facts shared by creation and full attestation. */
+    private deploymentPins;
     /**
      * Whether one session went through this boundary. The provenance note is
      * written only for attested sessions, which is what keeps a deployment's

package/lib/types/starters.d.ts

@@ -0,0 +1,45 @@
+import type { QaAccountStarters, QaAccountStartersInput, QaAccountStarter } from "./types.js";
+/**
+ * Per-account starter messages: the labeled buttons above an empty composer,
+ * and what each of them sends. Shape, limits, and the normalization both
+ * halves of the plugin agree on. Deliberately free of Node built-ins — the
+ * accounts store and the browser-side form import these same rules, the same
+ * way profile.ts does for the self-declared identity.
+ */
+/** Most starter buttons one account may store. */
+export declare const QA_STARTERS_MAX_ITEMS = 12;
+/** Longest accepted button label. */
+export declare const QA_STARTERS_MAX_LABEL = 80;
+/** Longest accepted prompt one button sends. */
+export declare const QA_STARTERS_MAX_PROMPT = 2000;
+/** The starters of an account that never customized them. */
+export declare function emptyStarters(): QaAccountStarters;
+/**
+ * Read one stored (or wire-delivered) starters record into its public shape.
+ * Unknown or hand-edited input degrades to the readable subset instead of
+ * throwing, mirroring the profile read path: a malformed record must never
+ * cost the account its session.
+ */
+export declare function normalizeStarters(value: unknown): QaAccountStarters;
+/** Validated starters values, before the store persists them. */
+export type QaStartersWrite = QaAccountStartersInput;
+export type QaStartersWriteResult = {
+    readonly ok: true;
+    readonly value: QaStartersWrite;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Validate one full-replace starters write. Values are cleaned the same way
+ * the read path cleans them, but limits are refused with a message instead of
+ * truncated, so a user pasting an essay learns why it was not stored.
+ */
+export declare function validateStartersWrite(input: unknown): QaStartersWriteResult;
+/**
+ * The buttons an empty composer shows: the account's own starters first,
+ * then the deployment's suggestions unless the account hid them. An anonymous
+ * visitor (no starters of their own) sees exactly the deployment's list.
+ */
+export declare function effectiveQuickQuestions(own: QaAccountStarters | undefined, defaults: readonly string[]): readonly QaAccountStarter[];
+//# sourceMappingURL=starters.d.ts.map