@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

package/lib/provenance/reported.js

@@ -1,20 +1,33 @@
-import { canonicalizeUrl, canonicalizeWorkspacePath } from "./normalize.js";
+import { canonicalizeUrl, canonicalizeWorkspacePath, unwrapSourceTarget, } from "./normalize.js";
 function fallbackTitle(value) {
     return value.split(/[\\/]/u).at(-1) || value;
 }
 /** Normalize a source explicitly reported by a delegated provider. */
-export function normalizeReportedSource(source, origin, workspaceRoot, urlOptions = {}) {
-    const title = source.title.trim();
+export function normalizeReportedSource(source, origin, workspaceRoot, urlOptions = {}, options = {}) {
+    const validate = options.validate ?? true;
+    const rawTitle = source.title.trim();
+    if (rawTitle === "" && validate)
+        return null;
+    const canonicalPath = source.path === undefined
+        ? ""
+        : canonicalizeWorkspacePath(source.path, workspaceRoot);
+    const canonicalUri = source.uri === undefined
+        ? undefined
+        : canonicalizeUrl(source.uri, urlOptions);
+    // An address the normalizer empties out is no address at all. A URL it
+    // refuses to parse survives verbatim only without validation, so the model's
+    // own wording still reaches the list.
+    const path = canonicalPath === "" ? undefined : canonicalPath;
+    const uri = canonicalUri ??
+        (validate ? undefined : unwrapSourceTarget(source.uri ?? "") || undefined);
+    const title = rawTitle === "" ? fallbackTitle(path ?? uri ?? "") : rawTitle;
     if (title === "")
         return null;
-    if (source.path !== undefined) {
-        const path = canonicalizeWorkspacePath(source.path, workspaceRoot);
-        if (path === "")
-            return null;
+    if (path !== undefined) {
         return {
             id: `file:${path}`,
             kind: source.kind === "code" ? "code" : "file",
-            title: title || fallbackTitle(path),
+            title,
             path,
             ...(source.snippet === undefined ? {} : { snippet: source.snippet }),
             locations: source.locations?.map((location) => ({
@@ -27,10 +40,7 @@ export function normalizeReportedSource(source, origin, workspaceRoot, urlOption
             ...(source.metadata === undefined ? {} : { metadata: source.metadata }),
         };
     }
-    if (source.uri !== undefined) {
-        const uri = canonicalizeUrl(source.uri, urlOptions);
-        if (uri === null)
-            return null;
+    if (uri !== undefined) {
         return {
             id: source.kind === "jira"
                 ? `jira:${source.locations?.[0]?.jiraKey ?? uri}`
@@ -48,6 +58,21 @@ export function normalizeReportedSource(source, origin, workspaceRoot, urlOption
             ...(source.metadata === undefined ? {} : { metadata: source.metadata }),
         };
     }
+    // Reached only with validation off: the model reported a source it can
+    // describe but not address, so the title is the whole identity.
+    if (!validate) {
+        return {
+            id: `reported:${source.kind}:${title}`,
+            kind: source.kind,
+            title,
+            ...(source.snippet === undefined ? {} : { snippet: source.snippet }),
+            locations: source.locations ?? [],
+            evidence: "reported",
+            origins: [origin],
+            score: 80,
+            ...(source.metadata === undefined ? {} : { metadata: source.metadata }),
+        };
+    }
     return null;
 }
 //# sourceMappingURL=reported.js.map

package/lib/provenance/reported.js.map

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

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":"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"}

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":"AAGA,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAuBxD;;;;;;;;GAQG;AACH,MAAM,OAAO,uBAAuB;IAGL,OAAO;IAFnB,MAAM,GAAG,IAAI,OAAO,EAAgC,CAAC;IAEtE,YAA6B,OAAuC;uBAAvC,OAAO;IAAmC,CAAC;IAExE;;;;;;;;;OASG;IACH,QAAQ,CACN,KAAY,EACZ,MAA8B;QAE9B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC3D,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QACtC,CAAC;QAED,MAAM,KAAK,GAA0B;YACnC,MAAM,EAAE,YAAY;YACpB,SAAS,EAAE,EAAE;SACd,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAE9B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QACrC,IAAI,QAAQ,GAAG,aAAa,CAAC;QAC7B,IAAI,CAAC;YACH,wBAAwB,CAAC,OAAO,CAAC,CAAC;YAClC,mEAAmE;YACnE,4CAA4C;YAC5C,MAAM,KAAK,GAAI,KAAiC,CAAC,GAAG,CAAC,KAAK,CAAC;YAC3D,KAAK,MAAM,UAAU,IAAI,OAAO,EAAE,CAAC;gBACjC,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;gBACtC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC;YACxB,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE;gBACtD,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM;gBACN,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE;YAC7C,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM;YACN,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc;SACrC,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;IAChE,CAAC;IAED,gEAAgE;IAChE,QAAQ,CAAC,KAAY;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC;IACrD,CAAC;IAED,mFAAmF;IACnF,eAAe,CAAC,KAAY;QAC1B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,KAAY;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAChC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE;YAC7C,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;SAC1B,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IACrE,QAAQ,CAAC,KAA4B;QAC3C,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC;QAC1B,KAAK,CAAC,cAAc,GAAG,SAAS,CAAC;QACjC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YAC1D,IAAI,CAAC;gBACH,OAAO,EAAE,CAAC;YACZ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE;oBAClD,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

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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"}