@yadsh/dsh-qa-surface 0.5.0 → 0.6.0

package/lib/provenance/snapshot-store.js

@@ -0,0 +1,154 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+const locationSchema = z
+    .object({
+    path: z.string().optional(),
+    lineStart: z.number().int().optional(),
+    lineEnd: z.number().int().optional(),
+    anchor: z.string().optional(),
+    jiraKey: z.string().optional(),
+    confluencePageId: z.string().optional(),
+})
+    .strict();
+const originSchema = z
+    .object({
+    sessionId: z.string(),
+    turn: z.number().int(),
+    step: z.number().int().optional(),
+    toolCallId: z.string().optional(),
+    toolName: z.string().optional(),
+    agentId: z.string().optional(),
+    role: z.enum(["parent", "subagent"]),
+    subagentRunId: z.string().optional(),
+    subagentSessionId: z.string().optional(),
+})
+    .strict();
+const sourceSchema = z
+    .object({
+    id: z.string(),
+    kind: z.enum([
+        "file",
+        "code",
+        "web",
+        "jira",
+        "confluence",
+        "knowledge",
+        "other",
+    ]),
+    title: z.string(),
+    uri: z.string().optional(),
+    path: z.string().optional(),
+    snippet: z.string().optional(),
+    locations: z.array(locationSchema),
+    evidence: z.enum([
+        "read",
+        "fetched",
+        "queried",
+        "reported",
+        "inherited",
+        "discovered",
+    ]),
+    origins: z.array(originSchema),
+    score: z.number(),
+    metadata: z.record(z.string(), z.json()).optional(),
+})
+    .strict();
+const bundleSchema = z
+    .object({
+    version: z.literal(1),
+    sessionId: z.string(),
+    turn: z.number().int().nonnegative(),
+    sources: z.array(sourceSchema),
+    discovered: z.array(sourceSchema).optional(),
+    complete: z.boolean(),
+    incompleteOrigins: z
+        .array(z
+        .object({
+        subagentRunId: z.string().optional(),
+        provider: z.string().optional(),
+        reason: z.string(),
+    })
+        .strict())
+        .optional(),
+})
+    .strict();
+const fileSchema = z
+    .object({
+    version: z.literal(1),
+    sessions: z.record(z.string(), z.record(z.string(), bundleSchema)),
+})
+    .strict();
+/** Process-local store used by tests and explicit ephemeral deployments. */
+export class MemoryQaProvenanceSnapshotStore {
+    sessions = new Map();
+    list(sessionId) {
+        return [...(this.sessions.get(sessionId)?.values() ?? [])].sort((left, right) => left.turn - right.turn);
+    }
+    put(bundle) {
+        const turns = this.sessions.get(bundle.sessionId) ?? new Map();
+        turns.set(bundle.turn, structuredClone(bundle));
+        this.sessions.set(bundle.sessionId, turns);
+    }
+}
+/** Default durable provenance path, deliberately outside Harness journals. */
+export function defaultQaProvenanceFilePath() {
+    const home = process.env.DSH_HOME?.trim();
+    return path.join(home !== undefined && home !== "" ? home : process.cwd(), "qa-sources.json");
+}
+/** Atomically persists per-turn QA source snapshots in plugin-owned storage. */
+export class FileQaProvenanceSnapshotStore {
+    filePath;
+    constructor(filePath = defaultQaProvenanceFilePath()) {
+        this.filePath = filePath;
+    }
+    list(sessionId) {
+        const turns = this.load().sessions[sessionId] ?? {};
+        return Object.values(turns).sort((left, right) => left.turn - right.turn);
+    }
+    put(bundle) {
+        const current = this.load();
+        const next = {
+            version: 1,
+            sessions: {
+                ...current.sessions,
+                [bundle.sessionId]: {
+                    ...(current.sessions[bundle.sessionId] ?? {}),
+                    [String(bundle.turn)]: structuredClone(bundle),
+                },
+            },
+        };
+        this.persist(next);
+    }
+    load() {
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return { version: 1, sessions: {} };
+            }
+            throw error;
+        }
+        const parsed = fileSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            throw new Error(`qa-sources: ${this.filePath} is not a recognizable provenance file; refusing to overwrite it`, { cause: parsed.error });
+        }
+        for (const [sessionId, turns] of Object.entries(parsed.data.sessions)) {
+            for (const [turn, bundle] of Object.entries(turns)) {
+                if (bundle.sessionId !== sessionId || String(bundle.turn) !== turn) {
+                    throw new Error(`qa-sources: ${this.filePath} contains a snapshot under the wrong session or turn; refusing to overwrite it`);
+                }
+            }
+        }
+        return parsed.data;
+    }
+    persist(file) {
+        mkdirSync(path.dirname(this.filePath), { recursive: true });
+        const temp = `${this.filePath}.${process.pid}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+        renameSync(temp, this.filePath);
+    }
+}
+//# sourceMappingURL=snapshot-store.js.map

package/lib/provenance/snapshot-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.js","sourceRoot":"","sources":["../../src/provenance/snapshot-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACjC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACpC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;QACX,MAAM;QACN,MAAM;QACN,KAAK;QACL,MAAM;QACN,YAAY;QACZ,WAAW;QACX,OAAO;KACR,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC;QACf,MAAM;QACN,SAAS;QACT,SAAS;QACT,UAAU;QACV,WAAW;QACX,YAAY;KACb,CAAC;IACF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE;CACpD,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACpC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE;IAC5C,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,iBAAiB,EAAE,CAAC;SACjB,KAAK,CACJ,CAAC;SACE,MAAM,CAAC;QACN,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACpC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;KACnB,CAAC;SACD,MAAM,EAAE,CACZ;SACA,QAAQ,EAAE;CACd,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,UAAU,GAAG,CAAC;KACjB,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC;CACnE,CAAC;KACD,MAAM,EAAE,CAAC;AAYZ,4EAA4E;AAC5E,MAAM,OAAO,+BAA+B;IACzB,QAAQ,GAAG,IAAI,GAAG,EAAsC,CAAC;IAE1E,IAAI,CAAC,SAAiB;QACpB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAC7D,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CACxC,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,MAAqB;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;QAC/D,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;QAChD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,2BAA2B;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,OAAO,IAAI,CAAC,IAAI,CACd,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EACxD,iBAAiB,CAClB,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,OAAO,6BAA6B;IAErB,QAAQ;IAD3B,YACmB,QAAQ,GAAW,2BAA2B,EAAE;wBAAhD,QAAQ;IACxB,CAAC;IAEJ,IAAI,CAAC,SAAiB;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACpD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,GAAG,CAAC,MAAqB;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAiB;YACzB,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE;gBACR,GAAG,OAAO,CAAC,QAAQ;gBACnB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE;oBAClB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;oBAC7C,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC;iBAC/C;aACF;SACF,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAEO,IAAI;QACV,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YACtC,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,QAAQ,kEAAkE,EAC9F,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CACxB,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtE,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;oBACnE,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,QAAQ,gFAAgF,CAC7G,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC,IAAoB,CAAC;IACrC,CAAC;IAEO,OAAO,CAAC,IAAkB;QAChC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;QACnD,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAClE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;CACF"}

package/lib/qa-tools/activation-detector.js

@@ -0,0 +1,53 @@
+/** The skill-loader tool whose successful result may unlock the QA tools. */
+const SKILL_TOOL = "skill";
+/** The canonical value `skill` returns: the loaded skill's identity. */
+function loadedSkillName(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const name = value.name;
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * Turns a successful QA skill load into an activation request.
+ *
+ * The trigger is the authoritative `tools/result` of the built-in `skill` tool,
+ * not the model's attempt and not the rendered conversation text: a refused,
+ * unknown, or cancelled skill load reaches this listener as an error result and
+ * activates nothing.
+ */
+export class QaToolActivationDetector {
+    ctx;
+    options;
+    dispose;
+    constructor(ctx, options) {
+        this.ctx = ctx;
+        this.options = options;
+        this.dispose = ctx.on("tools/result", (exec, result) => {
+            this.observe(exec, result);
+        }, { global: true });
+    }
+    observe(exec, result) {
+        if (exec.name !== SKILL_TOOL)
+            return;
+        if (result.isError)
+            return;
+        const agent = exec.agent;
+        if (agent === undefined)
+            return;
+        if (!this.options.isManagedAgent(agent))
+            return;
+        if (loadedSkillName(result.value) !== this.options.activationSkill)
+            return;
+        this.options.logger.info("qa-tools.activation-requested", {
+            agentId: String(agent.id),
+            skill: this.options.activationSkill,
+        });
+        // The skill result itself stays authoritative: a failed attachment is
+        // reported here and never rewritten into a skill failure.
+        this.options.manager.activate(agent, "skill");
+    }
+    disposeListeners() {
+        this.dispose();
+    }
+}
+//# sourceMappingURL=activation-detector.js.map

package/lib/qa-tools/activation-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-detector.js","sourceRoot":"","sources":["../../src/qa-tools/activation-detector.ts"],"names":[],"mappings":"AAKA,6EAA6E;AAC7E,MAAM,UAAU,GAAG,OAAO,CAAC;AAE3B,wEAAwE;AACxE,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,IAAI,GAAI,KAAiC,CAAC,IAAI,CAAC;IACrD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAwB;IAIhB,GAAG;IACH,OAAO;IAJT,OAAO,CAAa;IAErC,YACmB,GAAY,EACZ,OAAwC;mBADxC,GAAG;uBACH,OAAO;QAExB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,EAAE,CACnB,cAAc,EACd,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACf,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC,EACD,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB,CAAC;IACJ,CAAC;IAEO,OAAO,CACb,IAAuD,EACvD,MAA+D;QAE/D,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO;QACrC,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAChC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC;YAAE,OAAO;QAChD,IAAI,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,eAAe;YAAE,OAAO;QAE3E,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE;YACxD,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe;SACpC,CAAC,CAAC;QACH,sEAAsE;QACtE,0DAA0D;QAC1D,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,gBAAgB;QACd,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/lib/qa-tools/activation-manager.js

@@ -0,0 +1,111 @@
+import { assertValidQaToolCatalog } from "./catalog.js";
+/**
+ * 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 class QaToolActivationManager {
+    options;
+    states = new WeakMap();
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * 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, origin) {
+        const current = this.states.get(agent);
+        if (current !== undefined && current.status !== "inactive") {
+            return { status: "already-active" };
+        }
+        const state = {
+            status: "activating",
+            disposers: [],
+        };
+        this.states.set(agent, state);
+        const catalog = this.options.catalog;
+        let toolName = "(preflight)";
+        try {
+            assertValidQaToolCatalog(catalog);
+            // Called through the loaded tools object: the registry method uses
+            // `this` to pick the calling scope's layer.
+            const tools = agent.ctx.tools;
+            for (const descriptor of catalog) {
+                toolName = descriptor.definition.name;
+                state.disposers.push(tools.register(descriptor.definition));
+            }
+            state.status = "active";
+            state.catalogVersion = this.options.catalogVersion;
+        }
+        catch (error) {
+            this.rollback(state);
+            this.states.delete(agent);
+            this.options.logger.error("qa-tools.activation-failed", {
+                agentId: String(agent.id),
+                origin,
+                tool: toolName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return { status: "failed", error };
+        }
+        this.options.logger.info("qa-tools.activated", {
+            agentId: String(agent.id),
+            origin,
+            tools: state.disposers.length,
+            catalog: this.options.catalogVersion,
+        });
+        return { status: "activated", count: state.disposers.length };
+    }
+    /** Whether this agent currently has the QA tools registered. */
+    isActive(agent) {
+        return this.states.get(agent)?.status === "active";
+    }
+    /** Names registered on this agent; the admission guard evaluates this per call. */
+    activeToolNames(agent) {
+        if (!this.isActive(agent))
+            return [];
+        return this.options.catalog.map((descriptor) => descriptor.definition.name);
+    }
+    /**
+     * 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) {
+        const state = this.states.get(agent);
+        if (state === undefined)
+            return;
+        this.rollback(state);
+        this.states.delete(agent);
+        this.options.logger.debug("qa-tools.disposed", {
+            agentId: String(agent.id),
+        });
+    }
+    /** Dispose in reverse registration order, containing individual failures. */
+    rollback(state) {
+        state.status = "inactive";
+        state.catalogVersion = undefined;
+        for (const dispose of state.disposers.splice(0).reverse()) {
+            try {
+                dispose();
+            }
+            catch (error) {
+                this.options.logger.warn("qa-tools.dispose-failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=activation-manager.js.map

package/lib/qa-tools/activation-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-manager.js","sourceRoot":"","sources":["../../src/qa-tools/activation-manager.ts"],"names":[],"mappings":"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"}

package/lib/qa-tools/catalog.js

@@ -0,0 +1,108 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+/**
+ * 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 const QA_TOOL_CATALOG_VERSION = "1";
+function createSelfcheckTool(deps) {
+    return defineTool({
+        name: "qa_tools_selfcheck",
+        description: "Report whether the QA tool set is active for this agent and which QA tools are registered. Use it to diagnose a task that seems to be missing a QA capability.",
+        parameters: {
+            action: {
+                type: "string",
+                required: true,
+                enum: ["status", "catalog"],
+                description: "`status` reports this agent's activation state; `catalog` describes the shipped QA tool catalog.",
+            },
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    catalogVersion: { type: "string", required: true },
+                    activationMode: { type: "string", required: true },
+                    catalogTools: {
+                        type: "array",
+                        required: true,
+                        items: { type: "string" },
+                    },
+                    activeTools: {
+                        type: "array",
+                        required: true,
+                        items: { type: "string" },
+                    },
+                    active: { type: "boolean", required: true },
+                    skillLoaded: { type: "boolean", required: true },
+                },
+            },
+            render: (args, value) => {
+                const active = value.active === true;
+                const tools = Array.isArray(value.activeTools) ? value.activeTools : [];
+                const text = args.action === "catalog"
+                    ? `QA tool catalog ${String(value.catalogVersion)} (mode ${String(value.activationMode)}): ${tools.join(", ") || "(empty)"}.`
+                    : active
+                        ? `QA tools are active (catalog ${String(value.catalogVersion)}): ${tools.join(", ") || "(empty)"}.`
+                        : `QA tools are inactive (catalog ${String(value.catalogVersion)}, skill loaded: ${String(value.skillLoaded)}).`;
+                return [{ type: "text", text }];
+            },
+        },
+        execute: async (args, exec) => {
+            const agent = exec.agent;
+            const activeTools = agent === undefined ? [] : deps.activeTools(agent);
+            return {
+                catalogVersion: deps.catalogVersion,
+                activationMode: deps.activationMode,
+                catalogTools: [...deps.catalogTools()],
+                activeTools: [...activeTools],
+                active: activeTools.length > 0,
+                skillLoaded: agent === undefined ? false : deps.skillLoaded(agent),
+            };
+        },
+    });
+}
+/**
+ * Build the shipped QA tool catalog.
+ *
+ * Side-effect free: constructing it registers nothing with `ctx.tools`. The
+ * activation manager owns every registration.
+ */
+export function createQaToolCatalog(deps) {
+    return [
+        {
+            definition: createSelfcheckTool(deps),
+            group: "diagnostics",
+            tags: ["activation", "diagnostics"],
+        },
+    ];
+}
+/** QA tool names, in catalog order; the admission gate treats them as dynamic. */
+export function qaToolNames(catalog) {
+    return catalog.map((descriptor) => descriptor.definition.name);
+}
+/**
+ * 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 function assertValidQaToolCatalog(catalog) {
+    const seen = new Set();
+    for (const descriptor of catalog) {
+        const name = descriptor.definition.name;
+        if (typeof name !== "string" || name.length === 0) {
+            throw new Error("QA tool catalog contains a tool without a name");
+        }
+        if (seen.has(name)) {
+            throw new Error(`QA tool catalog contains duplicate tool name "${name}"`);
+        }
+        seen.add(name);
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/lib/qa-tools/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/qa-tools/catalog.ts"],"names":[],"mappings":"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"}

package/lib/qa-tools/durable-marker.js

@@ -0,0 +1,115 @@
+/**
+ * The durable activation marker, read back from the session log.
+ *
+ * The marker is not an event of its own. `qa-surface` deliberately appends no
+ * custom session type: a reader that does not mount this plugin refuses a log
+ * containing an unknown non-`ignorable` type, which would make every activated
+ * session unreadable in a plain DSH deployment. Instead the activation is
+ * derived from the `skill` tool call the model already made — a standard
+ * `tool/call` paired with a successful `tool/result`, both of which every
+ * harness build understands and neither of which this plugin writes.
+ *
+ * Consequence: restoration trusts the same fact the live detector does, and a
+ * deployment that drops the `skill` tool cannot restore. That is the correct
+ * trade — the tool is an operator's deliberate grant, and the log stays
+ * portable.
+ */
+/** Rendered `skill` result prefix emitted by `@deepseek-ai/dsh-tool-skill`. */
+const SKILL_CONTENT = /<skill_content name="([^"]*)">/u;
+/** The skill-loader tool whose successful result is the activation marker. */
+const SKILL_TOOL = "skill";
+/** `tool/call` data: the tool name and the call id its result will carry. */
+function toolCallData(data) {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const record = data;
+    return record.name === SKILL_TOOL && typeof record.callId === "string"
+        ? { callId: record.callId }
+        : undefined;
+}
+/** Every text fragment nested under a model content value, at any depth. */
+function collectTexts(value, into) {
+    if (typeof value === "string") {
+        into.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectTexts(item, into);
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        return;
+    const record = value;
+    if (typeof record.text === "string")
+        into.push(record.text);
+    if (Array.isArray(record.content))
+        collectTexts(record.content, into);
+}
+/**
+ * Read one `tool/result` event: the call it answers, the text it carried, and
+ * whether it failed. Text is collected recursively because a tool result wraps
+ * its blocks in a `tool_result` block whose own `content` holds the text the
+ * model saw.
+ */
+function resultBlocks(data) {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const message = data.message;
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const content = message.content;
+    if (!Array.isArray(content))
+        return undefined;
+    const callIds = [];
+    const texts = [];
+    let isError = false;
+    for (const block of content) {
+        if (typeof block !== "object" || block === null)
+            continue;
+        const record = block;
+        if (typeof record.callId === "string")
+            callIds.push(record.callId);
+        if (record.isError === true)
+            isError = true;
+        collectTexts(record.content, texts);
+    }
+    return { callIds, texts, isError };
+}
+/**
+ * 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 function sessionLoadedSkill(session, skillName) {
+    const skillCalls = new Set();
+    for (const event of session.snapshotEvents()) {
+        if (event.type === "tool/call") {
+            const call = toolCallData(event.data);
+            if (call !== undefined)
+                skillCalls.add(call.callId);
+            continue;
+        }
+        if (event.type !== "tool/result")
+            continue;
+        const blocks = resultBlocks(event.data);
+        if (blocks === undefined || blocks.isError)
+            continue;
+        if (!blocks.callIds.some((callId) => skillCalls.has(callId)))
+            continue;
+        for (const text of blocks.texts) {
+            if (SKILL_CONTENT.exec(text)?.[1] === skillName)
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=durable-marker.js.map

package/lib/qa-tools/durable-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-marker.js","sourceRoot":"","sources":["../../src/qa-tools/durable-marker.ts"],"names":[],"mappings":"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"}

package/lib/qa-tools/index.js

@@ -0,0 +1,83 @@
+import { QaToolActivationManager } from "./activation-manager.js";
+import { QaToolActivationDetector } from "./activation-detector.js";
+import { createQaToolCatalog, QA_TOOL_CATALOG_VERSION } from "./catalog.js";
+import { sessionLoadedSkill } from "./durable-marker.js";
+import { QaToolActivationLifecycle } from "./lifecycle.js";
+/**
+ * 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 class QaTools {
+    ctx;
+    options;
+    manager;
+    detector;
+    lifecycle;
+    catalogTools;
+    constructor(ctx, options) {
+        this.ctx = ctx;
+        this.options = options;
+        // The self-check tool answers about whichever agent calls it, so the
+        // catalog is built before any agent exists and resolves `exec.agent` at
+        // execution time.
+        const catalog = createQaToolCatalog({
+            catalogVersion: QA_TOOL_CATALOG_VERSION,
+            activationMode: options.activationMode,
+            catalogTools: () => this.catalogTools,
+            activeTools: (agent) => this.manager.activeToolNames(agent),
+            skillLoaded: (agent) => sessionLoadedSkill(agent.session, options.activationSkill),
+        });
+        this.catalogTools = catalog.map((entry) => entry.definition.name);
+        this.manager = new QaToolActivationManager({
+            catalog,
+            catalogVersion: QA_TOOL_CATALOG_VERSION,
+            logger: options.logger,
+        });
+        this.detector = new QaToolActivationDetector(ctx, {
+            manager: this.manager,
+            logger: options.logger,
+            activationSkill: options.activationSkill,
+            isManagedAgent: (agent) => this.isManagedAgent(agent),
+        });
+        this.lifecycle = new QaToolActivationLifecycle(ctx, {
+            manager: this.manager,
+            logger: options.logger,
+            isManagedAgent: (agent) => this.isManagedAgent(agent),
+            dynamicActivation: options.dynamicActivation,
+            activationSkill: options.activationSkill,
+        });
+        if (options.activationPresets.length === 0 &&
+            this.catalogTools.length > 0) {
+            options.logger.warn("qa-tools.unscoped", {
+                hint: "tools.activationPresets is empty: any composed agent can unlock the QA tools",
+            });
+        }
+    }
+    /** Names currently registered on one agent; the admission guard reads this per call. */
+    activeToolNames(agent) {
+        return this.manager.activeToolNames(agent);
+    }
+    dispose() {
+        this.detector.disposeListeners();
+        this.lifecycle.dispose();
+    }
+    /**
+     * 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.
+     */
+    isManagedAgent(agent) {
+        const presets = this.options.activationPresets;
+        if (presets.length === 0)
+            return true;
+        const preset = agent.session?.header?.agentPreset;
+        return preset !== undefined && presets.includes(preset);
+    }
+}
+//# sourceMappingURL=index.js.map