@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

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/questions.d.ts

@@ -0,0 +1,83 @@
+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 { QaSessionOwnership } from "./session-ownership.js";
+import type { QaPendingQuestion, QaQuestionAnswerItem } from "./types.js";
+/**
+ * The harness user-questions contract this seam reads and writes, declared
+ * structurally on purpose: the plugin neither mounts the service nor depends on
+ * its package, so it stays loadable in a deployment that composes no questions
+ * at all. Shapes follow `@deepseek-ai/dsh-user-questions` `src/types.ts` at the
+ * tested harness release (`AskUserQuestionItem` / `AskUserQuestionAnswer`).
+ */
+export interface QaQuestionOption {
+    readonly label: string;
+    readonly description?: string;
+}
+export interface QaQuestionItem {
+    readonly id: string;
+    readonly question: string;
+    readonly detail?: string;
+    readonly header?: string;
+    readonly options?: readonly QaQuestionOption[];
+    readonly multiSelect?: boolean;
+}
+export interface QaQuestionRequest {
+    readonly questions: readonly QaQuestionItem[];
+    readonly agent?: Agent;
+    readonly signal?: AbortSignal;
+}
+/** What the answerer waterfall accepts as its value. */
+export interface QaQuestionAnswer {
+    readonly answers: readonly QaQuestionAnswerItem[];
+}
+/** What the model reads when the deployment does not answer questions. */
+export declare const QA_QUESTIONS_UNSUPPORTED = "questions are not answered in this assistant view; ask the user in plain text instead";
+/**
+ * User questions in the QA view.
+ *
+ * `ask_user_question` reaches the browser through the harness answerer
+ * waterfall, and the stock DSH web bundle mounts its own answerer in every
+ * page. Behind the QA overlay that answerer is unreachable, so a question asked
+ * of a QA chat would sit in front of nobody. This gate claims the request for
+ * attested chats before the generic browser bridge sees it:
+ *
+ * - `interaction.questions: interactive` parks the request until the operator
+ *   answers or closes it in the QA view, and the answer becomes the waterfall's
+ *   value.
+ * - `unsupported` (default) refuses with a reason the model can act on, rather
+ *   than letting the turn stall on a card no one can see.
+ *
+ * Nothing is ever answered on the operator's behalf, and a request from a
+ * session this deployment did not attest is handed back to the chain untouched.
+ */
+export declare class QaQuestionGate {
+    private readonly ctx;
+    private readonly interactive;
+    private readonly ownership;
+    private readonly logger;
+    private readonly pending;
+    private readonly disposers;
+    constructor(ctx: Context, interactive: () => boolean, ownership: QaSessionOwnership, logger: PluginLogger);
+    /** Claim question requests for the chats this deployment answers. */
+    install(): void;
+    /** Questions of one chat, oldest first: what the QA view renders. */
+    list(sessionId: string): readonly QaPendingQuestion[];
+    /**
+     * Apply the operator's answers; an unknown or foreign id is refused. The
+     * parked request is authoritative: a label the question never offered is
+     * dropped, and a free-text answer replaces the choice in a single-select
+     * rather than accompanying it, so the model only ever reads a real answer.
+     */
+    answer(sessionId: string, requestId: string, answers: readonly QaQuestionAnswerItem[]): boolean;
+    /** Close a request without answering it. */
+    cancel(sessionId: string, requestId: string): boolean;
+    /** Detach the listener and fail every parked request. Wired as an effect. */
+    dispose(): void;
+    private handle;
+    /** Park one request until the operator answers it, or the turn ends. */
+    private park;
+    /** Fail the questions one session's agent owns; a disposed agent cannot ask. */
+    private settleOwner;
+}
+//# sourceMappingURL=questions.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,25 +26,65 @@ 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
      * one set answers for the whole chat.
      */
     private readonly attested;
-    private readonly workspaceRoots;
+    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;
     /**
      * 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.
+     */
+    attachmentRoot(): string | undefined;
+    /**
+     * The live agent for one session, resuming a Session the Host has not
+     * materialized in this process.
+     *
+     * DSH builds an agent on demand: a session's journal opens straight from
+     * persistence (`session/page` reads the durable log), and only Agent-bound
+     * operations — a prompt, a model selection, renaming, an upload — resolve or
+     * resume one. So a chat from an earlier Host run has a readable transcript
+     * and no agent at all, and attestation, which pins the tool policy ON that
+     * agent, is the first thing here that needs one. Refusing instead would make
+     * every restored chat unopenable until something else in the Host happened
+     * to wake it.
+     *
+     * The resume composes the session's OWN recorded preset — the same
+     * composition a stock prompt would produce — so a session composed outside
+     * the QA preset still lands on the mismatch refusals below ("composition
+     * mismatch"), and the adoption and permission checks stay the gate.
      */
-    private attachmentRoot;
-    secureSession(token: string, sessionId: string): QaLockdownProof;
+    private liveAgent;
+    secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
     /**
      * 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/session-ownership.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from "@deepseek-ai/cordis";
+/**
+ * Which sessions belong to this deployment.
+ *
+ * The admission boundary attests chat roots. A delegated child never appears
+ * there — its scope chain does not reach the chat's own agent context — so it
+ * inherits its chat from the session that created it. Both interactive seams
+ * (tool approvals and user questions) read ownership from here, which is what
+ * keeps one chat answered by exactly one surface.
+ */
+export declare class QaSessionOwnership {
+    private readonly isAttested;
+    /** Child session → the attested chat that owns it. */
+    private readonly inherited;
+    private disposeListener;
+    private installed;
+    constructor(isAttested: (sessionId: string) => boolean);
+    /** Listen for the children of an attested chat; safe to call from each seam. */
+    install(ctx: Context): void;
+    /** The attested chat behind a session: itself, or the root it inherited. */
+    rootOf(sessionId: string): string | undefined;
+    /**
+     * Drop one session's inheritance. Called when its agent is gone; the chat's
+     * own claim needs no bookkeeping here, because it resolves through the
+     * admission's attested set, which owns that lifetime.
+     */
+    forget(sessionId: string): void;
+    dispose(): void;
+}
+//# sourceMappingURL=session-ownership.d.ts.map

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