@wardby/cli 0.6.0 → 0.8.0

package/dist/core/coding-repository.js

@@ -0,0 +1,92 @@
+import { codeProviderOf, normalizeHostedRepository } from "../coding/code-host.js";
+import { isLocalRepository, normalizeGitHubRepository, normalizeLocalRepository } from "../coding/protocol.js";
+export class RepositoryChoiceRefusedError extends Error {
+    code;
+    allowed;
+    constructor(code, allowed) {
+        super(code === "repository_required"
+            ? `This coding agent works in several repositories: pass repository, one of ${allowed.join(", ")}.`
+            : `That repository is not on this coding agent's list: ${allowed.join(", ")}.`);
+        this.code = code;
+        this.allowed = allowed;
+        this.name = "RepositoryChoiceRefusedError";
+    }
+}
+function canonical(value) {
+    try {
+        if (isLocalRepository(value))
+            return normalizeLocalRepository(value);
+        if (codeProviderOf(value) === "github")
+            return normalizeGitHubRepository(value);
+        return normalizeHostedRepository(value);
+    }
+    catch {
+        return null;
+    }
+}
+function same(a, b) {
+    const left = canonical(a);
+    return left !== null && left === canonical(b);
+}
+/** Which of an agent's links are repositories on a coding agent's list. */
+export const CODING_REPOSITORY_LINK_FILTER = { access: "write", triggers: { isEmpty: true } };
+/**
+ * The repositories a list adds to its default. A link can come to equal the default when
+ * update_agent moves the default onto it; that link adds nothing, and a run there is on the default.
+ */
+export function extraCodingRepositoryLinks(links, defaultRepository) {
+    return links.filter((link) => !same(link.repository, defaultRepository));
+}
+async function listExtraRepositoryLinks(reader, agentId, defaultRepository) {
+    const links = await reader.agentRepository.findMany({
+        where: { agentId, ...CODING_REPOSITORY_LINK_FILTER },
+        select: { repository: true, baseRef: true },
+        orderBy: { repository: "asc" },
+    });
+    return extraCodingRepositoryLinks(links, defaultRepository);
+}
+/** Whether the agent has more than its default, for wording only: authorization is resolveCodingRepository's. */
+export async function hasCodingRepositoryList(reader, agentId, defaultRepository) {
+    return (await listExtraRepositoryLinks(reader, agentId, defaultRepository)).length > 0;
+}
+export async function resolveCodingRepository(reader, input) {
+    const { profile, requested, continuesCodingRunId } = input;
+    const defaultTarget = { repository: profile.repository, baseRef: profile.baseRef, viaRepositoryLink: false };
+    if (requested !== undefined && same(requested, profile.repository))
+        return defaultTarget;
+    if (requested === undefined && continuesCodingRunId === undefined && !input.requireExplicit)
+        return defaultTarget;
+    const links = await listExtraRepositoryLinks(reader, input.agentId, profile.repository);
+    const onList = (name) => links.find((link) => same(link.repository, name));
+    const target = (link) => ({
+        repository: link.repository,
+        baseRef: link.baseRef ?? profile.baseRef,
+        viaRepositoryLink: true,
+    });
+    const allowed = [profile.repository, ...links.map((link) => link.repository)];
+    if (requested !== undefined) {
+        const link = onList(requested);
+        if (!link)
+            throw new RepositoryChoiceRefusedError("repository_not_listed", allowed);
+        return target(link);
+    }
+    if (continuesCodingRunId !== undefined) {
+        const repository = await continuationRepository(reader, continuesCodingRunId);
+        const link = repository === null ? undefined : onList(repository);
+        // Anything else stays on the default, where checkContinuation gives its own refusal.
+        return link ? target(link) : defaultTarget;
+    }
+    if (links.length > 0)
+        throw new RepositoryChoiceRefusedError("repository_required", allowed);
+    return defaultTarget;
+}
+async function continuationRepository(reader, runId) {
+    const select = { repository: true, rootCodingRunId: true };
+    const run = await reader.codingRun.findUnique({ where: { runId }, select });
+    if (!run)
+        return null;
+    if (!run.rootCodingRunId)
+        return run.repository;
+    const root = await reader.codingRun.findUnique({ where: { runId: run.rootCodingRunId }, select });
+    return root?.repository ?? null;
+}

package/dist/core/cron.d.ts

@@ -5,7 +5,11 @@
 export interface DueCheckInput {
     schedule: string;
     timezone: string;
-    /** Start of the most recent window this agent already fired for, or null if never. */
+    /**
+     * Start of the most recent window this agent already fired for, or the
+     * moment its schedule was set (see startsSchedule); null only for a
+     * schedule set before that was recorded.
+     */
     lastScheduledAt: Date | null;
     now: Date;
 }
@@ -26,6 +30,20 @@ export interface DueCheckInput {
  * `now` that lands exactly on a boundary.
  */
 export declare function dueWindow(input: DueCheckInput): Date | null;
+export interface ScheduleState {
+    schedule: string | null;
+    timezone: string;
+    scheduleEnabled: boolean;
+}
+/**
+ * Whether a schedule change starts the schedule afresh. Setting, changing
+ * (expression or timezone) or re-enabling a schedule does, so it first fires
+ * at its next window after that, never for one that passed before it existed
+ * or while it was off (see scheduleStartFields). Saving the schedule it
+ * already has does not, keeping its firing history. `before` is null for a
+ * new agent.
+ */
+export declare function startsSchedule(before: ScheduleState | null, after: ScheduleState): boolean;
 export declare function isDue(input: DueCheckInput): boolean;
 /** Throws a descriptive error for an invalid cron expression or timezone. */
 export declare function validateCronExpression(schedule: string, timezone: string): void;

package/dist/core/cron.js

@@ -31,6 +31,23 @@ export function dueWindow(input) {
     }
     return mostRecent;
 }
+/**
+ * Whether a schedule change starts the schedule afresh. Setting, changing
+ * (expression or timezone) or re-enabling a schedule does, so it first fires
+ * at its next window after that, never for one that passed before it existed
+ * or while it was off (see scheduleStartFields). Saving the schedule it
+ * already has does not, keeping its firing history. `before` is null for a
+ * new agent.
+ */
+export function startsSchedule(before, after) {
+    if (!after.schedule || !after.scheduleEnabled)
+        return false;
+    const unchanged = before !== null &&
+        before.scheduleEnabled &&
+        before.schedule === after.schedule &&
+        before.timezone === after.timezone;
+    return !unchanged;
+}
 export function isDue(input) {
     return dueWindow(input) !== null;
 }

package/dist/core/datastores.js

@@ -65,7 +65,7 @@ export function buildSharedDatastoreAccessor(agentId, datastore, db) {
             const datastoreId = await resolveDatastoreId(agentId, boundName, db);
             if (!datastoreId)
                 throw new Error("datastore_not_bound");
-            await datastore.setShared(datastoreId, key, value, opts);
+            await datastore.setShared(datastoreId, key, value, { ...opts, writerAgentId: agentId });
         },
         async delete(boundName, key) {
             const datastoreId = await resolveDatastoreId(agentId, boundName, db);

package/dist/core/deferred-coding.d.ts

@@ -0,0 +1,14 @@
+import type { PrismaClient } from "#prisma";
+import type { Executor } from "../providers/executor/types.js";
+export interface ResolveDeferredCodingInput {
+    db: PrismaClient;
+    /** The starting process's own executor: the one with the coding configuration. */
+    executor: Executor;
+    runId: string;
+}
+/**
+ * Coding inputs of a run the native gateway dispatched (DeferredExecutor): resolved here, on the
+ * process that starts it, with its own executor — the gateway holds no coding configuration.
+ * Marker: a pending coding run whose CodingRun.workerImage is null. False: the run was refused.
+ */
+export declare function resolveDeferredCodingRun({ db, executor, runId }: ResolveDeferredCodingInput): Promise<boolean>;

package/dist/core/deferred-coding.js

@@ -0,0 +1,62 @@
+import { composeCodingTask } from "../coding/protocol.js";
+import { assertCodingProvider } from "../coding/provider.js";
+import { parseAllowedServiceNames } from "../coding/services/catalog.js";
+import { servicesInstructionNote } from "../coding/services/note.js";
+import { knowledgeSection } from "../knowledge/note.js";
+import { readKnowledgeIndexAt, readServiceDeclarationAt, resolveDispatchServices } from "./dispatch.js";
+/**
+ * Coding inputs of a run the native gateway dispatched (DeferredExecutor): resolved here, on the
+ * process that starts it, with its own executor — the gateway holds no coding configuration.
+ * Marker: a pending coding run whose CodingRun.workerImage is null. False: the run was refused.
+ */
+export async function resolveDeferredCodingRun({ db, executor, runId }) {
+    const run = await db.run.findUnique({
+        where: { id: runId },
+        include: { codingRun: true, agent: { include: { codingProfile: true } } },
+    });
+    const coding = run?.codingRun;
+    // A native run, or a coding run dispatch already resolved: nothing to do.
+    if (!run || !coding || coding.workerImage !== null)
+        return true;
+    const profile = run.agent.codingProfile;
+    if (!profile)
+        throw new Error(`coding_profile_missing: coding agent "${run.agentId}" has no coding profile.`);
+    assertCodingProvider(coding.provider);
+    // The provider is the run's own (fixed at dispatch); the toolchain and image ref are the profile's,
+    // read as they are when the run starts.
+    const selector = {
+        provider: coding.provider,
+        toolchain: profile.toolchain,
+        toolchainVersion: profile.toolchainVersion,
+        workerImageRef: profile.workerImageRef,
+    };
+    // Services before images, in dispatch's order: a run with both a refused declaration and a bad
+    // image ends refused. As at dispatch, only an agent allowed some service reads the declaration,
+    // and any refusal dispatch would have raised refuses the run here instead.
+    let services = [];
+    if (parseAllowedServiceNames(profile.services).length > 0) {
+        const outcome = await readServiceDeclarationAt(executor, coding.repository, coding.baseRef);
+        const resolved = await resolveDispatchServices(db, outcome, profile.services, executor, coding.provider, coding.task, run.agent.systemPrompt);
+        if ("refusal" in resolved) {
+            await db.run.updateMany({
+                where: { id: runId, status: "pending" },
+                data: { status: "refused", error: resolved.refusal, finishedAt: new Date() },
+            });
+            return false;
+        }
+        services = resolved.services;
+    }
+    if (!executor.resolveCodingWorkerImage) {
+        throw new Error("coding_execution_not_configured: this process cannot start coding runs.");
+    }
+    const workerImage = executor.resolveCodingWorkerImage(selector);
+    const toolImage = executor.resolveCodingToolImage?.(selector) ?? null;
+    const knowledge = await readKnowledgeIndexAt(executor, coding.repository, coding.baseRef);
+    const task = composeCodingTask(run.agent.systemPrompt, coding.task, servicesInstructionNote(services), knowledge ? knowledgeSection(knowledge) : undefined);
+    // Conditional on the marker: of two racing starts, only one writes (both composed the same inputs).
+    await db.codingRun.updateMany({
+        where: { runId, workerImage: null },
+        data: { workerImage, toolImage, services, task },
+    });
+    return true;
+}

package/dist/core/delegation-child.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one lookup both delegation paths (control-plane `delegate_to_*` and the sandbox gateway's
+ * `durableDelegate`) use to find the child a delegation call already created, so a re-executed
+ * delegate step (a resume, or a takeover under a new version) waits on that child again instead
+ * of refusing it as a duplicate.
+ */
+import type { PrismaClient } from "#prisma";
+export type DelegationChildDb = Pick<PrismaClient, "run">;
+/**
+ * The child a delegation call already created, if any: exact key first (Run.parentCallId, the
+ * model's tool-call id), then the single child of that agent with no key. Two or more such
+ * children are ambiguous and adopt none.
+ *
+ * A caller with a call id is a re-run of a recorded step, so an unkeyed child can only be a
+ * legacy row created before parentCallId existed; it is adopted in any status, because it may
+ * have finished while the lead was between deploys and its result is what the step is owed. A
+ * caller without a call id cannot tell a re-run from a new call (its children are unkeyed too),
+ * so it adopts only a drivable child; a finished one leaves the call to the once-per-agent
+ * refusal. `createdAt` is the child row's creation time (Run.startedAt, set when the row is
+ * written and never rewritten), from which the caller measures its wait bound.
+ */
+export declare function findDelegationChild(db: DelegationChildDb, parentRunId: string, childAgentId: string, parentCallId: string | undefined): Promise<{
+    id: string;
+    createdAt: Date;
+} | null>;

package/dist/core/delegation-child.js

@@ -0,0 +1,37 @@
+import { DRIVABLE } from "./run-status.js";
+/**
+ * The child a delegation call already created, if any: exact key first (Run.parentCallId, the
+ * model's tool-call id), then the single child of that agent with no key. Two or more such
+ * children are ambiguous and adopt none.
+ *
+ * A caller with a call id is a re-run of a recorded step, so an unkeyed child can only be a
+ * legacy row created before parentCallId existed; it is adopted in any status, because it may
+ * have finished while the lead was between deploys and its result is what the step is owed. A
+ * caller without a call id cannot tell a re-run from a new call (its children are unkeyed too),
+ * so it adopts only a drivable child; a finished one leaves the call to the once-per-agent
+ * refusal. `createdAt` is the child row's creation time (Run.startedAt, set when the row is
+ * written and never rewritten), from which the caller measures its wait bound.
+ */
+export async function findDelegationChild(db, parentRunId, childAgentId, parentCallId) {
+    const select = { id: true, startedAt: true };
+    const found = (row) => ({ id: row.id, createdAt: row.startedAt });
+    if (parentCallId) {
+        // Same agent too: a call id is the same call only if it names the same sub-agent. A colliding
+        // id from another agent is never adopted: its create then fails on the unique key, which the
+        // delegate tool answers with a tool-result error (delegation_conflict), never a run failure.
+        const keyed = await db.run.findFirst({ where: { parentRunId, parentCallId, agentId: childAgentId }, select });
+        if (keyed)
+            return found(keyed);
+    }
+    const legacy = await db.run.findMany({
+        where: {
+            parentRunId,
+            agentId: childAgentId,
+            parentCallId: null,
+            ...(parentCallId ? {} : { status: { in: [...DRIVABLE] } }),
+        },
+        select,
+        take: 2,
+    });
+    return legacy.length === 1 ? found(legacy[0]) : null;
+}

package/dist/core/delegation-slots.d.ts

@@ -0,0 +1,27 @@
+/** What the once-per-run rule counts: a sub-agent, and for a coding sub-agent, the repository. */
+export declare function delegationSlot(childAgentId: string, repository: string | null): string;
+/**
+ * Slots for runs already delegated. A run refused at dispatch has no CodingRun, so its
+ * repository is unknown; for this child that counts as its default. Retrying a refused
+ * non-default repository is allowed, and still counts toward the delegation limit.
+ */
+export declare function priorDelegationSlots(rows: readonly {
+    agentId: string;
+    codingRun?: {
+        repository: string;
+    } | null;
+}[], childAgentId: string, defaultRepository: string | null): string[];
+/**
+ * At most `limit` dispatches per run (default one: a classifier deciding plan-vs-implement
+ * commits to exactly one child), and never the same slot twice, so a retry can't leave two
+ * children racing on the same task. A delegation waiting for budget holds its place.
+ */
+export declare function delegationLimitRefusal(input: {
+    priorSlots: readonly string[];
+    waitingSlots: readonly string[];
+    slot: string;
+    boundName: string;
+    limit: number;
+    /** Whether "the same slot" means the same repository; otherwise it means the same sub-agent. */
+    childHasRepositoryList: boolean;
+}): string | null;

package/dist/core/delegation-slots.js

@@ -0,0 +1,44 @@
+/** What the once-per-run rule counts: a sub-agent, and for a coding sub-agent, the repository. */
+export function delegationSlot(childAgentId, repository) {
+    return repository === null ? childAgentId : `${childAgentId}\n${repository.toLowerCase()}`;
+}
+/**
+ * Slots for runs already delegated. A run refused at dispatch has no CodingRun, so its
+ * repository is unknown; for this child that counts as its default. Retrying a refused
+ * non-default repository is allowed, and still counts toward the delegation limit.
+ */
+export function priorDelegationSlots(rows, childAgentId, defaultRepository) {
+    return rows.map((row) => delegationSlot(row.agentId, row.codingRun?.repository ?? (row.agentId === childAgentId ? defaultRepository : null)));
+}
+/**
+ * At most `limit` dispatches per run (default one: a classifier deciding plan-vs-implement
+ * commits to exactly one child), and never the same slot twice, so a retry can't leave two
+ * children racing on the same task. A delegation waiting for budget holds its place.
+ */
+export function delegationLimitRefusal(input) {
+    const { priorSlots, waitingSlots, slot, boundName, limit, childHasRepositoryList } = input;
+    if (priorSlots.includes(slot) || waitingSlots.includes(slot)) {
+        return JSON.stringify({
+            error: "already_dispatched",
+            message: childHasRepositoryList
+                ? `This run already delegated to "${boundName}" for this repository; a run delegates to each sub-agent and repository at most once.`
+                : `This run already delegated to "${boundName}"; a run delegates to each sub-agent at most once.`,
+        });
+    }
+    if (priorSlots.length < limit && priorSlots.length + waitingSlots.length >= limit) {
+        // Only a waiting delegation (parallelDelegations) holds the remaining place.
+        return JSON.stringify({
+            error: "already_dispatched",
+            message: `This run reached its limit of ${limit} delegations: ${priorSlots.length} made and ${waitingSlots.length} waiting for budget.`,
+        });
+    }
+    if (priorSlots.length >= limit) {
+        return JSON.stringify({
+            error: "already_dispatched",
+            message: limit === 1
+                ? "This run already delegated to a sub-agent; only one delegation is allowed per run."
+                : `This run already made ${limit} delegations, the most this agent allows per run.`,
+        });
+    }
+    return null;
+}

package/dist/core/dispatch.d.ts

@@ -1,10 +1,14 @@
 import type { Prisma, PrismaClient, Run, RunTrigger, Task } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
+import { type CodingProvider } from "../coding/provider.js";
+import { type DeclaredService } from "../coding/services/declaration.js";
+import { type ServiceResolution } from "../coding/services/resolve.js";
 import { type AttributionIntent } from "./attribution.js";
 import { type BudgetConstraint } from "./budget-groups.js";
+import { type KnowledgeNoteInput } from "../knowledge/note.js";
 import { type SelfDefectSink } from "./self-defects.js";
-export type DispatchDb = Pick<PrismaClient, "agent" | "run" | "runHostCheck" | "codingRun" | "task" | "webhook" | "budgetGroup" | "$transaction" | "$queryRaw">;
-export type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "runHostCheck" | "runHostStatus" | "runIssueStatus" | "codingRun" | "codingService" | "task" | "webhook" | "budgetGroup" | "resourceGrant" | "workItem" | "localPullRequest" | "runAttribution" | "$queryRaw" | "$executeRawUnsafe">;
+export type DispatchDb = Pick<PrismaClient, "agent" | "agentRepository" | "run" | "runHostCheck" | "codingRun" | "task" | "webhook" | "budgetGroup" | "$transaction" | "$queryRaw">;
+export type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "agentRepository" | "run" | "runHostCheck" | "runHostStatus" | "runIssueStatus" | "codingRun" | "codingService" | "task" | "webhook" | "budgetGroup" | "resourceGrant" | "workItem" | "localPullRequest" | "runAttribution" | "$queryRaw" | "$executeRawUnsafe">;
 type DispatchAgent = Prisma.AgentGetPayload<{
     include: {
         codingProfile: true;
@@ -63,6 +67,12 @@ export interface DispatchRunOptions {
     triggeredById?: string | null;
     /** Sub-agent dispatch (see AgentSubAgent): links this run into a run tree. */
     parentRunId?: string;
+    /**
+     * The parent's delegation call (the model's tool-call id) that dispatches this sub-agent run.
+     * Unique per parent, so a re-executed delegate step finds the child its call created
+     * (findDelegationChild) instead of starting a second one.
+     */
+    parentCallId?: string;
     /**
      * Cost attribution for a run that starts a new attribution (issue event,
      * linked PR, explicit key), resolved before the call (attribution.ts
@@ -77,6 +87,10 @@ export interface DispatchRunOptions {
      * mutually exclusive with it, since a native run has no CodingRun.
      */
     taskOverride?: string;
+    /** The repository for a coding run; must be on the agent's list. Default: codingProfile.repository. */
+    codingRepository?: string;
+    /** Refuse with repository_required when the agent has links and nothing names a repository. */
+    requireExplicitRepository?: boolean;
     /**
      * Replaces `agent.budgetUsd` as the requested ceiling for this run's coding
      * budget reservation. The reservation is still tightened by the agent's
@@ -148,6 +162,19 @@ export declare function markRunFailedFromExecutorError(db: Pick<DispatchDb, "run
  * `run_tree_exhausted`, then a sentence for people.
  */
 export declare function budgetExhaustedError(constraint: BudgetConstraint): string;
+/**
+ * Serializes grouped coding dispatches (security review I1). Under
+ * Serializable, a row lock taken after the transaction's first read cannot
+ * queue anything: the snapshot is already fixed, so each waiter wakes up
+ * with a stale view and aborts. LOCK TABLE is the one statement that takes
+ * no snapshot, so as the transaction's first statement it makes a waiter's
+ * snapshot start only after the previous holder committed. SHARE ROW
+ * EXCLUSIVE conflicts with itself and with writes to BudgetGroup rows, but not
+ * with the ROW SHARE that foreign-key checks from Agent take, so attaching
+ * agents to groups is not blocked. It serializes grouped coding dispatches
+ * across all groups; each holds it only for one short transaction.
+ */
+export declare const GROUP_DISPATCH_LOCK_SQL = "LOCK TABLE \"BudgetGroup\" IN SHARE ROW EXCLUSIVE MODE";
 /**
  * Attempts for the persist transaction, and the jittered backoff between
  * them, for serialization failures, deadlocks and transactions that could
@@ -189,6 +216,25 @@ export type ContinuationCheck = {
  * run at all" (a user-facing refusal message, not a dispatch).
  */
 export declare function checkContinuation(reader: Pick<DispatchTx, "codingRun">, runId: string, repository: string, dispatchingOwnerId?: string | null): Promise<ContinuationCheck>;
+/** What dispatch learned about a coding run's .wardby/services.yaml before its transaction. */
+export type DeclarationOutcome = {
+    kind: "none";
+} | {
+    kind: "declared";
+    services: DeclaredService[];
+} | {
+    kind: "refused";
+    refusal: string;
+};
+/** The bundle index at a known base ref; also how a deferred coding run reads it when it starts. */
+export declare function readKnowledgeIndexAt(executor: Executor, repository: string, baseRef: string): Promise<KnowledgeNoteInput | undefined>;
+/** The declaration at a known base ref, parsed; also how a deferred coding run reads it when it starts. */
+export declare function readServiceDeclarationAt(executor: Executor, repository: string, baseRef: string): Promise<DeclarationOutcome>;
+/**
+ * Inside the transaction: the run's services, or the refusal that stops it. Takes only the
+ * catalog, so a deferred coding run's start resolves them the same way with a plain client.
+ */
+export declare function resolveDispatchServices(tx: Pick<Prisma.TransactionClient, "codingService">, outcome: DeclarationOutcome, allowed: unknown, executor: Executor, provider: CodingProvider, request: string, instructions: string | null): Promise<ServiceResolution>;
 /**
  * Persists every detached run input in one transaction, then invokes the
  * executor only after commit. A null result means the caller's transactional