psyclaw 0.25.2 → 0.26.0

package/dist/src/orchestration/pi-executor.js

@@ -0,0 +1,169 @@
+import { BoundedOrchestrator, } from "./runner.js";
+import { PiRpcClient } from "../adapters/pi/rpc.js";
+function blockedReport(task, context, summary) {
+    return {
+        schemaVersion: "psyclaw/worker-report/v1",
+        taskId: task.id,
+        dispatchId: context.dispatchId,
+        outcome: "blocked",
+        summary,
+        filesModified: [],
+        verification: [],
+        blockers: [summary],
+    };
+}
+function textFromMessage(message) {
+    if (!message || typeof message !== "object")
+        return undefined;
+    const content = message.content;
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content
+        .filter((part) => Boolean(part && typeof part === "object" && part.type === "text" && typeof part.text === "string"))
+        .map((part) => part.text)
+        .join("");
+    return text || undefined;
+}
+function extractJson(text) {
+    const trimmed = text.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i)?.[1];
+    const candidate = (fenced ?? trimmed).trim();
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        const start = candidate.indexOf("{");
+        const end = candidate.lastIndexOf("}");
+        if (start < 0 || end <= start)
+            return undefined;
+        try {
+            return JSON.parse(candidate.slice(start, end + 1));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function parseWorkerReport(value, task, context) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    if (record.schemaVersion !== "psyclaw/worker-report/v1")
+        return undefined;
+    if (record.taskId !== task.id || record.dispatchId !== context.dispatchId)
+        return undefined;
+    if (record.outcome !== "succeeded" && record.outcome !== "blocked" && record.outcome !== "failed")
+        return undefined;
+    if (typeof record.summary !== "string" || record.summary.trim() === "")
+        return undefined;
+    if (!Array.isArray(record.filesModified) || !record.filesModified.every((item) => typeof item === "string"))
+        return undefined;
+    if (!Array.isArray(record.blockers) || !record.blockers.every((item) => typeof item === "string"))
+        return undefined;
+    if (!Array.isArray(record.verification))
+        return undefined;
+    if (record.filesModified.length > 0)
+        return undefined;
+    return {
+        schemaVersion: "psyclaw/worker-report/v1",
+        taskId: task.id,
+        dispatchId: context.dispatchId,
+        outcome: record.outcome,
+        summary: record.summary,
+        filesModified: [],
+        verification: record.verification.filter((item) => {
+            if (!item || typeof item !== "object")
+                return false;
+            const candidate = item;
+            return typeof candidate.command === "string" && candidate.command.trim() !== ""
+                && Number.isInteger(candidate.exitCode) && (candidate.outputDigest === undefined || typeof candidate.outputDigest === "string");
+        }),
+        blockers: record.blockers,
+    };
+}
+function lastAssistantText(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type !== "message_end")
+            continue;
+        const text = textFromMessage(event.message);
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+function taskPrompt(task, context) {
+    return [
+        "You are a read-only psyclaw research worker.",
+        "Do not write, edit, delete, execute shell commands, access network services, or modify credentials.",
+        "Inspect only the supplied task inputs and project files with read/grep/find/ls.",
+        "At the end return ONLY one JSON object matching this schema:",
+        '{"schemaVersion":"psyclaw/worker-report/v1","taskId":"...","dispatchId":"...","outcome":"succeeded|blocked|failed","summary":"...","filesModified":[],"verification":[{"command":"...","exitCode":0}],"blockers":[]}',
+        `taskId=${task.id}`,
+        `dispatchId=${context.dispatchId}`,
+        `objective=${task.objective}`,
+        `inputs=${JSON.stringify(task.inputs)}`,
+    ].join("\n");
+}
+/**
+ * Execute one task in a separate Pi process with extensions, skills, context
+ * files and all mutating tools disabled. This is a process boundary, not a
+ * complete OS sandbox; deployments needing hostile-code isolation must add a
+ * container or equivalent runtime policy.
+ */
+export function createPiReadOnlyExecutor(options) {
+    return async (task, context) => {
+        const effects = task.allowedEffects ?? ["read"];
+        if (effects.some((effect) => effect !== "read")) {
+            return { report: blockedReport(task, context, "Pi read-only executor cannot run side-effecting tasks") };
+        }
+        const client = new PiRpcClient({
+            cwd: options.cwd,
+            ...(options.cliPath === undefined ? {} : { cliPath: options.cliPath }),
+            ...(options.command === undefined ? {} : { command: options.command }),
+            ...(options.provider === undefined ? {} : { provider: options.provider }),
+            ...(options.model === undefined ? {} : { model: options.model }),
+            ...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            tools: ["read", "grep", "find", "ls"],
+        });
+        try {
+            await client.start();
+            const events = await client.promptAndWait(taskPrompt(task, context), options.timeoutMs);
+            const report = parseWorkerReport(extractJson(lastAssistantText(events) ?? ""), task, context);
+            if (!report)
+                return { report: blockedReport(task, context, "Worker did not return a valid structured report") };
+            return { report };
+        }
+        catch {
+            return { report: blockedReport(task, context, "Pi worker process failed or timed out") };
+        }
+        finally {
+            await client.stop();
+        }
+    };
+}
+export async function runPlanWithPi(plan, options = { cwd: process.cwd() }) {
+    const executor = createPiReadOnlyExecutor(options);
+    return new BoundedOrchestrator({
+        executor,
+        root: options.root ?? options.cwd,
+        ...(options.maxWorkers === undefined ? {} : { maxWorkers: options.maxWorkers }),
+        allowWrites: false,
+        ...(options.pauseRequested === undefined ? {} : { pauseRequested: options.pauseRequested }),
+        ...(options.onEvent === undefined ? {} : { onEvent: options.onEvent }),
+    }).run(plan);
+}
+export async function resumePlanWithPi(plan, options = { cwd: process.cwd() }) {
+    const executor = createPiReadOnlyExecutor(options);
+    return new BoundedOrchestrator({
+        executor,
+        root: options.root ?? options.cwd,
+        ...(options.maxWorkers === undefined ? {} : { maxWorkers: options.maxWorkers }),
+        allowWrites: false,
+        ...(options.pauseRequested === undefined ? {} : { pauseRequested: options.pauseRequested }),
+        ...(options.onEvent === undefined ? {} : { onEvent: options.onEvent }),
+    }).resume(plan);
+}
+//# sourceMappingURL=pi-executor.js.map

package/dist/src/orchestration/pi-executor.js.map

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

package/dist/src/orchestration/runner.d.ts

@@ -0,0 +1,196 @@
+import { Type } from "typebox";
+import type { Effect, ToolReceipt } from "../core/contracts.js";
+import type { Plan, TaskNode, WorkerReport } from "./contracts.js";
+/**
+ * The planner boundary intentionally has no tool or filesystem capability.
+ * A caller gives us an opaque planner result and we only accept a strict Plan.
+ */
+export interface PlannerRequest {
+    goal: string;
+    paradigm?: string;
+    runId?: string;
+}
+export type Planner = (request: PlannerRequest) => unknown | Promise<unknown>;
+export declare const PlanSchema: Type.TObject<{
+    schemaVersion: Type.TLiteral<"psyclaw/plan/v1">;
+    runId: Type.TString;
+    tasks: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        role: Type.TUnion<[Type.TLiteral<"planner">, Type.TLiteral<"researcher">, Type.TLiteral<"analyst">, Type.TLiteral<"critic">, Type.TLiteral<"writer">, Type.TLiteral<"verifier">]>;
+        objective: Type.TString;
+        deps: Type.TArray<Type.TString>;
+        ownedPaths: Type.TArray<Type.TString>;
+        parallelSafe: Type.TBoolean;
+        inputs: Type.TArray<Type.TString>;
+        outputs: Type.TArray<Type.TString>;
+        allowedEffects: Type.TOptional<Type.TArray<Type.TUnion<[Type.TLiteral<"read">, Type.TLiteral<"write">, Type.TLiteral<"network">, Type.TLiteral<"destructive">]>>>;
+        completionContract: Type.TObject<{
+            requiredArtifacts: Type.TArray<Type.TString>;
+            requiredReceiptEffects: Type.TArray<Type.TUnion<[Type.TLiteral<"read">, Type.TLiteral<"write">, Type.TLiteral<"network">, Type.TLiteral<"destructive">]>>;
+            mustPassGates: Type.TArray<Type.TString>;
+        }>;
+    }>>;
+    budget: Type.TObject<{
+        maxTurns: Type.TInteger;
+        maxWorkers: Type.TInteger;
+    }>;
+    horizon: Type.TOptional<Type.TObject<{
+        strategy: Type.TLiteral<"hierarchical-plan-act-reflect">;
+        maxIterations: Type.TInteger;
+        reflectionEvery: Type.TInteger;
+    }>>;
+}>;
+export declare class PlanSchemaError extends Error {
+    readonly diagnostics: string[];
+    constructor(diagnostics: string[]);
+}
+/** Parse and validate the only value a planner is allowed to hand to runtime. */
+export declare function validatePlanSchema(value: unknown): Plan;
+/** Alias used by integrations that call the boundary an "accepted plan". */
+export declare const acceptPlan: typeof validatePlanSchema;
+/** Execute a planner with no ambient tool context, then enforce the Plan schema. */
+export declare function planOnly(planner: Planner, request: PlannerRequest): Promise<Plan>;
+export interface WorkerArtifact {
+    path: string;
+    sha256?: string;
+}
+export interface WorkerExecutionResult {
+    report: WorkerReport;
+    artifacts?: (string | WorkerArtifact)[];
+    receipts?: ToolReceipt[];
+    passedGates?: string[];
+    /** Optional revision generated by the coordinator; stale revisions are rejected. */
+    specRevision?: string;
+}
+export interface WorkerContext {
+    runId: string;
+    dispatchId: string;
+    attempt: number;
+    task: TaskNode;
+    /** MVP workers receive this as true and should only inspect inputs. */
+    readOnly: boolean;
+    signal: AbortSignal;
+}
+export type WorkerExecutor = (task: TaskNode, context: WorkerContext) => WorkerExecutionResult | WorkerReport | Promise<WorkerExecutionResult | WorkerReport>;
+export interface OrchestratorOptions {
+    executor: WorkerExecutor;
+    /** Project root used for the default checkpoint location. */
+    root?: string;
+    checkpointPath?: string;
+    /** An input fingerprint that must remain stable across resume. */
+    inputDigest?: string;
+    /** Coordinator revision that must remain stable across resume. */
+    specRevision?: string;
+    /** Runtime budget; a resume may explicitly raise this after human approval. */
+    maxTurns?: number;
+    /** Can only lower the plan's worker count; never raises the hard cap of four. */
+    maxWorkers?: number;
+    /** Explicit human-approved write mode. It is false by default. */
+    allowWrites?: boolean;
+    /** Grants network effects. `allowWrites` never implies this. */
+    allowNetwork?: boolean;
+    /** Grants destructive effects. `allowWrites` never implies this. */
+    allowDestructive?: boolean;
+    now?: () => string;
+    onEvent?: (event: RunnerEvent) => void | Promise<void>;
+    /** Cooperative pause hook checked between task batches. */
+    pauseRequested?: () => boolean | Promise<boolean>;
+}
+export interface RunnerEvent {
+    type: "planned" | "started" | "completed" | "blocked" | "checkpoint";
+    runId: string;
+    at: string;
+    taskId?: string;
+    dispatchId?: string;
+    message?: string;
+}
+export type TaskRunStatus = "pending" | "running" | "succeeded" | "failed" | "blocked";
+export interface TaskCheckpoint {
+    status: TaskRunStatus;
+    dispatchId?: string;
+    attempt: number;
+    report?: WorkerReport;
+    artifacts: string[];
+    artifactRecords?: WorkerArtifact[];
+    receipts: ToolReceipt[];
+    passedGates: string[];
+}
+export interface RunnerCheckpoint {
+    schemaVersion: "psyclaw/orchestrator-checkpoint/v1";
+    runId: string;
+    planHash: string;
+    inputDigest?: string;
+    specRevision?: string;
+    budgetLimit: number;
+    budgetUsed: number;
+    tasks: Record<string, TaskCheckpoint>;
+    writtenPaths: string[];
+    updatedAt: string;
+}
+export interface OrchestrationResult {
+    runId: string;
+    status: "completed" | "paused" | "blocked";
+    planHash: string;
+    budgetUsed: number;
+    checkpoint?: RunnerCheckpoint;
+    reports: WorkerReport[];
+    diagnostics: string[];
+}
+export interface NormalizedWorkerResult {
+    report: WorkerReport;
+    artifacts: string[];
+    artifactRecords?: WorkerArtifact[];
+    artifactErrors?: string[];
+    receipts: ToolReceipt[];
+    passedGates: string[];
+    specRevision?: string;
+    schemaValid: boolean;
+}
+/**
+ * A deliberately small coordinator. It owns scheduling and acceptance, while
+ * the executor owns the actual Pi/skill/MCP call. No model output can mutate
+ * task state without passing the checks below.
+ */
+export declare class BoundedOrchestrator {
+    private readonly options;
+    private checkpointWrite;
+    constructor(options: OrchestratorOptions);
+    run(planValue: unknown): Promise<OrchestrationResult>;
+    resume(planValue: unknown): Promise<OrchestrationResult>;
+    private execute;
+    private dispatch;
+    /** Persist failure experience as a pending lesson; human approval promotes it. */
+    private draftReflection;
+    private checkpointPath;
+    private allowedEffects;
+    private taskAllowsWrite;
+    private taskIsReadOnly;
+    private persist;
+    private markBlocked;
+    private emit;
+    private timestamp;
+    private assertCheckpointPath;
+    private blocked;
+    private blockedWithoutPlan;
+    private result;
+}
+/** Alias kept short for callers that do not need the implementation name. */
+export declare const Orchestrator: typeof BoundedOrchestrator;
+export declare function runPlan(plan: unknown, options: OrchestratorOptions): Promise<OrchestrationResult>;
+export declare function resumePlan(plan: unknown, options: OrchestratorOptions): Promise<OrchestrationResult>;
+export interface CompletionAcceptance {
+    ok: boolean;
+    reasons: string[];
+}
+export declare function verifyWorkerCompletion(task: TaskNode, result: NormalizedWorkerResult | WorkerExecutionResult, policy?: {
+    readOnly: boolean;
+    writtenPaths?: readonly string[];
+    artifactRoot?: string;
+    allowedEffects?: ReadonlySet<Effect>;
+    seenIdempotencyKeys?: readonly string[];
+    expectedRunId?: string;
+    expectedTaskId?: string;
+    expectedDispatchId?: string;
+    expectedSpecRevision?: string;
+    reservedPaths?: readonly string[];
+}): CompletionAcceptance;