@wardby/cli 0.5.3 → 0.7.0

package/dist/core/error-code.js

@@ -0,0 +1,168 @@
+/**
+ * The code a wardby error message leads with (`some_code` or `some_code: detail`), or undefined.
+ * Worker-safe: the native sandbox worker image ships this module.
+ */
+export function errorCodeOf(message) {
+    return message ? /^([a-z][a-z0-9_]*)(:|$)/.exec(message)?.[1] : undefined;
+}
+/** The longest cause code carried; a longer leading word is not a code. */
+const MAX_CAUSE_CODE_LENGTH = 64;
+/** The code an unexpected error's message leads with, if it is code-shaped (has an underscore) and short enough. */
+export function causeCodeOf(err) {
+    const code = errorCodeOf(err instanceof Error ? err.message : typeof err === "string" ? err : undefined);
+    // Only the code form leaves a boundary: snake_case with an underscore, so a bare word
+    // (which could be a token) never crosses.
+    return code && code.includes("_") && code.length <= MAX_CAUSE_CODE_LENGTH ? code : undefined;
+}
+/**
+ * The only codes that may be shown from an arbitrary error's text (to a worker, or to the model in a
+ * tool result): wardby's own codes that an unexpected error on those paths can lead with. Anything
+ * else, however code-shaped, could be a value from an error's text, so it never crosses.
+ * - coding_execution_not_configured, coding_profile_missing: a coding delegation reaching a process
+ *   that cannot start coding runs (core/deferred-coding.ts, providers/executor/routing.ts).
+ * - message_too_large, message_not_json, message_invalid, unsupported_protocol_version: the native
+ *   worker protocol's own ProtocolError codes (native-worker/protocol.ts).
+ * - invalid_merge_order: dispatchRun's refusal of a bad mergeOrder (core/dispatch.ts).
+ * - coding_worker_image_invalid: a coding worker image that is not pinned by digest
+ *   (providers/executor/container.ts).
+ * - native_sandbox_unavailable: createRun/the router refusing a sandbox-mode agent with no sandbox executor
+ *   (core/runner.ts).
+ * - run_tree_exhausted: dispatchRun refusing a run whose tree budget is spent (core/dispatch.ts).
+ * - secret_in_value, secret_check_unavailable: the datastore and memory write guard refusing a value
+ *   that holds an attached secret's value (core/secret-guard.ts); the code carries only the name of
+ *   the secret, never its value, across the gateway.
+ */
+export const GATEWAY_CAUSE_CODES = new Set([
+    "coding_execution_not_configured",
+    "coding_profile_missing",
+    "message_too_large",
+    "message_not_json",
+    "message_invalid",
+    "unsupported_protocol_version",
+    "invalid_merge_order",
+    "coding_worker_image_invalid",
+    "native_sandbox_unavailable",
+    "run_tree_exhausted",
+    "secret_in_value",
+    "secret_check_unavailable",
+]);
+/**
+ * The codes wardby itself writes as a failed coding or native child run's Run.error (read from the
+ * literals in core/dispatch.ts, core/coding-queue.ts, providers/executor/*, core/run-pricing.ts,
+ * providers/llm/catalog-types.ts and the native sandbox). A parent may be told which of these a
+ * child failed with; any other leading word is not shown. Includes GATEWAY_CAUSE_CODES, and the
+ * container executor's terminal codes: `coding_failure_<category>` for every category
+ * failureCategory files a failure under (providers/executor/container.ts), and
+ * `coding_provider_<class>` for every provider failure class (core/provider-wording.ts).
+ */
+export const CHILD_RUN_FAILURE_CODES = new Set([
+    ...GATEWAY_CAUSE_CODES,
+    "coding_failure_turn_limit",
+    "coding_failure_service_unready",
+    "coding_failure_preflight",
+    "coding_failure_job",
+    "coding_failure_repo_access_unavailable",
+    "coding_failure_repo_access",
+    "coding_failure_github",
+    "coding_failure_protected_path",
+    "coding_failure_continuation_closed",
+    "coding_failure_merge_conflict",
+    "coding_failure_target_merge",
+    "coding_failure_workspace",
+    "coding_failure_budget",
+    "coding_failure_artifact",
+    "coding_failure_cancelled",
+    "coding_failure_executor",
+    "coding_provider_quota",
+    "coding_provider_rate_limited",
+    "coding_provider_unavailable",
+    "coding_provider_rejected",
+    "coding_ambiguous_provisioning",
+    "coding_artifact_duplicate_key",
+    "coding_artifact_invalid_json",
+    "coding_artifact_nesting_limit",
+    "coding_artifact_path_invalid",
+    "coding_artifact_root_invalid",
+    "coding_artifact_size_limit",
+    "coding_budget_exhausted",
+    "coding_capability_exists",
+    "coding_capability_unavailable",
+    "coding_credential_ref_invalid",
+    "coding_credential_reference_invalid",
+    "coding_credential_unavailable",
+    "coding_dispatch_unavailable",
+    "coding_head_ref_invalid",
+    "coding_input_invalid_file",
+    "coding_job_handle_conflict",
+    "coding_job_handle_mismatch",
+    "coding_job_status_unavailable",
+    "coding_output_invalid",
+    "coding_output_missing",
+    "coding_output_run_mismatch",
+    "coding_output_size_limit",
+    "coding_provider_not_configured",
+    "coding_provider_unsupported",
+    "coding_queue_timeout",
+    "coding_recovery_incomplete",
+    "coding_recovery_unavailable",
+    "coding_resource_limits_invalid",
+    "coding_result_missing",
+    "coding_result_run_mismatch",
+    "coding_run_budget_invalid",
+    "coding_run_no_longer_active",
+    "coding_run_not_active",
+    "coding_run_not_found",
+    "coding_run_ownership_invalid",
+    "coding_run_pricing_mismatch",
+    "coding_run_status_invalid",
+    "coding_run_terminal_conflict",
+    "coding_service_catalog_invalid",
+    "coding_service_unready",
+    "coding_services_unsupported",
+    "coding_services_unsupported_launcher",
+    "coding_stream_agent_exited",
+    "coding_stream_failed",
+    "coding_stream_proxy_denied",
+    "coding_stream_proxy_unreachable",
+    "coding_stream_quota_exceeded",
+    "coding_stream_rate_limited",
+    "coding_stream_timeout",
+    "coding_stream_upstream_error",
+    "coding_toolchain_unsupported",
+    "coding_turn_failed",
+    "coding_turn_limit",
+    "coding_workspace_disk_exceeds_limit",
+    "coding_workspace_lost",
+    "model_unavailable",
+    "model_not_allowed",
+    "executor_run_not_found",
+    "run_not_drivable",
+    "ownership_lost",
+    "step_replay_mismatch",
+    "worker_error",
+    "worker_tool_runner_unreachable",
+    "sandbox_dispatch_unavailable",
+    "native_sandbox_capacity",
+    "native_sandbox_deadline_exceeded",
+    "native_sandbox_docker_failed",
+    "native_sandbox_gateway_error",
+    "native_sandbox_gateway_unavailable",
+    "native_sandbox_image_not_pinned",
+    "native_sandbox_invalid_run_id",
+    "native_sandbox_invalid_warm_token",
+    "native_sandbox_isolation_mismatch",
+    "native_sandbox_launch_abandoned",
+    "native_sandbox_network_unenforced",
+    "native_sandbox_platform_unsupported",
+    "native_sandbox_recovery_unavailable",
+    "native_sandbox_requires_catalog",
+    "native_sandbox_warm_delivery_failed",
+    "native_sandbox_worker_exited",
+    "native_sandbox_worker_lost",
+    "native_sandbox_worker_unready",
+]);
+/** The leading code of an arbitrary error or message, only when it is declared in `allowed`. */
+export function declaredCodeOf(err, allowed = GATEWAY_CAUSE_CODES) {
+    const code = causeCodeOf(err);
+    return code && allowed.has(code) ? code : undefined;
+}

package/dist/core/grants.d.ts

@@ -19,14 +19,14 @@ export type ResourceType = keyof typeof LEVELS;
 export type Level<T extends ResourceType = ResourceType> = (typeof LEVELS)[T][number];
 export type Access<T extends ResourceType = ResourceType> = "none" | Level<T> | "owner";
 /**
- * Highest level an "everyone" grant may carry: never write. Everyone-write
- * on an agent would bring back the old public-mutable model (anyone
- * rewriting the prompt of an agent that holds its owner's tools and
- * secrets). Also applied when a stored everyone row is read, so a row
- * written around grant_access can't exceed it either.
+ * Highest level an "everyone" grant may carry. Agents may be public-write
+ * (anyone signed in can edit them) but only while they hold none of their
+ * owner's bindings: see agentOwnerBindings and the guard in grant_access and
+ * the binding tools. Otherwise anyone could rewrite the prompt of an agent
+ * that holds its owner's secrets.
  */
 export declare const EVERYONE_MAX: {
-    readonly agent: "execute";
+    readonly agent: "write";
     readonly tool: "use";
     readonly budget_group: "use";
 };
@@ -84,3 +84,16 @@ export declare function everyoneGrantData(type: ResourceType, resourceId: string
 };
 /** Every resource delete path calls this in the same transaction (no FK on resourceId). */
 export declare function deleteGrantsFor(db: GrantDb, type: ResourceType, resourceId: string): Promise<number>;
+type BindingDb = Pick<PrismaClient, "agentSecret" | "agentDatastore" | "agentRepository" | "agentSubAgent" | "agentTool" | "codingAgentProfile">;
+/**
+ * The owner-only bindings an agent holds, by kind (empty = none). An agent
+ * may be public-write only while this is empty; binding a secret, datastore,
+ * repository, sub-agent or owner-granted tool capability to a public-write
+ * agent is refused for the same reason. A coding profile counts: its
+ * repository is the owner's GitHub access, and the prompt is part of every
+ * coding task.
+ */
+export declare function agentOwnerBindings(db: BindingDb, agentId: string): Promise<string[]>;
+/** True when everyone holds write on the agent. */
+export declare function isPublicWritable(db: GrantDb, agentId: string): Promise<boolean>;
+export {};

package/dist/core/grants.js

@@ -4,13 +4,13 @@ export const LEVELS = {
     budget_group: ["read", "use", "write"],
 };
 /**
- * Highest level an "everyone" grant may carry: never write. Everyone-write
- * on an agent would bring back the old public-mutable model (anyone
- * rewriting the prompt of an agent that holds its owner's tools and
- * secrets). Also applied when a stored everyone row is read, so a row
- * written around grant_access can't exceed it either.
+ * Highest level an "everyone" grant may carry. Agents may be public-write
+ * (anyone signed in can edit them) but only while they hold none of their
+ * owner's bindings: see agentOwnerBindings and the guard in grant_access and
+ * the binding tools. Otherwise anyone could rewrite the prompt of an agent
+ * that holds its owner's secrets.
  */
-export const EVERYONE_MAX = { agent: "execute", tool: "use", budget_group: "use" };
+export const EVERYONE_MAX = { agent: "write", tool: "use", budget_group: "use" };
 /** Types grant_access/revoke_access accept today (Phase 1: agents only). */
 export const SHAREABLE_TYPES = ["agent"];
 export const EVERYONE_KEY = "everyone";
@@ -124,3 +124,52 @@ export async function deleteGrantsFor(db, type, resourceId) {
     const { count } = await db.resourceGrant.deleteMany({ where: { resourceType: type, resourceId } });
     return count;
 }
+/**
+ * The owner-only bindings an agent holds, by kind (empty = none). An agent
+ * may be public-write only while this is empty; binding a secret, datastore,
+ * repository, sub-agent or owner-granted tool capability to a public-write
+ * agent is refused for the same reason. A coding profile counts: its
+ * repository is the owner's GitHub access, and the prompt is part of every
+ * coding task.
+ */
+export async function agentOwnerBindings(db, agentId) {
+    const [secrets, datastores, repositories, subagents, capabilityTools, codingProfiles] = await Promise.all([
+        db.agentSecret.count({ where: { agentId } }),
+        db.agentDatastore.count({ where: { agentId } }),
+        db.agentRepository.count({ where: { agentId } }),
+        db.agentSubAgent.count({ where: { parentAgentId: agentId } }),
+        // The owner's attach_tool stamps its consent even when it grants nothing:
+        // only an attachment that carries a capability counts.
+        db.agentTool.count({
+            where: {
+                agentId,
+                capabilitiesGrantedById: { not: null },
+                NOT: {
+                    allowedSecrets: { equals: [] },
+                    allowedDatastorePrefixes: { equals: [] },
+                    allowedHosts: { equals: [] },
+                    allowedSharedDatastorePrefixes: { equals: {} },
+                },
+            },
+        }),
+        db.codingAgentProfile.count({ where: { agentId } }),
+    ]);
+    return Object.entries({
+        secrets,
+        datastores,
+        repositories,
+        "sub-agents": subagents,
+        "tool capabilities": capabilityTools,
+        "a coding repository": codingProfiles,
+    })
+        .filter(([, count]) => count > 0)
+        .map(([kind]) => kind);
+}
+/** True when everyone holds write on the agent. */
+export async function isPublicWritable(db, agentId) {
+    const row = await db.resourceGrant.findFirst({
+        where: { resourceType: "agent", resourceId: agentId, granteeKey: EVERYONE_KEY },
+        select: { level: true },
+    });
+    return row !== null && atLeast("agent", row.level, "write");
+}

package/dist/core/host-events.d.ts

@@ -5,15 +5,15 @@
  * module decides which agents run. See
  * docs/private/2026-09-25-code-review-host-design.md §6.3.
  */
-import type { PrismaClient } from "#prisma";
+import { type PrismaClient } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
 import type { IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
-import type { HostEvent, ReviewHostRegistry } from "../providers/review-host/types.js";
+import type { CodeReviewHost, HostEvent, ReviewHostRegistry } from "../providers/review-host/types.js";
 import { type OpenSibling } from "./related-pull-requests.js";
 import { type RepoAccessGate } from "./repo-access.js";
 import { type DriftScope } from "../knowledge/relevance.js";
 export type { HostEvent };
-export type HostEventDb = Pick<PrismaClient, "agentRepository" | "deferredReview" | "agent" | "run" | "runHostCheck" | "runHostStatus" | "codingRun" | "task" | "webhook" | "budgetGroup" | "issuePullRequest" | "workItem" | "runAttribution" | "agentIssueProject" | "$transaction" | "$queryRaw">;
+export type HostEventDb = Pick<PrismaClient, "runBudgetEvent" | "agentRepository" | "deferredReview" | "agent" | "run" | "runHostCheck" | "runHostStatus" | "codingRun" | "registryFetch" | "registryAuditRecord" | "task" | "webhook" | "budgetGroup" | "issuePullRequest" | "workItem" | "runAttribution" | "agentIssueProject" | "$transaction" | "$queryRaw">;
 export interface RouteHostEventDeps {
     db: HostEventDb;
     executor: Executor;
@@ -24,6 +24,12 @@ export interface RouteHostEventDeps {
     repoAccess: RepoAccessGate;
     /** Issue trackers for moving/commenting on the issue a closed PR was opened for; absent → pr_closed is ignored. */
     issueTrackers?: IssueTrackerRegistry;
+    /**
+     * False (WARDBY_MENTION_EXPLANATIONS=false): a mention that starts nothing gets no
+     * reply saying why. The reply is a comment anyone who can see the repository reads,
+     * so a deployment may keep what is linked there to itself. Absent = true.
+     */
+    mentionExplanations?: boolean;
 }
 /** What starting a review needs: everything routing needs except the mention handle. */
 export type ReviewStartDeps = Omit<RouteHostEventDeps, "mentionHandle">;
@@ -38,6 +44,7 @@ export interface RouteResult {
     /** Cosmetic work to do after the webhook response is sent (reactions, status comments). */
     followUps: Array<() => Promise<void>>;
 }
+/** A `@app review` outside code: quoting the command in code documents it. */
 export declare function isReviewCommand(body: string, mentionHandle: string): boolean;
 type PushEvent = Extract<HostEvent, {
     kind: "push";
@@ -56,7 +63,7 @@ type ConceptCitationStatus = {
  * commits, so they and the affected concept paths travel as untrusted context.
  * Commit messages and author names are never included.
  */
-export declare function mergeTaskText(event: PushEvent, scope: DriftScope | null, bundleComplete?: boolean, citations?: ReadonlyMap<string, ConceptCitationStatus>): string;
+export declare function mergeTaskText(event: PushEvent, scope: DriftScope | null, bundleComplete?: boolean, citations?: ReadonlyMap<string, ConceptCitationStatus>, bundlePath?: string): string;
 type MentionEvent = Extract<HostEvent, {
     kind: "mention";
 }>;
@@ -83,13 +90,68 @@ export declare function siblingContinuationHints(siblings: readonly OpenSibling[
  * taskOverride column.
  */
 export declare function mentionTaskText(event: MentionEvent, siblings?: readonly OpenSibling[]): string;
+/** The reply to a mention whose author can see the repository but cannot push to it. */
+export declare const NO_WRITE_ACCESS_BODY: string;
 export declare function unknownPriorRunBody(priorRunId: string): string;
+/** Why a mention from someone allowed to use wardby started nothing; posted so they are not left guessing. */
+export type MentionDeclineReason = "no_responder" | "no_reviewer" | "agent_not_authorized" | "pull_request_not_reviewable";
+/**
+ * Never names the App's handle: this comment is posted by the App, and a
+ * body that mentioned it could be matched as a mention of itself.
+ */
+export declare function mentionDeclinedBody(reason: MentionDeclineReason): string;
+export interface ReviewTarget {
+    agentId: string;
+    checkName: string;
+}
+/** A review run's task: the head to review, plus any extra context its trigger adds. */
+export declare function reviewTaskText(repository: string, prNumber: number, headSha: string, context?: {
+    task: string;
+    untrustedContext: string;
+}): string;
+/** Starts one review run per target on a pull request head; returns the started run ids. */
+export declare function startReviews(deps: ReviewStartDeps, host: CodeReviewHost, repository: string, prNumber: number, headSha: string, targets: ReviewTarget[], 
+/** True for automatic triggers; an explicit re-run or `@wardby review` always runs. */
+skipReviewedCommits?: boolean, 
+/**
+ * Extra context for this review: `task` (written by wardby, trusted) is appended to the
+ * review task; `untrustedContext` (anything a model or a person wrote) travels separately,
+ * delivered as data.
+ */
+context?: {
+    task: string;
+    untrustedContext: string;
+}): Promise<string[]>;
 /**
  * The reconciler's fallback for deferred reviews: drops rows older than
  * DEFERRED_REVIEW_MAX_AGE_MS, and starts (regardless of CI) those waiting
  * longer than DEFERRED_REVIEW_MAX_WAIT_MS, at most DEFERRED_REVIEW_BATCH per
  * pass, oldest first. Covers CI that never reported, ran very long, or whose
- * completion webhook was missed. Never throws; returns the runs started.
+ * completion webhook was missed. Rows waiting for a delegating run (reason
+ * "request") are released the same way once they are that old, but only when
+ * that run is terminal (or gone): a lead the reconciler marked lost never
+ * reaches its finalizer. Never throws; returns the runs started.
  */
 export declare function startDeferredReviews(deps: ReviewStartDeps, now?: Date): Promise<string[]>;
+/**
+ * The run whose finish a review of this pull request waits for: the root of
+ * the run tree when the PR's opening coding run was delegated (it has a
+ * parent run) and that root is not terminal yet; otherwise null (a
+ * non-delegated coding PR, a finished request, or an unknown marker). A lead's
+ * delegate_to_* calls block until each child is terminal, so a terminal root
+ * means every sibling coding run of the request has finished and opened its
+ * pull request. A continuation's marker resolves to its root coding run, then
+ * up that run's parents. `repository`, when given, must be the coding run's.
+ */
+export declare function requestLeadRunId(db: Pick<HostEventDb, "$queryRaw">, prMarkerRunId: string, repository?: string): Promise<string | null>;
+/**
+ * The delegating run `leadRunId` is terminal (it succeeded, failed, or was
+ * cancelled): releases every review that waited for it. A reviewer linked
+ * with waitForCi whose head's CI is still pending is handed to CI (the row
+ * becomes reason "ci", its max wait counted from now); every other row is
+ * started (claimed by delete, so concurrent releases start each review once).
+ * Called from the lead's finalizer, after the related pull requests sections
+ * were rewritten. Never throws.
+ */
+export declare function startDeferredForRequest(deps: ReviewStartDeps, leadRunId: string): Promise<void>;
 export declare function routeHostEvent(event: HostEvent, deps: RouteHostEventDeps): Promise<RouteResult>;