@davidorex/pi-agent-dispatch 0.28.0

package/dist/run-work-order-loop-tool.d.ts

@@ -0,0 +1,35 @@
+/**
+ * run-work-order-loop Pi tool — single-call wrapper around the FEAT-006
+ * north-star loop. The orchestrator names a work-order id (loaded from
+ * .project/work-orders.json per TASK-088 schema) and the loop drives:
+ * dispatch the target_agent → run-real-checks → on pass commit-attested
+ * → on fail human-OK retry. Bounded iterations (default 3) per FEAT-006;
+ * human-OK gate per DEC-0047 governance.
+ *
+ * Per DEC-0014 this tool is the harness-confined orchestrator's positive-
+ * clause shortcut: previously the orchestrator hand-chained call-agent /
+ * run-real-checks / commit-attested per iteration; now one Pi call closes
+ * the loop while preserving every gate (capability composition at the
+ * call boundary, deterministic real-check verdict, human-OK retry, writer-
+ * attestation footer).
+ */
+import { Type } from "@earendil-works/pi-ai";
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type WorkOrderLoopResult } from "./work-order-loop.js";
+export declare const runWorkOrderLoopTool: {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        work_order_id: Type.TString;
+        max_iterations: Type.TOptional<Type.TNumber>;
+        agent_grant: Type.TOptional<Type.TArray<Type.TString>>;
+    }>;
+    execute(_toolCallId: string, params: {
+        work_order_id: string;
+        max_iterations?: number;
+        agent_grant?: string[];
+    }, _signal: AbortSignal, _onUpdate: AgentToolUpdateCallback, ctx: ExtensionContext): Promise<AgentToolResult<WorkOrderLoopResult>>;
+};
+//# sourceMappingURL=run-work-order-loop-tool.d.ts.map

package/dist/run-work-order-loop-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-work-order-loop-tool.d.ts","sourceRoot":"","sources":["../src/run-work-order-loop-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAClH,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAElF,eAAO,MAAM,oBAAoB;;;;;;;;;;yBAkBlB,MAAM,UACX;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,WACzE,WAAW,aACT,uBAAuB,OAC7B,gBAAgB,GACnB,OAAO,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC;CAahD,CAAC"}

package/dist/run-work-order-loop-tool.js

@@ -0,0 +1,46 @@
+/**
+ * run-work-order-loop Pi tool — single-call wrapper around the FEAT-006
+ * north-star loop. The orchestrator names a work-order id (loaded from
+ * .project/work-orders.json per TASK-088 schema) and the loop drives:
+ * dispatch the target_agent → run-real-checks → on pass commit-attested
+ * → on fail human-OK retry. Bounded iterations (default 3) per FEAT-006;
+ * human-OK gate per DEC-0047 governance.
+ *
+ * Per DEC-0014 this tool is the harness-confined orchestrator's positive-
+ * clause shortcut: previously the orchestrator hand-chained call-agent /
+ * run-real-checks / commit-attested per iteration; now one Pi call closes
+ * the loop while preserving every gate (capability composition at the
+ * call boundary, deterministic real-check verdict, human-OK retry, writer-
+ * attestation footer).
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { runWorkOrderLoop } from "./work-order-loop.js";
+export const runWorkOrderLoopTool = {
+    name: "run-work-order-loop",
+    label: "Run Work-Order Loop",
+    description: "Execute the bounded work-order loop: dispatch target_agent (via direct pi-jit-agents library) → run-real-checks (deterministic verdict — the actual exit code, never an LLM self-report) → on-pass commit-attested → on-fail human-OK retry at the iteration boundary. Bounded iterations (default 3); human-OK gate governs retry.",
+    promptSnippet: "Execute the end-to-end work-order loop for a declared spec.",
+    parameters: Type.Object({
+        work_order_id: Type.String({
+            description: "ID of the work-order to execute (loads from .project/work-orders.json schema).",
+        }),
+        max_iterations: Type.Optional(Type.Number({ description: "Max iteration count before fail-final. Default 3." })),
+        agent_grant: Type.Optional(Type.Array(Type.String(), {
+            description: "Tool grant for the dispatched privileged agent (capability composition). Default empty.",
+        })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const result = await runWorkOrderLoop(ctx.cwd, params, ctx);
+        const commitFragment = result.commit_sha ? `, commit ${result.commit_sha}` : "";
+        return {
+            details: result,
+            content: [
+                {
+                    type: "text",
+                    text: `run-work-order-loop ${params.work_order_id}: ${result.final_status} (${result.iterations.length} iterations${commitFragment})`,
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=run-work-order-loop-tool.js.map

package/dist/run-work-order-loop-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-work-order-loop-tool.js","sourceRoot":"","sources":["../src/run-work-order-loop-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAA4B,MAAM,sBAAsB,CAAC;AAElF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IACnC,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EACV,qUAAqU;IACtU,aAAa,EAAE,6DAA6D;IAC5E,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;QACvB,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC;YAC1B,WAAW,EAAE,gFAAgF;SAC7F,CAAC;QACF,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,mDAAmD,EAAE,CAAC,CAAC;QAChH,WAAW,EAAE,IAAI,CAAC,QAAQ,CACzB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE;YACzB,WAAW,EAAE,yFAAyF;SACtG,CAAC,CACF;KACD,CAAC;IACF,KAAK,CAAC,OAAO,CACZ,WAAmB,EACnB,MAAkF,EAClF,OAAoB,EACpB,SAAkC,EAClC,GAAqB;QAErB,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5D,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,OAAO;YACN,OAAO,EAAE,MAAM;YACf,OAAO,EAAE;gBACR;oBACC,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,uBAAuB,MAAM,CAAC,aAAa,KAAK,MAAM,CAAC,YAAY,KAAK,MAAM,CAAC,UAAU,CAAC,MAAM,cAAc,cAAc,GAAG;iBACrI;aACD;SACD,CAAC;IACH,CAAC;CACD,CAAC"}

package/dist/verified-identity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * verified-identity — terminal-operator identity discovered from process
+ * environment, used by the auth-gate handler to overwrite caller-supplied
+ * writer.user with a verified value at the canonical authorization point
+ * (the pi-dispatch tool_call boundary).
+ *
+ * Aim: the auth-gate's interactive confirm verifies that SOMEONE at the
+ * terminal authorized the call; this module supplies the identity of that
+ * someone so the substrate attestation stamp reflects the actually-
+ * confirming operator rather than a caller-claimed value. The intended
+ * source chain is:
+ *
+ *   1. `git config user.email` — the typical canonical contributor identity
+ *      anchored on this checkout's git configuration; preferred because it
+ *      mirrors the identity the same operator commits under.
+ *   2. `process.env.USER` — POSIX login name; coarser but always present in
+ *      a normally-launched interactive shell.
+ *   3. `null` + a structured warning trace — the operator-visible signal
+ *      that no verifiable identity was discoverable; the auth-gate
+ *      preserves the caller-supplied identity in that case (last-resort
+ *      fall-through; auditable via the warning).
+ *
+ * The resolution is module-level cached. Caching means a config drift
+ * mid-process does not change later attestations; tests cover the cache
+ * via the exported `_resetVerifiedIdentityCache` helper.
+ *
+ * Dependency-injection design: `getVerifiedOperatorIdentity` accepts an
+ * optional `deps` argument shaped `{ runGitConfig, getEnvUser, emitWarning }`
+ * so tests can substitute stubs without spawning a real git or mutating
+ * process.env. Production callers pass nothing; the defaults bind the real
+ * execSync / process.env.USER / writeAgentTrace pipeline.
+ */
+export interface VerifiedIdentityDeps {
+    runGitConfig?: () => string | null;
+    getEnvUser?: () => string | null;
+    emitWarning?: (message: string) => void;
+}
+/**
+ * Reset the module-level cache so a subsequent call re-resolves identity.
+ * Test-only surface — production callers should never invoke this.
+ */
+export declare function _resetVerifiedIdentityCache(): void;
+/**
+ * Resolve a verified operator identity. Lazy-cached at module level on
+ * first call; subsequent calls return the cached value (including a cached
+ * null when both sources were absent on first resolution).
+ *
+ * Returns the discovered identity string, or null if neither source
+ * yielded a value. When the result is null, a structured warning is
+ * emitted via the supplied (or default) trace pipeline so the absence is
+ * operator-visible rather than silent.
+ */
+export declare function getVerifiedOperatorIdentity(deps?: VerifiedIdentityDeps): string | null;
+//# sourceMappingURL=verified-identity.d.ts.map

package/dist/verified-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verified-identity.d.ts","sourceRoot":"","sources":["../src/verified-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AASH,MAAM,WAAW,oBAAoB;IACpC,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAID;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AA+DD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAwBtF"}

package/dist/verified-identity.js

@@ -0,0 +1,133 @@
+/**
+ * verified-identity — terminal-operator identity discovered from process
+ * environment, used by the auth-gate handler to overwrite caller-supplied
+ * writer.user with a verified value at the canonical authorization point
+ * (the pi-dispatch tool_call boundary).
+ *
+ * Aim: the auth-gate's interactive confirm verifies that SOMEONE at the
+ * terminal authorized the call; this module supplies the identity of that
+ * someone so the substrate attestation stamp reflects the actually-
+ * confirming operator rather than a caller-claimed value. The intended
+ * source chain is:
+ *
+ *   1. `git config user.email` — the typical canonical contributor identity
+ *      anchored on this checkout's git configuration; preferred because it
+ *      mirrors the identity the same operator commits under.
+ *   2. `process.env.USER` — POSIX login name; coarser but always present in
+ *      a normally-launched interactive shell.
+ *   3. `null` + a structured warning trace — the operator-visible signal
+ *      that no verifiable identity was discoverable; the auth-gate
+ *      preserves the caller-supplied identity in that case (last-resort
+ *      fall-through; auditable via the warning).
+ *
+ * The resolution is module-level cached. Caching means a config drift
+ * mid-process does not change later attestations; tests cover the cache
+ * via the exported `_resetVerifiedIdentityCache` helper.
+ *
+ * Dependency-injection design: `getVerifiedOperatorIdentity` accepts an
+ * optional `deps` argument shaped `{ runGitConfig, getEnvUser, emitWarning }`
+ * so tests can substitute stubs without spawning a real git or mutating
+ * process.env. Production callers pass nothing; the defaults bind the real
+ * execSync / process.env.USER / writeAgentTrace pipeline.
+ */
+import { execSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+import { cleanGitEnv } from "@davidorex/pi-context/git-env";
+import { writeAgentTrace } from "@davidorex/pi-jit-agents";
+let cached; // undefined = not yet resolved
+/**
+ * Reset the module-level cache so a subsequent call re-resolves identity.
+ * Test-only surface — production callers should never invoke this.
+ */
+export function _resetVerifiedIdentityCache() {
+    cached = undefined;
+}
+/**
+ * ULID-shape placeholder for the trace entry id. Mirrors the precedent in
+ * composite-loader.ts: the trace pipeline schema requires a 26-character
+ * Crockford-base32 ULID; we mint a regex-shaped value without taking a
+ * dependency on a real ULID library. Identifier collisions on the trace
+ * surface are tolerated by downstream consumers.
+ */
+function placeholderTraceId() {
+    const hex = randomUUID().replace(/-/g, "");
+    const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    let out = "";
+    for (let i = 0; i < 26; i++) {
+        out += alphabet[Number.parseInt(hex[i % hex.length], 16) % alphabet.length];
+    }
+    return out;
+}
+function defaultTracePath() {
+    const env = process.env.PI_AGENT_TRACE_PATH;
+    if (env && env.length > 0)
+        return env;
+    return path.join(homedir(), ".pi", "traces", "extension-load.jsonl");
+}
+function defaultEmitWarning(message) {
+    try {
+        writeAgentTrace({
+            type: "extension_load_warning",
+            id: placeholderTraceId(),
+            parentId: null,
+            timestamp: new Date().toISOString(),
+            extension_name: "pi-agent-dispatch",
+            message,
+            severity: "warning",
+        }, { tracePath: defaultTracePath() });
+    }
+    catch {
+        // Trace failures are observability-only; never let them mask the
+        // missing-identity condition or abort the gate.
+    }
+}
+function defaultRunGitConfig() {
+    try {
+        const out = execSync("git config user.email", {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env: cleanGitEnv(),
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultGetEnvUser() {
+    const u = process.env.USER;
+    return u && u.length > 0 ? u : null;
+}
+/**
+ * Resolve a verified operator identity. Lazy-cached at module level on
+ * first call; subsequent calls return the cached value (including a cached
+ * null when both sources were absent on first resolution).
+ *
+ * Returns the discovered identity string, or null if neither source
+ * yielded a value. When the result is null, a structured warning is
+ * emitted via the supplied (or default) trace pipeline so the absence is
+ * operator-visible rather than silent.
+ */
+export function getVerifiedOperatorIdentity(deps) {
+    if (cached !== undefined)
+        return cached;
+    const runGitConfig = deps?.runGitConfig ?? defaultRunGitConfig;
+    const getEnvUser = deps?.getEnvUser ?? defaultGetEnvUser;
+    const emitWarning = deps?.emitWarning ?? defaultEmitWarning;
+    const fromGit = runGitConfig();
+    if (fromGit !== null && fromGit.length > 0) {
+        cached = fromGit;
+        return cached;
+    }
+    const fromEnv = getEnvUser();
+    if (fromEnv !== null && fromEnv.length > 0) {
+        cached = fromEnv;
+        return cached;
+    }
+    cached = null;
+    emitWarning("verified-identity: neither git config user.email nor process.env.USER yielded a value; auth-gate identity-stamp will preserve caller-supplied writer.user (unverified)");
+    return cached;
+}
+//# sourceMappingURL=verified-identity.js.map

package/dist/verified-identity.js.map

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

package/dist/work-order-loop.d.ts

@@ -0,0 +1,82 @@
+/**
+ * work-order-loop — bounded FEAT-006 north-star loop implementation.
+ *
+ * The orchestrator declares a work-order (TASK-088 schema). This library
+ * drives the end-to-end loop the work-order encodes:
+ *
+ *   for iteration in 0..max_iterations:
+ *     1. dispatch the work-order's target_agent via the jit-agents library
+ *        (DEC-0044 narrowed; pi-jit-agents stays a library import per JI-021).
+ *     2. run the work-order's real_check_criteria via runRealChecks
+ *        (deterministic verdict per DEC-0018 + DEC-0047 clause 5 — never the
+ *        executing agent's self-report).
+ *     3. on pass: commit-attested with writer-identity footer; final_status
+ *        = "completed".
+ *     4. on fail: ask the human at the iteration boundary (ctx.ui.confirm)
+ *        whether to retry. !confirm → final_status = "aborted-by-human".
+ *
+ * If the loop exhausts max_iterations without a pass → final_status =
+ * "failed". The aim is one Pi tool invocation that closes the entire loop
+ * — the orchestrator no longer manually chains call-agent / run-real-checks
+ * / commit-attested per iteration.
+ *
+ * Per DEC-0014 the orchestrator-side composite is the only authorized
+ * driver of this loop; per FEAT-005 the agent_grant the orchestrator
+ * passes is composed (intersected) at the call-agent dispatch boundary.
+ */
+import type { CompiledAgent, DispatchContext, JitAgentResult } from "@davidorex/pi-jit-agents/types";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AttestedCommitResult, attestedCommit as canonicalAttestedCommit } from "./attested-commit.js";
+import { runRealChecks as canonicalRunRealChecks, type RealCheckCriteria, type RealCheckResult } from "./real-check-runner.js";
+export declare class WorkOrderNotFoundError extends Error {
+    constructor(workOrderId: string);
+}
+export interface WorkOrderIteration {
+    iteration: number;
+    agent_output: unknown;
+    real_check_result: RealCheckResult;
+    commit_attested_result?: AttestedCommitResult;
+    status: "passed" | "failed";
+}
+export interface WorkOrderLoopResult {
+    work_order_id: string;
+    iterations: WorkOrderIteration[];
+    final_status: "completed" | "failed" | "aborted-by-human";
+    commit_sha?: string;
+    total_duration_ms: number;
+}
+export interface WorkOrderLoopOptions {
+    work_order_id: string;
+    max_iterations?: number;
+    agent_grant?: string[];
+}
+interface WorkOrderRecord {
+    id: string;
+    target_agent: string;
+    real_check_criteria?: RealCheckCriteria;
+    scope?: {
+        files?: string[];
+        directories?: string[];
+        operations?: string[];
+    };
+}
+/**
+ * Internal indirection — tests substitute these to short-circuit the
+ * jit-agents / real-check / commit paths. Production code path never
+ * reassigns; the same indirection pattern as call-agent-tool._internals.
+ */
+type DispatchTargetAgent = (cwd: string, wo: WorkOrderRecord, agentGrant: string[], ctx: ExtensionContext) => Promise<JitAgentResult>;
+export declare const _internals: {
+    executeAgent: (c: CompiledAgent, d: DispatchContext) => Promise<JitAgentResult>;
+    runRealChecks: typeof canonicalRunRealChecks;
+    attestedCommit: typeof canonicalAttestedCommit;
+    /**
+     * Tests reassign this to short-circuit the model/auth resolution +
+     * jit-agents compile/dispatch chain. Production code path runs the
+     * default canonical implementation.
+     */
+    dispatchTargetAgent: DispatchTargetAgent | undefined;
+};
+export declare function runWorkOrderLoop(cwd: string, options: WorkOrderLoopOptions, ctx: ExtensionContext): Promise<WorkOrderLoopResult>;
+export {};
+//# sourceMappingURL=work-order-loop.d.ts.map

package/dist/work-order-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-order-loop.d.ts","sourceRoot":"","sources":["../src/work-order-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,KAAK,oBAAoB,EAAE,cAAc,IAAI,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE5G,OAAO,EACN,aAAa,IAAI,sBAAsB,EACvC,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,sBAAuB,SAAQ,KAAK;gBACpC,WAAW,EAAE,MAAM;CAI/B;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,eAAe,CAAC;IACnC,sBAAsB,CAAC,EAAE,oBAAoB,CAAC;IAC9C,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,YAAY,EAAE,WAAW,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,UAAU,eAAe;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,iBAAiB,CAAC;IACxC,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC5E;AAQD;;;;GAIG;AACH,KAAK,mBAAmB,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,GAAG,EAAE,gBAAgB,KACjB,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B,eAAO,MAAM,UAAU;kBACiB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC;;;IAGxG;;;;OAIG;yBAC+B,mBAAmB,GAAG,SAAS;CACjE,CAAC;AAoCF,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,gBAAgB,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAwE9B"}

package/dist/work-order-loop.js

@@ -0,0 +1,149 @@
+/**
+ * work-order-loop — bounded FEAT-006 north-star loop implementation.
+ *
+ * The orchestrator declares a work-order (TASK-088 schema). This library
+ * drives the end-to-end loop the work-order encodes:
+ *
+ *   for iteration in 0..max_iterations:
+ *     1. dispatch the work-order's target_agent via the jit-agents library
+ *        (DEC-0044 narrowed; pi-jit-agents stays a library import per JI-021).
+ *     2. run the work-order's real_check_criteria via runRealChecks
+ *        (deterministic verdict per DEC-0018 + DEC-0047 clause 5 — never the
+ *        executing agent's self-report).
+ *     3. on pass: commit-attested with writer-identity footer; final_status
+ *        = "completed".
+ *     4. on fail: ask the human at the iteration boundary (ctx.ui.confirm)
+ *        whether to retry. !confirm → final_status = "aborted-by-human".
+ *
+ * If the loop exhausts max_iterations without a pass → final_status =
+ * "failed". The aim is one Pi tool invocation that closes the entire loop
+ * — the orchestrator no longer manually chains call-agent / run-real-checks
+ * / commit-attested per iteration.
+ *
+ * Per DEC-0014 the orchestrator-side composite is the only authorized
+ * driver of this loop; per FEAT-005 the agent_grant the orchestrator
+ * passes is composed (intersected) at the call-agent dispatch boundary.
+ */
+import { readBlock } from "@davidorex/pi-context/block-api";
+import { createAgentLoader } from "@davidorex/pi-jit-agents/agent-spec";
+import { compileAgent } from "@davidorex/pi-jit-agents/compile";
+import { executeAgent as canonicalExecuteAgent } from "@davidorex/pi-jit-agents/runtime";
+import { createTemplateEnv } from "@davidorex/pi-jit-agents/template";
+import { attestedCommit as canonicalAttestedCommit } from "./attested-commit.js";
+import { composeToolGrant } from "./capability-composer.js";
+import { runRealChecks as canonicalRunRealChecks, } from "./real-check-runner.js";
+export class WorkOrderNotFoundError extends Error {
+    constructor(workOrderId) {
+        super(`work-order-loop: work-order '${workOrderId}' not found in work-orders block`);
+        this.name = "WorkOrderNotFoundError";
+    }
+}
+function parseModelSpec(spec) {
+    const slashIndex = spec.indexOf("/");
+    if (slashIndex !== -1)
+        return { provider: spec.slice(0, slashIndex), modelId: spec.slice(slashIndex + 1) };
+    return { provider: "anthropic", modelId: spec };
+}
+export const _internals = {
+    executeAgent: canonicalExecuteAgent,
+    runRealChecks: canonicalRunRealChecks,
+    attestedCommit: canonicalAttestedCommit,
+    /**
+     * Tests reassign this to short-circuit the model/auth resolution +
+     * jit-agents compile/dispatch chain. Production code path runs the
+     * default canonical implementation.
+     */
+    dispatchTargetAgent: undefined,
+};
+async function dispatchTargetAgent(cwd, wo, agentGrant, ctx) {
+    const loadAgent = createAgentLoader({ cwd });
+    const spec = loadAgent(wo.target_agent);
+    const env = createTemplateEnv({ cwd });
+    const compiled = compileAgent(spec, { env, input: { work_order_id: wo.id }, cwd });
+    const modelSpec = compiled.model ?? spec.model;
+    if (!modelSpec) {
+        throw new Error(`work-order-loop: agent '${wo.target_agent}' has no model specified.`);
+    }
+    const { provider, modelId } = parseModelSpec(modelSpec);
+    const model = ctx.modelRegistry.find(provider, modelId);
+    if (!model) {
+        throw new Error(`work-order-loop: model '${modelSpec}' not found for agent '${wo.target_agent}'.`);
+    }
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+        throw new Error(`work-order-loop: auth resolution failed for '${modelSpec}': ${auth.error}`);
+    }
+    // Intersect at dispatch boundary per FEAT-005 (parent ∩ requested = agentGrant ∩ spec.tools).
+    const composedGrant = composeToolGrant(agentGrant, spec.tools);
+    const dispatch = {
+        model: model,
+        auth: { apiKey: auth.apiKey ?? "", headers: auth.headers ?? {} },
+        parentGrant: composedGrant,
+        maxTokens: 1024,
+    };
+    return _internals.executeAgent(compiled, dispatch);
+}
+export async function runWorkOrderLoop(cwd, options, ctx) {
+    const start = Date.now();
+    const maxIterations = options.max_iterations ?? 3;
+    const data = readBlock(cwd, "work-orders");
+    const wo = data.work_orders.find((w) => w.id === options.work_order_id);
+    if (!wo)
+        throw new WorkOrderNotFoundError(options.work_order_id);
+    const iterations = [];
+    let finalStatus = "failed";
+    let commitSha;
+    const dispatch = _internals.dispatchTargetAgent ?? dispatchTargetAgent;
+    for (let i = 0; i < maxIterations; i++) {
+        const agentResult = await dispatch(cwd, wo, options.agent_grant ?? [], ctx);
+        const realCheck = await _internals.runRealChecks(cwd, wo.id, wo.real_check_criteria ?? { build_check_test: true });
+        if (realCheck.passed) {
+            const files = wo.scope?.files ?? [];
+            const commitMessage = `feat(work-order-${wo.id}): completion under FEAT-006 loop (iteration ${i + 1}/${maxIterations})`;
+            let commit;
+            if (files.length > 0) {
+                commit = await _internals.attestedCommit(cwd, {
+                    files,
+                    message: commitMessage,
+                    agent_id: wo.target_agent,
+                    work_order_id: wo.id,
+                });
+                commitSha = commit.commit_sha;
+            }
+            iterations.push({
+                iteration: i,
+                agent_output: agentResult.output,
+                real_check_result: realCheck,
+                commit_attested_result: commit,
+                status: "passed",
+            });
+            finalStatus = "completed";
+            break;
+        }
+        iterations.push({
+            iteration: i,
+            agent_output: agentResult.output,
+            real_check_result: realCheck,
+            status: "failed",
+        });
+        // Human-OK gate at iteration boundary. Skip after final iteration —
+        // the loop will exit naturally as "failed" without asking the user
+        // whether to retry past max_iterations.
+        if (i < maxIterations - 1) {
+            const failExcerpt = JSON.stringify(realCheck.details, null, 2).slice(0, 500);
+            const proceed = await ctx.ui.confirm("Real-check failed", `Iteration ${i + 1}/${maxIterations} failed. Retry?\nFail-report: ${failExcerpt}`);
+            if (!proceed) {
+                finalStatus = "aborted-by-human";
+                break;
+            }
+        }
+    }
+    return {
+        work_order_id: wo.id,
+        iterations,
+        final_status: finalStatus,
+        commit_sha: commitSha,
+        total_duration_ms: Date.now() - start,
+    };
+}
+//# sourceMappingURL=work-order-loop.js.map

package/dist/work-order-loop.js.map

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

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@davidorex/pi-agent-dispatch",
+	"version": "0.28.0",
+	"publishConfig": {
+		"access": "public"
+	},
+	"description": "In-pi agent-as-tool dispatch + capability composition extension",
+	"type": "module",
+	"keywords": [
+		"pi-package"
+	],
+	"license": "MIT",
+	"author": "David Ryan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/davidorex/pi-project-workflows.git",
+		"directory": "packages/pi-agent-dispatch"
+	},
+	"homepage": "https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-agent-dispatch",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist/",
+		"*.md",
+		"skills/"
+	],
+	"pi": {
+		"extensions": [
+			"./dist/index.js"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run clean && npm run build",
+		"test": "tsx --test src/*.test.ts"
+	},
+	"dependencies": {
+		"@davidorex/pi-behavior-monitors": "^0.28.0",
+		"@davidorex/pi-context": "^0.28.0",
+		"@davidorex/pi-jit-agents": "^0.28.0",
+		"@davidorex/pi-workflows": "^0.28.0",
+		"@earendil-works/pi-ai": "^0.75.4",
+		"@earendil-works/pi-coding-agent": "^0.75.4",
+		"yaml": "^2.7.1"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/skill-narrative.md

@@ -0,0 +1,53 @@
+---
+name: pi-agent-dispatch
+description: >
+  Sibling Pi extension that registers in-pi agent-as-tool dispatch, capability
+  composition, real-check execution, attested commits, and the bounded
+  north-star work-order loop. Use when authoring agent specs, granting tool
+  capabilities, running deterministic checks, committing with writer attestation,
+  loading config-declared composite operations, or driving end-to-end
+  work-orders through their bounded retry loop.
+---
+
+<objective>
+pi-agent-dispatch is the harness-confined orchestrator's in-pi surface. It registers Pi tools the orchestrator agent invokes to dispatch sub-agents, author specs and tool grants, run deterministic checks the executive cannot fake, commit with writer attestation, and drive bounded work-order loops. It is the sibling-consumer registration site; pi-jit-agents stays a library consumed directly by this package and by pi-workflows.
+</objective>
+
+<dispatch_tools>
+| Tool | Purpose |
+|------|---------|
+| `call-agent` | Dispatch a declared agent spec with a composed tool grant (parent ∩ requested ∩ spec.tools). |
+| `author-agent-spec` | Write an `.agent.yaml` spec to the substrate. Human-authorized via auth-gate confirm at the pi-dispatch layer; the verified terminal-operator identity is stamped as writer on confirm. |
+| `run-work-order-loop` | Execute the bounded work-order loop: dispatch → run-real-checks → on-pass commit-attested → on-fail human-OK retry. |
+</dispatch_tools>
+
+<real_check_tools>
+| Tool | Purpose |
+|------|---------|
+| `run-real-checks` | Execute declared deterministic checks (build/check/test exit codes, schema validations, git diff probes, runtime event probes). Verdict is the actual exit code, never an LLM self-report. |
+| `commit-attested` | Stage + commit with writer-identity footer. Refuses on missing agent_id, files, or message. |
+</real_check_tools>
+
+<capability_authoring>
+Tool grants are config-declared (bounded composites) and authored only via the `author-tool-grant` Pi tool, which is human-authorized at the pi-dispatch auth-gate (interactive confirmation; on confirm the verified terminal-operator identity is stamped as writer). Default grant is empty; widening goes through the auth-gate. The FORBIDDEN_WHOLESALE_OPERATIONS set blocks shipping wholesale L1 surfaces (bash, write, edit) as a single composite token; the L1 ∪ L5 forbidden union check refuses tokens that already appear on the L1 wholesale-forbidden list.
+</capability_authoring>
+
+<composite_loader>
+On extension load, `composite-loader` reads the active substrate's `config.tool_operations[]` and dynamically registers each declared bounded composite as a Pi tool. Config-absent (no pointer or unbootstrapped substrate) degrades gracefully: extension still registers the 6 static tools; the absence is observed via the `extension_load_warning` TraceEntry and (when available) surfaced through `pi.ui.notify`. The substrate is the single source of truth — no parallel ungated path widens capability outside the loader.
+</composite_loader>
+
+<canonical_intention>
+Anchors:
+- Harness-confined orchestrator (positive clause: substrate-write + call-agent + author-agent-spec + run-real-checks + commit-attested + author-tool-grant + run-work-order-loop + declared composites; negative clause: NO bash/edit/write).
+- Sibling-consumer scope; pi-jit-agents stays a library.
+- Human-authorized authoring at the pi-dispatch auth-gate; default empty; terminal verdict = real deterministic checks.
+- Capability composition + end-to-end work-order loop + bounded-composite vocabulary + launch-chain integration.
+- Orchestrator uses jit-agents directly; capability composition lives in the dispatch layer.
+</canonical_intention>
+
+<success_criteria>
+- 6 static tools register on every load: call-agent, author-agent-spec, author-tool-grant, run-real-checks, commit-attested, run-work-order-loop.
+- Composite tools register from config.tool_operations[] when present; load proceeds with warning when absent.
+- Every write-bearing tool routes through the pi-dispatch auth-gate; the verified terminal-operator identity is stamped as writer on confirm.
+- Work-order loop honors max_iterations + human-OK retry gate + on-pass attested commit.
+</success_criteria>