@akagilnc/pi-workflow-roles 0.1.3932 → 0.1.3975

package/dist/stderr-jsonl.js

@@ -1,26 +0,0 @@
-import { writeSync } from "node:fs";
-const STDERR_JSONL_WRITE_RETRY_LIMIT = 100;
-/**
- * Write one complete JSONL record to fd 2.
- * Retries EAGAIN/EINTR and short writes; never writes stdout.
- */
-export function writeStderrJsonlRecord(record, write = writeSync) {
-    const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
-    let offset = 0;
-    let retries = 0;
-    while (offset < bytes.length) {
-        try {
-            const written = write(2, bytes, offset, bytes.length - offset);
-            if (written <= 0)
-                throw new Error("stderr JSONL write made no progress");
-            offset += written;
-            retries = 0;
-        }
-        catch (error) {
-            const code = error.code;
-            if ((code === "EAGAIN" || code === "EINTR") && retries++ < STDERR_JSONL_WRITE_RETRY_LIMIT)
-                continue;
-            throw error;
-        }
-    }
-}

package/dist/tool-execution-observation.js

@@ -1,141 +0,0 @@
-import { writeSync } from "node:fs";
-import { Type } from "typebox";
-import { Value } from "typebox/value";
-import { writeStderrJsonlRecord } from "./stderr-jsonl.js";
-/** Mandatory coalesce window for tool_execution_update heartbeats (stderr is bounded). */
-export const TOOL_EXECUTION_UPDATE_THROTTLE_MS = 30_000;
-/**
- * Heartbeat basis for downstream silence predicates.
- *
- * Production Pi `bash.js` calls `onUpdate` once with empty content at execute entry,
- * then schedules output-driven updates at ~100 ms. This face skips non-producing
- * (empty-content) updates so the first heartbeat is real child output, then
- * coalesces at {@link TOOL_EXECUTION_UPDATE_THROTTLE_MS}.
- *
- * If a future host path stopped delivering output-driven updates, change this to
- * `"duration-only"` and document that silence predicates degrade to pure duration.
- */
-export const TOOL_EXECUTION_UPDATE_HEARTBEAT = "output-driven";
-const observationBase = {
-    role: Type.String({ minLength: 1 }),
-    toolCallId: Type.String({ minLength: 1 }),
-    toolName: Type.String({ minLength: 1 }),
-    timestamp: Type.String({ format: "date-time" }),
-};
-export const toolExecutionObservationRecordSchema = Type.Union([
-    Type.Object({
-        ...observationBase,
-        event: Type.Literal("tool_execution_start"),
-    }, { additionalProperties: true }),
-    Type.Object({
-        ...observationBase,
-        event: Type.Literal("tool_execution_update"),
-    }, { additionalProperties: true }),
-    Type.Object({
-        ...observationBase,
-        event: Type.Literal("tool_execution_end"),
-        isError: Type.Boolean(),
-    }, { additionalProperties: true }),
-]);
-export function validateToolExecutionObservationRecord(record) {
-    if (!Value.Check(toolExecutionObservationRecordSchema, record)) {
-        throw new TypeError("Tool execution observation record does not match its contract");
-    }
-    return record;
-}
-export function writeToolExecutionObservationRecord(record, write = writeSync) {
-    writeStderrJsonlRecord(validateToolExecutionObservationRecord(record), write);
-}
-/** True when a tool_execution_update partialResult carries producing content (not bash's empty entry callback). */
-export function isProducingToolUpdate(partialResult) {
-    if (partialResult == null)
-        return false;
-    if (typeof partialResult !== "object")
-        return true;
-    const content = partialResult.content;
-    if (!Array.isArray(content))
-        return true;
-    if (content.length === 0)
-        return false;
-    return content.some((part) => {
-        if (typeof part !== "object" || part === null)
-            return true;
-        const text = part.text;
-        if (typeof text === "string")
-            return text.length > 0;
-        return true;
-    });
-}
-/**
- * Production throttle clock: genuinely monotonic milliseconds.
- * Wall-clock Date.now() is not safe — NTP/slew can compress two heartbeats under 30s.
- */
-export function systemToolExecutionObservationMonoNow() {
-    return performance.now();
-}
-export function createToolExecutionObservationFace(options) {
-    const states = new Map();
-    async function emit(record) {
-        await options.write(validateToolExecutionObservationRecord(record));
-    }
-    function activeRole() {
-        if (!options.admitted())
-            return undefined;
-        const role = options.role();
-        return role === undefined || role === "" ? undefined : role;
-    }
-    return {
-        reset() {
-            states.clear();
-        },
-        async onStart(event) {
-            const role = activeRole();
-            if (role === undefined)
-                return;
-            states.set(event.toolCallId, { lastUpdateEmitMonoMs: undefined });
-            await emit({
-                event: "tool_execution_start",
-                role,
-                toolCallId: event.toolCallId,
-                toolName: event.toolName,
-                timestamp: options.clock(),
-            });
-        },
-        async onUpdate(event) {
-            const role = activeRole();
-            if (role === undefined)
-                return;
-            if (!isProducingToolUpdate(event.partialResult))
-                return;
-            const now = options.monoNow();
-            const state = states.get(event.toolCallId) ?? { lastUpdateEmitMonoMs: undefined };
-            if (state.lastUpdateEmitMonoMs !== undefined
-                && now - state.lastUpdateEmitMonoMs < TOOL_EXECUTION_UPDATE_THROTTLE_MS) {
-                return;
-            }
-            state.lastUpdateEmitMonoMs = now;
-            states.set(event.toolCallId, state);
-            await emit({
-                event: "tool_execution_update",
-                role,
-                toolCallId: event.toolCallId,
-                toolName: event.toolName,
-                timestamp: options.clock(),
-            });
-        },
-        async onEnd(event) {
-            const role = activeRole();
-            if (role === undefined)
-                return;
-            states.delete(event.toolCallId);
-            await emit({
-                event: "tool_execution_end",
-                role,
-                toolCallId: event.toolCallId,
-                toolName: event.toolName,
-                timestamp: options.clock(),
-                isError: event.isError,
-            });
-        },
-    };
-}

package/dist/worker-role.js

@@ -1,345 +0,0 @@
-import { stringEnum } from "./host-contracts.js";
-import { Type } from "typebox";
-import { openToolObjectFromUnion } from "./open-tool-schema.js";
-import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
-import { CorrectableSubmissionError } from "./submission-correctable-error.js";
-import { CODER_ACCEPTED_TEXT, CODER_OUTPUT_TOOL_NAME, FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, validateAcceptedWorkerDetails, } from "./package-contracts/worker-output.js";
-import { fixerOutputSchema, validateFixerOutput, validateFixerOutputForPacket } from "./package-contracts/fixer-output.js";
-import { FixerPacketValidationError, parseFixerPrerequisites, } from "./package-contracts/fixer-packet.js";
-import { createWorkerSubmissionGate, WORKER_DONE_STATUSES, WorkerCommitReminderError, WorkerPrefixReminderError, WorkerUnfinishedReasonReminderError, } from "./worker-submission-gates.js";
-import { fixerBashSeatbeltDenyReason, matchFixerBashForbiddenLiteral, } from "./fixer-bash-seatbelt.js";
-export { CODER_OUTPUT_TOOL_NAME, FIXER_OUTPUT_TOOL_NAME, validateAcceptedWorkerDetails, };
-const coderOutputVariants = Type.Union([
-    Type.Object({
-        status: stringEnum(["planned"], { description: "planned — 形状指引，非 schema 闸" }),
-        report: Type.String({ minLength: 1, description: "如实结果报告" }),
-    }, { additionalProperties: false }),
-    Type.Object({
-        status: stringEnum(["completed", "refused"], {
-            description: "completed | refused — 形状指引，非 schema 闸；completed 回执含 TDD、同模式、引入回归、行为事实四项证据",
-        }),
-        report: Type.String({ minLength: 1, description: "如实结果报告" }),
-    }, { additionalProperties: false }),
-    Type.Object({
-        status: stringEnum(["unfinished"], {
-            description: "unfinished — 形状指引，非 schema 闸；缺前置或违宪约束致本局未完成时可用。缺待决 owner 决定或答复属缺前置。",
-        }),
-        report: Type.String({ minLength: 1, description: "如实结果报告" }),
-        remainingScope: Type.String({ minLength: 1, description: "本局后剩余工作" }),
-        reason: Type.Optional(Type.String({
-            minLength: 1,
-            description: "阻断原因：缺前置或违宪约束。缺待决 owner 决定或答复属缺前置。",
-        })),
-    }, { additionalProperties: false }),
-]);
-export const coderOutputSchema = withInfrastructureFailureDeclaration(openToolObjectFromUnion(coderOutputVariants));
-export const FIXER_FLAG_DEFINITIONS = {
-    packet: {
-        name: "ak-fix-packet",
-        definition: {
-            description: "Path to opaque prose instructions for the Fixer",
-            type: "string",
-        },
-    },
-    prerequisites: {
-        name: "ak-fixer-prerequisites",
-        definition: {
-            description: "Optional path to a JSON array of typed Fixer prerequisites",
-            type: "string",
-        },
-    },
-    phase: {
-        name: "ak-fixer-phase",
-        definition: {
-            description: "Fixer phase: plan (inspect and propose a repair plan; no edits or commits) or apply (execute the approved plan, verify, and commit when repaired)",
-            type: "string",
-        },
-    },
-};
-export const FIXER_PHASES = ["plan", "apply"];
-function isWorkerPhase(value) {
-    return typeof value === "string" && FIXER_PHASES.includes(value);
-}
-/** Stable code for completed apply without host skill-expansion capability evidence (#525). */
-export const CODER_SKILL_EXPANSION_EVIDENCE_MISSING_CODE = "coder_skill_expansion_evidence_missing";
-/** Correct completed rejection — not infrastructure; projected via submission non-pass bridge. */
-export class CoderSkillExpansionEvidenceMissingError extends CorrectableSubmissionError {
-    code = CODER_SKILL_EXPANSION_EVIDENCE_MISSING_CODE;
-    result;
-    constructor() {
-        super("Coder completed requires host skill-expansion capability evidence");
-        this.name = "CoderSkillExpansionEvidenceMissingError";
-        this.result = Object.freeze({ code: CODER_SKILL_EXPANSION_EVIDENCE_MISSING_CODE });
-    }
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function deepFreeze(value) {
-    if (typeof value !== "object" || value === null || Object.isFrozen(value))
-        return value;
-    for (const child of Object.values(value))
-        deepFreeze(child);
-    return Object.freeze(value);
-}
-export function validateWorkerOutput(output, phase, roleLabel) {
-    if (roleLabel === "Fixer")
-        return validateFixerOutput(output, phase);
-    return validateAcceptedWorkerDetails(output, "Coder");
-}
-/** Reminder bounces stay typed rejects; IO/infrastructure keep identity via host failInfrastructure. */
-function assertAcceptableThroughHost(submissionGate, status, details, hostActions, ctx, toolCallId) {
-    try {
-        submissionGate.assertAcceptable(status, details);
-    }
-    catch (error) {
-        if (error instanceof WorkerCommitReminderError ||
-            error instanceof WorkerPrefixReminderError ||
-            error instanceof WorkerUnfinishedReasonReminderError) {
-            throw error;
-        }
-        hostActions.failInfrastructure(error, ctx, toolCallId);
-    }
-}
-export function createFixerRoleRuntime(pi, dependencies, hostActions) {
-    let soul;
-    let packet;
-    let packetPath;
-    let prerequisitesPath;
-    let phase;
-    let lifecycleRegistered = false;
-    const submissionGate = createWorkerSubmissionGate();
-    pi.registerFlag(FIXER_FLAG_DEFINITIONS.packet.name, FIXER_FLAG_DEFINITIONS.packet.definition);
-    pi.registerFlag(FIXER_FLAG_DEFINITIONS.prerequisites.name, FIXER_FLAG_DEFINITIONS.prerequisites.definition);
-    pi.registerFlag(FIXER_FLAG_DEFINITIONS.phase.name, FIXER_FLAG_DEFINITIONS.phase.definition);
-    return {
-        async activate() {
-            soul = (await dependencies.loadSoul()).trim();
-            if (soul.length === 0)
-                throw new Error("Fixer soul is empty");
-            const selectedPhase = pi.getFlag(FIXER_FLAG_DEFINITIONS.phase.name);
-            if (!isWorkerPhase(selectedPhase)) {
-                throw new Error("Fixer role requires --ak-fixer-phase plan|apply; no other phase is supported");
-            }
-            phase = selectedPhase;
-            const resolvedPacketPath = pi.getFlag(FIXER_FLAG_DEFINITIONS.packet.name);
-            if (typeof resolvedPacketPath !== "string" || resolvedPacketPath.trim().length === 0) {
-                throw new Error("Fixer role requires --ak-fix-packet");
-            }
-            packetPath = resolvedPacketPath;
-            const instructions = await dependencies.loadPacket(packetPath);
-            if (instructions.trim().length === 0) {
-                throw new FixerPacketValidationError(new Error("Fixer instructions must be nonblank"));
-            }
-            const resolvedPrerequisitesPath = pi.getFlag(FIXER_FLAG_DEFINITIONS.prerequisites.name);
-            if (resolvedPrerequisitesPath !== undefined && (typeof resolvedPrerequisitesPath !== "string" || resolvedPrerequisitesPath.trim().length === 0)) {
-                throw new Error("Fixer --ak-fixer-prerequisites path must be nonblank when supplied");
-            }
-            prerequisitesPath =
-                typeof resolvedPrerequisitesPath === "string" ? resolvedPrerequisitesPath : undefined;
-            const prerequisites = prerequisitesPath !== undefined
-                ? parseFixerPrerequisites(await dependencies.loadPacket(prerequisitesPath))
-                : Object.freeze([]);
-            packet = Object.freeze({ instructions, prerequisites });
-            if (!lifecycleRegistered) {
-                lifecycleRegistered = true;
-                pi.registerTool({
-                    name: FIXER_OUTPUT_TOOL_NAME,
-                    label: "修内司输出",
-                    description: "提交修内司终局回执；基础设施失败走 abort，不经本工具。",
-                    promptSnippet: "提交修内司终局回执",
-                    parameters: fixerOutputSchema,
-                    async execute(toolCallId, parameters, _signal, _onUpdate, ctx) {
-                        if (packet === undefined || phase === undefined) {
-                            throw new Error("修内司修理包与阶段未装载");
-                        }
-                        const output = deepFreeze(validateFixerOutputForPacket(parameters, phase, packet));
-                        assertAcceptableThroughHost(submissionGate, output.status, output, hostActions, ctx, toolCallId);
-                        if (WORKER_DONE_STATUSES.has(output.status)) {
-                            await pi.requireGatekeeperPass({
-                                context: ctx,
-                                subject: { kind: "worker_completion" },
-                                ...(_signal === undefined ? {} : { signal: _signal }),
-                                hostActions,
-                                toolCallId,
-                            });
-                        }
-                        const acceptedDetails = output;
-                        return {
-                            content: [{ type: "text", text: FIXER_ACCEPTED_TEXT }],
-                            details: acceptedDetails,
-                            terminate: true,
-                        };
-                    },
-                });
-                pi.on("tool_call", (event) => {
-                    if (event.toolName !== "bash")
-                        return;
-                    const command = event.input["command"];
-                    if (typeof command !== "string")
-                        return;
-                    const matched = matchFixerBashForbiddenLiteral(command);
-                    if (matched === undefined)
-                        return;
-                    return {
-                        block: true,
-                        reason: fixerBashSeatbeltDenyReason(matched),
-                    };
-                });
-                pi.on("before_agent_start", (event) => {
-                    if (soul === undefined)
-                        throw new Error("修内司职分未装载");
-                    if (packetPath === undefined)
-                        throw new Error("修内司修理包路径未装载");
-                    // Path delivery only — body is self-fetched; no inline duplicate of flag bytes (#632).
-                    const prerequisitesBlock = prerequisitesPath === undefined
-                        ? ""
-                        : `\n\n<fixer_prerequisites_path>\n${prerequisitesPath}\n</fixer_prerequisites_path>`;
-                    return {
-                        systemPrompt: `${event.systemPrompt}\n\n<fixer_soul>\n${soul}\n</fixer_soul>\n\n<fixer_phase>\n${phase ?? ""}\n</fixer_phase>\n\n<fix_packet_path>\n${packetPath}\n</fix_packet_path>${prerequisitesBlock}`,
-                    };
-                });
-            }
-        },
-        armSubmissionGate(cwd, parent) {
-            submissionGate.arm(cwd, parent);
-        },
-    };
-}
-export function createCoderRoleRuntime(pi, dependencies, hostActions) {
-    let soul;
-    let task;
-    let phase;
-    let binding;
-    let tddInvocationInjected = false;
-    let originalRequest;
-    let expansionPending = false;
-    let expansionCaptured = false;
-    let lifecycleRegistered = false;
-    const submissionGate = createWorkerSubmissionGate();
-    pi.registerFlag("ak-coder-task", {
-        description: "Markdown task assigned to the coder role",
-        type: "string",
-    });
-    pi.registerFlag("ak-coder-phase", {
-        description: "Coder phase: plan (inspect and propose an implementation plan; no edits or commits) or apply (execute the approved plan and verify the first implementation)",
-        type: "string",
-    });
-    return {
-        async activate(ctx) {
-            // Each activation owns its own Skill capture state; prior-session flags must
-            // not authorize a later apply completed (same RoleHost, sequential activate).
-            tddInvocationInjected = false;
-            originalRequest = undefined;
-            expansionPending = false;
-            expansionCaptured = false;
-            soul = (await dependencies.loadSoul()).trim();
-            if (soul.length === 0)
-                throw new Error("Coder soul is empty");
-            const selectedPhase = pi.getFlag("ak-coder-phase");
-            if (selectedPhase !== "plan" && selectedPhase !== "apply") {
-                throw new Error("Coder role requires --ak-coder-phase plan|apply; no other phase is supported");
-            }
-            phase = selectedPhase;
-            const taskPath = pi.getFlag("ak-coder-task");
-            if (typeof taskPath !== "string" || taskPath.trim().length === 0) {
-                throw new Error("Coder role requires --ak-coder-task");
-            }
-            task = (await dependencies.loadTask(taskPath)).trim();
-            if (task.length === 0)
-                throw new Error("Coder task is empty");
-            binding = undefined;
-            if (phase === "apply") {
-                if (dependencies.loadCanonicalSkillBinding === undefined) {
-                    throw new Error("Coder canonical Skill binding loader is not configured");
-                }
-                try {
-                    const loaded = await dependencies.loadCanonicalSkillBinding("tdd");
-                    if (loaded.name !== "tdd") {
-                        throw new Error("Canonical Skill binding loader returned code-review for tdd");
-                    }
-                    binding = loaded;
-                }
-                catch (error) {
-                    if (ctx === undefined)
-                        throw error;
-                    hostActions.failInfrastructure(error, ctx);
-                }
-            }
-            if (!lifecycleRegistered) {
-                lifecycleRegistered = true;
-                pi.registerTool({
-                    name: CODER_OUTPUT_TOOL_NAME,
-                    label: "将作监输出",
-                    description: "提交将作监终局回执；本工具无 escalate 通道。",
-                    promptSnippet: "提交将作监终局回执",
-                    parameters: coderOutputSchema,
-                    async execute(toolCallId, parameters, _signal, _onUpdate, ctx) {
-                        if (task === undefined || phase === undefined) {
-                            throw new Error("将作监任务与阶段未装载");
-                        }
-                        const output = validateWorkerOutput(parameters, phase, "Coder");
-                        if (phase === "apply" && output.status === "completed" &&
-                            !expansionCaptured) {
-                            const rejection = new CoderSkillExpansionEvidenceMissingError();
-                            hostActions.bindSubmissionNonPass(toolCallId, rejection.result);
-                            throw rejection;
-                        }
-                        assertAcceptableThroughHost(submissionGate, output.status, output, hostActions, ctx, toolCallId);
-                        if (WORKER_DONE_STATUSES.has(output.status)) {
-                            await pi.requireGatekeeperPass({
-                                context: ctx,
-                                subject: { kind: "worker_completion" },
-                                ...(_signal === undefined ? {} : { signal: _signal }),
-                                hostActions,
-                                toolCallId,
-                            });
-                        }
-                        const acceptedDetails = output;
-                        return {
-                            content: [{ type: "text", text: CODER_ACCEPTED_TEXT }],
-                            details: acceptedDetails,
-                            terminate: true,
-                        };
-                    },
-                });
-                pi.on("input", (event) => {
-                    if (phase !== "apply" || tddInvocationInjected) {
-                        return { action: "continue" };
-                    }
-                    tddInvocationInjected = true;
-                    expansionPending = true;
-                    // Original request via host capability when Pi argv already carries native form;
-                    // non-pi keeps plain original bytes (no consumer trim; #822 r3 / reviewer-aligned).
-                    // Role never emits or parses `/skill:` (ADR 0082).
-                    originalRequest = binding === undefined
-                        ? event.text
-                        : (pi.capabilities?.skillOriginalRequest?.(binding.name, event.text)
-                            ?? event.text);
-                    return { action: "continue" };
-                });
-                pi.on("before_agent_start", (event, ctx) => {
-                    if (soul === undefined)
-                        throw new Error("将作监职分未装载");
-                    if (phase === "apply") {
-                        if (binding === undefined) {
-                            hostActions.failInfrastructure(new Error("Coder canonical tdd Skill binding was not initialized"), ctx);
-                        }
-                        if (expansionPending) {
-                            expansionPending = false;
-                            if (originalRequest !== undefined) {
-                                expansionCaptured = binding.captureExpansion(pi.capabilities?.skillExpansion(event.prompt), originalRequest) !== undefined;
-                            }
-                        }
-                    }
-                    return {
-                        systemPrompt: `${event.systemPrompt}\n\n<coder_soul>\n${soul}\n</coder_soul>\n\n<coder_phase>\n${phase ?? ""}\n</coder_phase>\n\n<coder_task>\n${task ?? ""}\n</coder_task>`,
-                    };
-                });
-            }
-        },
-        armSubmissionGate(cwd, parent) {
-            submissionGate.arm(cwd, parent);
-        },
-    };
-}