@wardby/cli 0.2.1 → 0.4.0

package/dist/core/scheduler.d.ts

@@ -9,6 +9,7 @@
 import type { Agent } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
 import { type DispatchDb } from "./dispatch.js";
+import type { SelfDefectSink } from "./self-defects.js";
 export type SchedulerDb = DispatchDb;
 /**
  * Per spec: "Executor throws synchronously on start → the run is marked
@@ -25,7 +26,7 @@ export declare function findDueCandidates(db: Pick<SchedulerDb, "agent">, now: D
  * Returns the new run's id, or null if the agent wasn't (or is no longer)
  * due, or another tick already holds its row lock.
  */
-export declare function claimDueRun(db: SchedulerDb, executor: Executor, agentId: string, now: Date): Promise<string | null>;
+export declare function claimDueRun(db: SchedulerDb, executor: Executor, agentId: string, now: Date, selfDefects?: SelfDefectSink): Promise<string | null>;
 export interface SchedulerOptions {
     executor: Executor;
     db?: SchedulerDb;
@@ -39,6 +40,8 @@ export interface SchedulerOptions {
      * failing hook cannot stop scheduled agents from firing.
      */
     onLeaderTick?: () => Promise<void>;
+    /** Files a self-defect when a scheduled run's executor fails to start it. Optional. */
+    selfDefects?: SelfDefectSink;
 }
 export interface SchedulerHandle {
     stop(): void;

package/dist/core/scheduler.js

@@ -39,11 +39,12 @@ export async function findDueCandidates(db, now) {
  * Returns the new run's id, or null if the agent wasn't (or is no longer)
  * due, or another tick already holds its row lock.
  */
-export async function claimDueRun(db, executor, agentId, now) {
+export async function claimDueRun(db, executor, agentId, now, selfDefects) {
     const dispatched = await dispatchRun({
         db,
         executor,
         agentId,
+        selfDefects,
         trigger: "scheduled",
         now,
         lockAgent: true,
@@ -88,7 +89,7 @@ export function startScheduler(options) {
         const due = await findDueCandidates(db, now());
         for (const agent of due) {
             try {
-                const runId = await claimDueRun(db, options.executor, agent.id, now());
+                const runId = await claimDueRun(db, options.executor, agent.id, now(), options.selfDefects);
                 if (runId) {
                     log(`firing agent "${agent.name}" -> run ${runId}`);
                 }

package/dist/core/secrets.d.ts

@@ -26,14 +26,23 @@ export declare function listSecrets(ownerId: string, db: PrismaClient): Promise<
  *  (`secrets.get(boundName)`). Defaults to the secret's own name. */
 export declare function attachSecret(agentId: string, name: string, ownerId: string, db: PrismaClient, boundName?: string): Promise<void>;
 /** Detaches by point-of-use name — the pair (agentId, boundName) uniquely
- *  identifies the edge; agent ownership is enforced by the caller. */
-export declare function detachSecret(agentId: string, boundName: string, db: PrismaClient): Promise<void>;
+ *  identifies the edge — falling back to the secret's own name when no edge
+ *  has that point-of-use name, since a secret attached under an alias is
+ *  otherwise easy to "detach" by its real name without effect. Returns how
+ *  many edges were removed; agent ownership is enforced by the caller. */
+export declare function detachSecret(agentId: string, name: string, db: PrismaClient): Promise<number>;
 export declare function deleteSecret(secretId: string, db: PrismaClient): Promise<void>;
 /**
  * Decrypt-on-demand: only the ONE secret actually requested by name is
  * decrypted, never the agent's whole attached set eagerly — a lookup
  * that returns nothing (unattached name) is indistinguishable from one
  * that was never created, both `undefined`.
+ *
+ * Owner rule (resource-sharing grants spec §3.4.1): a binding resolves only
+ * while the secret's owner is the agent's CURRENT owner, both non-null. A
+ * binding written before that rule, left behind by make_owner, or on an
+ * owner-less agent behaves exactly like an unattached name, so one owner's
+ * secret never reaches another owner's agent (A2/S2-2, R2-1).
  */
 export declare function buildSecretsAccessor(agentId: string, cipher: SecretCipher, db: Pick<PrismaClient, "agentSecret"> & Partial<Pick<PrismaClient, "$queryRaw">>): SecretsAccessor;
 /**

package/dist/core/secrets.js

@@ -41,9 +41,16 @@ export async function attachSecret(agentId, name, ownerId, db, boundName = name)
     await db.agentSecret.create({ data: { agentId, secretId: secret.id, boundName } });
 }
 /** Detaches by point-of-use name — the pair (agentId, boundName) uniquely
- *  identifies the edge; agent ownership is enforced by the caller. */
-export async function detachSecret(agentId, boundName, db) {
-    await db.agentSecret.deleteMany({ where: { agentId, boundName } });
+ *  identifies the edge — falling back to the secret's own name when no edge
+ *  has that point-of-use name, since a secret attached under an alias is
+ *  otherwise easy to "detach" by its real name without effect. Returns how
+ *  many edges were removed; agent ownership is enforced by the caller. */
+export async function detachSecret(agentId, name, db) {
+    const byBoundName = await db.agentSecret.deleteMany({ where: { agentId, boundName: name } });
+    if (byBoundName.count > 0)
+        return byBoundName.count;
+    const bySecretName = await db.agentSecret.deleteMany({ where: { agentId, secret: { name } } });
+    return bySecretName.count;
 }
 export async function deleteSecret(secretId, db) {
     await db.secret.delete({ where: { id: secretId } });
@@ -53,16 +60,25 @@ export async function deleteSecret(secretId, db) {
  * decrypted, never the agent's whole attached set eagerly — a lookup
  * that returns nothing (unattached name) is indistinguishable from one
  * that was never created, both `undefined`.
+ *
+ * Owner rule (resource-sharing grants spec §3.4.1): a binding resolves only
+ * while the secret's owner is the agent's CURRENT owner, both non-null. A
+ * binding written before that rule, left behind by make_owner, or on an
+ * owner-less agent behaves exactly like an unattached name, so one owner's
+ * secret never reaches another owner's agent (A2/S2-2, R2-1).
  */
 export function buildSecretsAccessor(agentId, cipher, db) {
     return {
         async get(name) {
             boundedString(name, 1024);
             if (db.$queryRaw) {
+                // NULL-safe: "=" is never true when either owner is NULL.
                 const rows = await db.$queryRaw `
           SELECT CASE WHEN octet_length(s."ciphertext") <= 262144 THEN s."ciphertext" ELSE NULL END AS "ciphertext"
-          FROM "Secret" s JOIN "AgentSecret" a ON a."secretId" = s."id"
-          WHERE a."agentId" = ${agentId} AND a."boundName" = ${name} LIMIT 1`;
+          FROM "Secret" s
+          JOIN "AgentSecret" a ON a."secretId" = s."id"
+          JOIN "Agent" g ON g."id" = a."agentId"
+          WHERE a."agentId" = ${agentId} AND a."boundName" = ${name} AND s."ownerId" = g."ownerId" LIMIT 1`;
                 if (!rows.length)
                     return undefined;
                 if (rows[0].ciphertext === null)
@@ -72,10 +88,13 @@ export function buildSecretsAccessor(agentId, cipher, db) {
             // Lightweight provider doubles use the same post-read bound; production Prisma filters in SQL.
             const attachment = await db.agentSecret.findFirst({
                 where: { agentId, boundName: name },
-                include: { secret: true },
+                include: { secret: true, agent: { select: { ownerId: true } } },
             });
             if (!attachment)
                 return undefined;
+            const owner = attachment.agent.ownerId;
+            if (owner === null || attachment.secret.ownerId !== owner)
+                return undefined;
             boundedString(attachment.secret.ciphertext, 256 * 1024);
             return cipher.decrypt(attachment.secret.ciphertext);
         },

package/dist/core/self-defects.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Self-defects: when a run of an opted-in agent (Agent.defectProjectKey +
+ * defectIssueType) ends failed, lost or budget_exhausted, the control plane
+ * (no model involved) files a defect for it through fileIssue, deduped by a
+ * structural fingerprint so a recurring failure becomes "seen again" comments
+ * on one issue rather than a new issue per run.
+ *
+ *   fingerprint  self:<agentId>:<status>:<category>
+ *   category     CodingRun.failureCategory, else the leading `code:` token of
+ *                Run.error, else "unknown" — only ever a closed-shape token
+ *                (lower-case letters/underscore), never the error's free text
+ *
+ * Fails closed: the agent needs a live write link to defectProjectKey whose
+ * creatableIssueTypes includes defectIssueType; otherwise it logs and skips.
+ * Self-defects are not counted against the link's maxNewIssuesPerRun: that cap
+ * bounds what a run's model may create, while this is a control-plane action
+ * whose volume the fingerprint dedupe already bounds (one open issue per
+ * agent/status/category).
+ *
+ * Filed by whichever write made the run's row terminal (its update count says so, so a run files once): the
+ * runner, the container store, the reconciler, the coding queue's timeout, a failed executor start
+ * (markRunFailedFromExecutorError) and DBOS recovery's mark-failed.
+ *
+ * Best effort and never throws. No recursion: this is only ever called after a
+ * run's row is final, outside any run, and a failure to file only logs — it
+ * never fails a run, so it can never trigger another filing.
+ */
+import type { PrismaClient } from "#prisma";
+import { type IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+import { type FileIssueInput, type FileIssueResult } from "./issue-dedupe.js";
+/** Run statuses that file a defect; succeeded, cancelled and refused never do. */
+export declare const SELF_DEFECT_STATUSES: ReadonlySet<string>;
+/** How long a caller waits for the filing; past this it carries on in the background (and still only logs). */
+export declare const SELF_DEFECT_WAIT_MS = 15000;
+export type SelfDefectDb = Pick<PrismaClient, "agent" | "agentIssueProject" | "codingRun" | "$transaction">;
+/** The finished run, as its final row has it. */
+export interface SelfDefectRun {
+    id: string;
+    agentId: string;
+    status: string;
+    error: string | null;
+    finishedAt: Date | null;
+}
+export interface SelfDefectOptions {
+    /** Injected for tests; defaults to issue-dedupe's fileIssue on `db`. */
+    fileIssue?: (input: FileIssueInput) => Promise<FileIssueResult>;
+    waitMs?: number;
+}
+/**
+ * Where a write that ends a run files its self-defect: the database to read the run and file through, and the
+ * configured issue trackers. Absent, or with no tracker configured, the write files nothing and makes no extra query.
+ */
+export interface SelfDefectSink {
+    db: SelfDefectDb & Pick<PrismaClient, "run">;
+    issueTrackers?: IssueTrackerRegistry;
+    /** Injected for tests; the wait defaults to SELF_DEFECT_SHORT_WAIT_MS. */
+    options?: SelfDefectOptions;
+}
+/** The bound for callers on a dispatch, queue or executor path: past it the filing carries on detached. */
+export declare const SELF_DEFECT_SHORT_WAIT_MS = 2000;
+/** True when at least one issue tracker is configured (no Jira site configured yields an empty registry). */
+export declare function hasIssueTrackers(trackers: IssueTrackerRegistry | undefined): trackers is IssueTrackerRegistry;
+/**
+ * The leading `code:` token of a run error (lower-cased) when it is a safe category (CATEGORY_PATTERN), else
+ * "unknown". Never any of the free text after it.
+ */
+export declare function errorClass(error: string | null | undefined): string;
+export declare function selfDefectFingerprint(agentId: string, status: string, category: string): string;
+/**
+ * Files (or re-sights) the defect for a finished run. Resolves to the filing's
+ * result, or null when nothing was filed (not a filing status, not opted in,
+ * no live link, an error, or still in flight after `waitMs`). Never throws.
+ */
+export declare function fileSelfDefect(db: SelfDefectDb, trackers: IssueTrackerRegistry | undefined, run: SelfDefectRun, opts?: SelfDefectOptions): Promise<FileIssueResult | null>;
+/**
+ * For a write that just made `runId` terminal (its update count said so, so this files once): reads the final row
+ * and files its self-defect, waiting at most SELF_DEFECT_SHORT_WAIT_MS. No-op, with no query, without a configured
+ * tracker. Never throws.
+ */
+export declare function fileSelfDefectForRun(sink: SelfDefectSink | undefined, runId: string): Promise<FileIssueResult | null>;

package/dist/core/self-defects.js

@@ -0,0 +1,180 @@
+import { agentFooter } from "../providers/issue-tracker/jira.js";
+import { ISSUE_TRACKER_PROVIDERS, } from "../providers/issue-tracker/types.js";
+import { fileIssue } from "./issue-dedupe.js";
+import { propertyKey } from "./issue-tracker-tools.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "self-defects" });
+/** Run statuses that file a defect; succeeded, cancelled and refused never do. */
+export const SELF_DEFECT_STATUSES = new Set(["failed", "lost", "budget_exhausted"]);
+/** How long a caller waits for the filing; past this it carries on in the background (and still only logs). */
+export const SELF_DEFECT_WAIT_MS = 15_000;
+const SUMMARY_MAX_LENGTH = 255;
+/**
+ * What a category may look like to be published in the issue and fingerprint: lower-case letters and underscores,
+ * at most 32. No digits, dots or dashes, so secret-shaped (ghp_…, sk-ant-…), host-shaped (db.internal.corp) and
+ * id-shaped (run-8f3a…) prefixes never reach Jira and fingerprints stay a small closed set.
+ */
+const CATEGORY_PATTERN = /^[a-z][a-z_]{0,31}$/;
+/** The bound for callers on a dispatch, queue or executor path: past it the filing carries on detached. */
+export const SELF_DEFECT_SHORT_WAIT_MS = 2_000;
+/** True when at least one issue tracker is configured (no Jira site configured yields an empty registry). */
+export function hasIssueTrackers(trackers) {
+    return !!trackers && Object.values(trackers).some(Boolean);
+}
+/**
+ * The leading `code:` token of a run error (lower-cased) when it is a safe category (CATEGORY_PATTERN), else
+ * "unknown". Never any of the free text after it.
+ */
+export function errorClass(error) {
+    const match = /^([^:\s]{1,64}):/.exec(error ?? "");
+    return safeCategory(match?.[1]) ?? "unknown";
+}
+export function selfDefectFingerprint(agentId, status, category) {
+    return `self:${agentId}:${status}:${category}`;
+}
+function safeCategory(value) {
+    const lowered = value?.trim().toLowerCase();
+    return lowered && CATEGORY_PATTERN.test(lowered) ? lowered : null;
+}
+/**
+ * Files (or re-sights) the defect for a finished run. Resolves to the filing's
+ * result, or null when nothing was filed (not a filing status, not opted in,
+ * no live link, an error, or still in flight after `waitMs`). Never throws.
+ */
+export async function fileSelfDefect(db, trackers, run, opts = {}) {
+    if (!SELF_DEFECT_STATUSES.has(run.status) || !trackers)
+        return null;
+    const filing = attempt(db, trackers, run, opts).catch((err) => {
+        log.warn({ err, runId: run.id, agentId: run.agentId }, "could not file the run's self-defect");
+        return null;
+    });
+    const waitMs = opts.waitMs ?? SELF_DEFECT_WAIT_MS;
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            log.warn({ runId: run.id, waitMs }, "self-defect filing still in progress; no longer waiting for it");
+            resolve(null);
+        }, waitMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([filing, timedOut]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * For a write that just made `runId` terminal (its update count said so, so this files once): reads the final row
+ * and files its self-defect, waiting at most SELF_DEFECT_SHORT_WAIT_MS. No-op, with no query, without a configured
+ * tracker. Never throws.
+ */
+export async function fileSelfDefectForRun(sink, runId) {
+    if (!sink || !hasIssueTrackers(sink.issueTrackers))
+        return null;
+    let row;
+    try {
+        row = await sink.db.run.findUnique({
+            where: { id: runId },
+            select: { id: true, agentId: true, status: true, error: true, finishedAt: true },
+        });
+    }
+    catch (err) {
+        log.warn({ err, runId }, "could not read the run to file its self-defect");
+        return null;
+    }
+    if (!row)
+        return null;
+    return fileSelfDefect(sink.db, sink.issueTrackers, row, {
+        waitMs: SELF_DEFECT_SHORT_WAIT_MS,
+        ...sink.options,
+    });
+}
+async function attempt(db, trackers, run, opts) {
+    const configured = ISSUE_TRACKER_PROVIDERS.filter((p) => trackers[p]);
+    if (configured.length === 0)
+        return null;
+    const agent = await db.agent.findUnique({
+        where: { id: run.agentId },
+        select: { id: true, name: true, defectProjectKey: true, defectIssueType: true },
+    });
+    if (!agent?.defectProjectKey || !agent.defectIssueType)
+        return null;
+    const projectKey = agent.defectProjectKey;
+    const issueType = agent.defectIssueType;
+    let tracker;
+    let link;
+    for (const provider of configured) {
+        // Live, read now: an unlink, downgrade or allowlist change since the run started applies here.
+        const row = await db.agentIssueProject.findUnique({
+            where: { agentId_provider_projectKey: { agentId: agent.id, provider, projectKey } },
+            select: {
+                provider: true,
+                projectKey: true,
+                access: true,
+                commentVisibilityRole: true,
+                creatableIssueTypes: true,
+            },
+        });
+        if (!row)
+            continue;
+        const typeAllowed = row.creatableIssueTypes.some((t) => t.trim().toLowerCase() === issueType.trim().toLowerCase());
+        if (row.access !== "write" || !typeAllowed) {
+            log.warn({ runId: run.id, agentId: agent.id, projectKey, access: row.access, typeAllowed }, "self-defects skipped: the agent's link to the defect project is not writable or does not allow the issue type");
+            return null;
+        }
+        tracker = trackers[provider];
+        link = row;
+        break;
+    }
+    if (!tracker || !link) {
+        log.warn({ runId: run.id, agentId: agent.id, projectKey }, "self-defects skipped: no link to the defect project");
+        return null;
+    }
+    let codingCategory = null;
+    try {
+        const coding = await db.codingRun.findUnique({ where: { runId: run.id }, select: { failureCategory: true } });
+        codingCategory = safeCategory(coding?.failureCategory);
+    }
+    catch (err) {
+        log.debug({ err, runId: run.id }, "no coding failure category for the self-defect");
+    }
+    const category = codingCategory ?? errorClass(run.error);
+    const finished = (run.finishedAt ?? new Date()).toISOString();
+    const summary = `wardby agent "${agent.name}": ${run.status}${category === "unknown" ? "" : ` (${category})`}`;
+    const description = [
+        `A run of wardby agent "${agent.name}" ended ${run.status}.`,
+        "",
+        `- Run: ${run.id}`,
+        `- Agent: ${agent.id}`,
+        `- Status: ${run.status}`,
+        `- Failure category: ${category}`,
+        `- Finished: ${finished}`,
+        "",
+        "Filed by wardby itself. The run's error text is not included; see the run in wardby for details.",
+    ].join("\n");
+    const file = opts.fileIssue ?? ((input) => fileIssue({ db }, input));
+    // Not subject to maxNewIssuesPerRun (control plane; dedupe bounds volume), so createAllowed stays at its default.
+    const result = await file({
+        agentId: agent.id,
+        runId: run.id,
+        link,
+        tracker,
+        fingerprint: selfDefectFingerprint(agent.id, run.status, category),
+        create: {
+            issueType,
+            summary: summary.length > SUMMARY_MAX_LENGTH ? `${summary.slice(0, SUMMARY_MAX_LENGTH - 1)}…` : summary,
+            descriptionMarkdown: description,
+            properties: { [propertyKey(agent.id, "self-defect")]: { runId: run.id } },
+        },
+        footerMarkdown: agentFooter(agent.id),
+        seenAgainMarkdown: `Run ${run.id} ended ${run.status} at ${finished}.\n\n${agentFooter(agent.id)}`,
+    });
+    if ("error" in result) {
+        log.warn({ runId: run.id, agentId: agent.id, error: result.error }, "self-defect filing failed");
+    }
+    else {
+        log.info({ runId: run.id, agentId: agent.id, outcome: result.outcome, issueKey: result.issueKey }, "self-defect filed");
+    }
+    return result;
+}

package/dist/core/subagent-memory-tools.d.ts

@@ -4,7 +4,7 @@ import type { AgentMemoryStore } from "../providers/memory/types.js";
 export declare const SUBAGENT_MEMORY_TOOL_NAMES: ReadonlySet<string>;
 export declare const SUBAGENT_MEMORY_GET_TOOL: LoadedTool;
 export declare const PARENT_MEMORY_GET_TOOL: LoadedTool;
-type SubAgentMemoryDb = Pick<PrismaClient, "agentSubAgent" | "run">;
+type SubAgentMemoryDb = Pick<PrismaClient, "agentSubAgent" | "run" | "agent">;
 /** `subagent_memory_get` — callable by a parent, gated by the AgentSubAgent edge itself. */
 export declare function handleSubAgentMemoryGet(argsJson: string, callingAgentId: string, db: SubAgentMemoryDb, memory: AgentMemoryStore): Promise<string>;
 /**

package/dist/core/subagent-memory-tools.js

@@ -4,9 +4,9 @@
  * sandboxed, the same treatment memory-tools.ts gives the own-memory
  * built-ins:
  *
- * - subagent_memory_get: a parent can always read a declared child's
- *   memory. The AgentSubAgent edge itself is the grant -- no reference
- *   needed each time.
+ * - subagent_memory_get: a parent can read a declared child's memory when
+ *   both have the same owner. The AgentSubAgent edge itself is the grant --
+ *   no reference needed each time; a cross-owner edge never carries it.
  * - parent_memory_get: a child can read a specific key of its dispatching
  *   parent's memory ONLY when that exact run was handed a grant for that
  *   key at dispatch time (Run.grantedParentMemoryKeys) -- never a standing
@@ -74,6 +74,19 @@ export async function handleSubAgentMemoryGet(argsJson, callingAgentId, db, memo
             message: `No sub-agent is bound to name "${args.boundName}".`,
         });
     }
+    // Memory inspection is owner-level (resource-sharing grants spec §3.4.4):
+    // an edge to another owner's child carries execute, never its memory.
+    // Owners are read live, so a make_owner transfer takes effect at once.
+    const [parent, child] = await Promise.all([
+        db.agent.findUnique({ where: { id: callingAgentId }, select: { ownerId: true } }),
+        db.agent.findUnique({ where: { id: edge.childAgentId }, select: { ownerId: true } }),
+    ]);
+    if (!parent || !child || (parent.ownerId ?? null) !== (child.ownerId ?? null)) {
+        return JSON.stringify({
+            error: "subagent_not_authorized",
+            message: `The "${args.boundName}" sub-agent belongs to another owner; its memory is not readable from here.`,
+        });
+    }
     const content = await memory.get(edge.childAgentId, args.key);
     return JSON.stringify({ content: content ?? null });
 }

package/dist/core/tool-admin.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Updating and deleting a Tool, shared by MCP update_tool/delete_tool (the
+ * owner, over MCP) and `wardby tool update|delete` (the operator, over the
+ * CLI). Each caller brings its own authorization -- MCP is strictly
+ * owner-only and never touches public tools; the operator may change any
+ * tool -- but the attachment rules are the same for both, and are always
+ * judged against the *tool's* owner:
+ *
+ * - An update is refused while the tool is attached to any agent owned by
+ *   someone other than the tool's owner (a public agent counts, unless the
+ *   tool is public too). An attachment's grants hand whatever code the row
+ *   holds to that agent owner's secrets and hosts, and the description
+ *   reaches their model context.
+ * - A delete is refused while any attachment remains; `detach` first removes
+ *   the attachments to the tool owner's own agents (for a public tool, the
+ *   public agents), never anyone else's. The check runs before any detach,
+ *   so a refusal changes nothing.
+ *
+ * Both run in one Serializable transaction, the same isolation as MCP
+ * attach_tool, so an attach that commits between the check and the write
+ * aborts one side instead of letting new code reach a newly attached agent
+ * (pinned in core/prisma-adapter.database.test.ts). That guarantee covers
+ * MCP attach_tool only: `wardby tool attach` and the importer attach with a
+ * plain check-then-upsert, acceptable because both are operator-only.
+ */
+import { Prisma, type PrismaClient, type Tool } from "#prisma";
+export type AttachedAgent = {
+    id: string;
+    name: string;
+    ownerId: string | null;
+};
+export interface ToolChanges {
+    description?: string;
+    paramsZod?: string;
+    code?: string;
+}
+/**
+ * Why a tool change was refused because of its attachments:
+ * - `other_owners`: attached to agents owned by someone other than the
+ *   tool's owner (`agents` lists them; callers decide how much to reveal).
+ * - `needs_detach`: a delete without `detach`, still attached to the tool
+ *   owner's own agents.
+ * - `race`: an attachment committed after the check, and the RESTRICT
+ *   foreign key stopped the delete (`agents` is empty).
+ */
+export declare class ToolAttachedError extends Error {
+    readonly reason: "other_owners" | "needs_detach" | "race";
+    readonly agents: AttachedAgent[];
+    constructor(reason: "other_owners" | "needs_detach" | "race", agents: AttachedAgent[]);
+}
+/** Whether `changes` names at least one field to change. */
+export declare function hasToolChanges(changes: ToolChanges): boolean;
+/**
+ * The row update for `changes`, with jsonSchema re-derived exactly as tool
+ * creation does whenever paramsZod changes, so the cached schema never goes
+ * stale. An invalid paramsZod is returned, not thrown -- the caller reports
+ * it like create_tool does and writes nothing. Run it before the transaction
+ * so a QuickJS compile never holds one open.
+ */
+export declare function prepareToolUpdate(changes: ToolChanges): Promise<{
+    ok: true;
+    data: Prisma.ToolUpdateInput;
+} | {
+    ok: false;
+    errorKind: string;
+    errorMessage: string;
+}>;
+/** The agents `toolId` is attached to, read inside the caller's transaction. */
+export declare function attachedAgents(tx: Pick<Prisma.TransactionClient, "agentTool">, toolId: string): Promise<AttachedAgent[]>;
+/** Refuses (by throwing) unless the caller may change this tool; receives the row read inside the transaction. */
+export type AuthorizeTool = (tool: Tool | null) => void;
+export declare function updateToolGuarded(db: Pick<PrismaClient, "$transaction">, toolId: string, data: Prisma.ToolUpdateInput, authorize: AuthorizeTool): Promise<Tool>;
+/** Deletes the tool and returns the ids of the agents it was detached from. */
+export declare function deleteToolGuarded(db: Pick<PrismaClient, "$transaction">, toolId: string, options: {
+    detach: boolean;
+    authorize: AuthorizeTool;
+}): Promise<string[]>;
+/** One `wardby tool list` line: names are only unique per owner, so the id and owner disambiguate. */
+export declare function formatToolLine(tool: Pick<Tool, "id" | "name" | "description" | "ownerId">): string;
+/** Attached agents for an operator-facing refusal: unlike MCP's, nothing is redacted. */
+export declare function formatAttachedAgents(agents: AttachedAgent[]): string;

package/dist/core/tool-admin.js

@@ -0,0 +1,129 @@
+/**
+ * Updating and deleting a Tool, shared by MCP update_tool/delete_tool (the
+ * owner, over MCP) and `wardby tool update|delete` (the operator, over the
+ * CLI). Each caller brings its own authorization -- MCP is strictly
+ * owner-only and never touches public tools; the operator may change any
+ * tool -- but the attachment rules are the same for both, and are always
+ * judged against the *tool's* owner:
+ *
+ * - An update is refused while the tool is attached to any agent owned by
+ *   someone other than the tool's owner (a public agent counts, unless the
+ *   tool is public too). An attachment's grants hand whatever code the row
+ *   holds to that agent owner's secrets and hosts, and the description
+ *   reaches their model context.
+ * - A delete is refused while any attachment remains; `detach` first removes
+ *   the attachments to the tool owner's own agents (for a public tool, the
+ *   public agents), never anyone else's. The check runs before any detach,
+ *   so a refusal changes nothing.
+ *
+ * Both run in one Serializable transaction, the same isolation as MCP
+ * attach_tool, so an attach that commits between the check and the write
+ * aborts one side instead of letting new code reach a newly attached agent
+ * (pinned in core/prisma-adapter.database.test.ts). That guarantee covers
+ * MCP attach_tool only: `wardby tool attach` and the importer attach with a
+ * plain check-then-upsert, acceptable because both are operator-only.
+ */
+import { Prisma } from "#prisma";
+import { deriveJsonSchema } from "../sandbox/zod-params.js";
+/**
+ * Why a tool change was refused because of its attachments:
+ * - `other_owners`: attached to agents owned by someone other than the
+ *   tool's owner (`agents` lists them; callers decide how much to reveal).
+ * - `needs_detach`: a delete without `detach`, still attached to the tool
+ *   owner's own agents.
+ * - `race`: an attachment committed after the check, and the RESTRICT
+ *   foreign key stopped the delete (`agents` is empty).
+ */
+export class ToolAttachedError extends Error {
+    reason;
+    agents;
+    constructor(reason, agents) {
+        super(`tool_attached_${reason}`);
+        this.reason = reason;
+        this.agents = agents;
+        this.name = "ToolAttachedError";
+    }
+}
+/** Whether `changes` names at least one field to change. */
+export function hasToolChanges(changes) {
+    return changes.description !== undefined || changes.paramsZod !== undefined || changes.code !== undefined;
+}
+/**
+ * The row update for `changes`, with jsonSchema re-derived exactly as tool
+ * creation does whenever paramsZod changes, so the cached schema never goes
+ * stale. An invalid paramsZod is returned, not thrown -- the caller reports
+ * it like create_tool does and writes nothing. Run it before the transaction
+ * so a QuickJS compile never holds one open.
+ */
+export async function prepareToolUpdate(changes) {
+    const data = {
+        ...(changes.description !== undefined ? { description: changes.description } : {}),
+        ...(changes.code !== undefined ? { code: changes.code } : {}),
+    };
+    if (changes.paramsZod !== undefined) {
+        const schemaResult = await deriveJsonSchema(changes.paramsZod);
+        if (!schemaResult.ok) {
+            return { ok: false, errorKind: schemaResult.errorKind, errorMessage: schemaResult.errorMessage };
+        }
+        data.paramsZod = changes.paramsZod;
+        data.jsonSchema = schemaResult.value;
+    }
+    return { ok: true, data };
+}
+/** The agents `toolId` is attached to, read inside the caller's transaction. */
+export async function attachedAgents(tx, toolId) {
+    const rows = await tx.agentTool.findMany({
+        where: { toolId },
+        select: { agent: { select: { id: true, name: true, ownerId: true } } },
+    });
+    return rows.map((row) => row.agent);
+}
+export async function updateToolGuarded(db, toolId, data, authorize) {
+    return db.$transaction(async (tx) => {
+        const tool = await tx.tool.findUnique({ where: { id: toolId } });
+        authorize(tool);
+        const others = (await attachedAgents(tx, toolId)).filter((agent) => agent.ownerId !== tool.ownerId);
+        if (others.length > 0)
+            throw new ToolAttachedError("other_owners", others);
+        return tx.tool.update({ where: { id: toolId }, data });
+    }, { isolationLevel: Prisma.TransactionIsolationLevel.Serializable });
+}
+/** Deletes the tool and returns the ids of the agents it was detached from. */
+export async function deleteToolGuarded(db, toolId, options) {
+    try {
+        return await db.$transaction(async (tx) => {
+            const tool = await tx.tool.findUnique({ where: { id: toolId } });
+            options.authorize(tool);
+            const agents = await attachedAgents(tx, toolId);
+            const own = agents.filter((agent) => agent.ownerId === tool.ownerId);
+            const others = agents.filter((agent) => agent.ownerId !== tool.ownerId);
+            if (others.length > 0)
+                throw new ToolAttachedError("other_owners", others);
+            if (own.length > 0 && !options.detach)
+                throw new ToolAttachedError("needs_detach", own);
+            if (own.length > 0) {
+                await tx.agentTool.deleteMany({ where: { toolId, agentId: { in: own.map((agent) => agent.id) } } });
+            }
+            await tx.tool.delete({ where: { id: toolId } });
+            return own.map((agent) => agent.id);
+        }, { isolationLevel: Prisma.TransactionIsolationLevel.Serializable });
+    }
+    catch (err) {
+        // AgentTool.toolId is ON DELETE RESTRICT: an attachment that raced in
+        // past the check above still stops the delete, as P2003.
+        if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2003") {
+            throw new ToolAttachedError("race", []);
+        }
+        throw err;
+    }
+}
+/** One `wardby tool list` line: names are only unique per owner, so the id and owner disambiguate. */
+export function formatToolLine(tool) {
+    return `${tool.id}  ${tool.name}  owner:${tool.ownerId ?? "public"}  ${tool.description}`;
+}
+/** Attached agents for an operator-facing refusal: unlike MCP's, nothing is redacted. */
+export function formatAttachedAgents(agents) {
+    return agents
+        .map((agent) => `"${agent.name}" (${agent.id}, ${agent.ownerId === null ? "public" : `owner ${agent.ownerId}`})`)
+        .join(", ");
+}