toolcraft 0.0.99 → 0.0.100

package/composition.json

@@ -48,7 +48,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.99",
+      "version": "0.0.100",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -48,7 +48,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.99",
+      "version": "0.0.100",
       "license": "MIT"
     },
     {

package/dist/human-in-loop/approval-tasks.d.ts

@@ -1,11 +1,14 @@
 import type { OpenTaskListOptions, TaskList, Tasks } from "@poe-code/task-list";
 import type { HumanInLoopPending, HumanInLoopRuntimeOptions } from "./types.js";
+import { type ApprovalPlanValue } from "./plan-hash.js";
 export interface ApprovalPayload {
     approvalId?: string;
     commandPath: string;
     params: Record<string, unknown>;
     message: string;
     declineInputPrompt?: string | null;
+    plan?: ApprovalPlanValue;
+    planHash?: string;
     enqueuedAt?: string;
     pid?: number | null;
     result?: unknown;

package/dist/human-in-loop/approval-tasks.js

@@ -2,6 +2,7 @@ import { TaskAlreadyExistsError, TaskNotFoundError, openTaskList } from "@poe-co
 import { randomBytes } from "node:crypto";
 import { UserError } from "../user-error.js";
 import { approvalStateMachine } from "./state-machine.js";
+import { isApprovalPlanValue } from "./plan-hash.js";
 const DEFAULT_LIST_NAME = "approvals";
 const openedTaskListsByRuntime = new WeakMap();
 const validatedListsByRuntime = new WeakMap();
@@ -84,28 +85,36 @@ function isListValidated(runtimeOptions, listName) {
 }
 function createApprovalRecord(payload, enqueuedAt) {
     const approvalId = `${enqueuedAt.slice(0, 19).replaceAll(":", "-")}-${randomBytes(3).toString("hex")}`;
-    return {
+    const metadata = {
+        schemaVersion: 1,
+        approvalId,
+        commandPath: payload.commandPath,
+        params: payload.params,
+        message: payload.message,
+        declineInputPrompt: payload.declineInputPrompt ?? null,
+        enqueuedAt,
+        pid: null,
+        result: null,
+        error: null
+    };
+    const pending = {
+        status: "pending-approval",
+        approvalId,
+        message: payload.message,
+        enqueuedAt
+    };
+    const approval = {
         approvalId,
         name: `${payload.commandPath} (${enqueuedAt})`,
-        metadata: {
-            schemaVersion: 1,
-            approvalId,
-            commandPath: payload.commandPath,
-            params: payload.params,
-            message: payload.message,
-            declineInputPrompt: payload.declineInputPrompt ?? null,
-            enqueuedAt,
-            pid: null,
-            result: null,
-            error: null
-        },
-        pending: {
-            status: "pending-approval",
-            approvalId,
-            message: payload.message,
-            enqueuedAt
-        }
+        metadata,
+        pending
     };
+    if (payload.plan !== undefined && payload.planHash !== undefined) {
+        approval.metadata.plan = payload.plan;
+        approval.metadata.planHash = payload.planHash;
+        approval.pending.planHash = payload.planHash;
+    }
+    return approval;
 }
 async function createApprovalTask(tasks, approval) {
     await tasks.create({
@@ -198,6 +207,8 @@ function approvalPayloadFromTask(task) {
         declineInputPrompt: typeof metadata.declineInputPrompt === "string" || metadata.declineInputPrompt === null
             ? metadata.declineInputPrompt
             : undefined,
+        plan: isApprovalPlanValue(metadata.plan) ? metadata.plan : undefined,
+        planHash: typeof metadata.planHash === "string" ? metadata.planHash : undefined,
         enqueuedAt: metadata.enqueuedAt,
         pid: typeof metadata.pid === "number" || metadata.pid === null ? metadata.pid : undefined,
         result: metadata.result,

package/dist/human-in-loop/config.js

@@ -12,6 +12,9 @@ export function validateHumanInLoopOnDefine(config) {
     if (typeof config.humanInLoop.message !== "function") {
         throw new Error(`${label} '${config.name}': humanInLoop.message must be a function`);
     }
+    if (config.humanInLoop.plan !== undefined && typeof config.humanInLoop.plan !== "function") {
+        throw new Error(`${label} '${config.name}': humanInLoop.plan must be a function`);
+    }
 }
 export function mergeHumanInLoopFromGroup(groupHumanInLoop, childHumanInLoop) {
     if (childHumanInLoop !== undefined) {

package/dist/human-in-loop/gate.js

@@ -2,6 +2,7 @@ import { enqueueApproval, ensureApprovalList } from "./approval-tasks.js";
 import { defaultProviderForPlatform } from "./default-provider.js";
 import { spawnApprovalRunner } from "./spawn.js";
 import { ApprovalDeclinedError } from "./types.js";
+import { assertApprovalPlanHash, createApprovalPlan, formatApprovalMessage } from "./plan-hash.js";
 const providersByRuntime = new WeakMap();
 let providerWithoutRuntime;
 export function resolveProvider(runtimeOptions) {
@@ -24,10 +25,17 @@ export async function invokeWithHumanInLoop(node, ctx, runtimeOptions, commandPa
     if (!node.humanInLoop) {
         return node.handler(ctx);
     }
-    const message = node.humanInLoop.message({
+    const planContext = {
         params: ctx.params,
         commandPath
-    });
+    };
+    const baseMessage = node.humanInLoop.message(planContext);
+    const approvalPlan = node.humanInLoop.plan === undefined
+        ? undefined
+        : createApprovalPlan(await node.humanInLoop.plan(planContext));
+    const message = approvalPlan === undefined
+        ? baseMessage
+        : formatApprovalMessage(baseMessage, approvalPlan);
     if (node.humanInLoop.mode === "async") {
         const { tasks } = await ensureApprovalList(runtimeOptions);
         const { approvalId, pending } = await (options.enqueueApproval ?? enqueueApproval)({
@@ -36,6 +44,8 @@ export async function invokeWithHumanInLoop(node, ctx, runtimeOptions, commandPa
                 commandPath,
                 params: ctx.params,
                 message,
+                plan: approvalPlan?.value,
+                planHash: approvalPlan?.hash,
                 declineInputPrompt: node.humanInLoop.declineInputPrompt
             }
         });
@@ -55,5 +65,9 @@ export async function invokeWithHumanInLoop(node, ctx, runtimeOptions, commandPa
             commandPath
         });
     }
+    if (approvalPlan !== undefined && node.humanInLoop.plan !== undefined) {
+        const executionPlan = createApprovalPlan(await node.humanInLoop.plan(planContext));
+        assertApprovalPlanHash(approvalPlan.hash, executionPlan.hash);
+    }
     return node.handler(ctx);
 }

package/dist/human-in-loop/plan-hash.d.ts

@@ -0,0 +1,13 @@
+export type ApprovalPlanValue = null | boolean | number | string | ApprovalPlanValue[] | {
+    [key: string]: ApprovalPlanValue;
+};
+export interface ApprovalPlan {
+    value: ApprovalPlanValue;
+    canonical: string;
+    display: string;
+    hash: string;
+}
+export declare function isApprovalPlanValue(value: unknown): value is ApprovalPlanValue;
+export declare function createApprovalPlan(value: unknown): ApprovalPlan;
+export declare function formatApprovalMessage(message: string, plan: ApprovalPlan): string;
+export declare function assertApprovalPlanHash(expectedHash: string, actualHash: string): void;

package/dist/human-in-loop/plan-hash.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { UserError } from "../user-error.js";
+export function isApprovalPlanValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.every(isApprovalPlanValue);
+    }
+    if (typeof value !== "object") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return ((prototype === Object.prototype || prototype === null) &&
+        Object.values(value).every(isApprovalPlanValue));
+}
+function normalizePlan(value, seen) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new UserError("Approval plan numbers must be finite.");
+        }
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new UserError("Approval plan must contain only JSON values.");
+    }
+    if (seen.has(value)) {
+        throw new UserError("Approval plan must not contain circular references.");
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => normalizePlan(item, seen));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new UserError("Approval plan must contain only JSON values.");
+        }
+        const normalized = {};
+        for (const key of Object.keys(value).sort()) {
+            normalized[key] = normalizePlan(value[key], seen);
+        }
+        return normalized;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+export function createApprovalPlan(value) {
+    const normalized = normalizePlan(value, new Set());
+    const canonical = JSON.stringify(normalized);
+    const digest = createHash("sha256").update(canonical).digest("hex");
+    return {
+        value: normalized,
+        canonical,
+        display: JSON.stringify(normalized, null, 2),
+        hash: `sha256:${digest}`
+    };
+}
+export function formatApprovalMessage(message, plan) {
+    return `${message}\n\nPlan:\n${plan.display}\n\nPlan hash: ${plan.hash}`;
+}
+export function assertApprovalPlanHash(expectedHash, actualHash) {
+    if (expectedHash !== actualHash) {
+        throw new UserError(`Approval plan changed after approval. Expected ${expectedHash}, received ${actualHash}.`);
+    }
+}

package/dist/human-in-loop/runner.js

@@ -4,6 +4,7 @@ import { createEnv, createFs } from "../runtime/io.js";
 import { ensureApprovalList } from "./approval-tasks.js";
 import { resolveProvider } from "./gate.js";
 import { createRuntimeLogger } from "../runtime-logging.js";
+import { assertApprovalPlanHash, createApprovalPlan, formatApprovalMessage, isApprovalPlanValue } from "./plan-hash.js";
 const MAX_AVAILABLE_COMMAND_PATHS = 20;
 export async function runApproval(approvalId, runtimeOptions, root) {
     const { tasks } = await ensureApprovalList(runtimeOptions);
@@ -27,6 +28,7 @@ export async function runApproval(approvalId, runtimeOptions, root) {
         throw error;
     }
     try {
+        verifyStoredApprovalPlan(approval);
         const approvalResult = await provider.requestApproval({
             message: approval.message,
             declineInputPrompt: approval.declineInputPrompt ?? undefined
@@ -50,10 +52,32 @@ export async function runApproval(approvalId, runtimeOptions, root) {
         });
         return;
     }
+    let command;
+    let ctx;
+    try {
+        command = findCommand(root, approval.commandPath);
+        ctx = createHandlerContext(command, approval.params);
+        if (approval.planHash !== undefined) {
+            if (command.humanInLoop?.plan === undefined) {
+                throw new UserError("Approval plan can no longer be verified by this command.");
+            }
+            const executionPlan = createApprovalPlan(await command.humanInLoop.plan({
+                params: approval.params,
+                commandPath: approval.commandPath
+            }));
+            assertApprovalPlanHash(approval.planHash, executionPlan.hash);
+        }
+    }
+    catch (error) {
+        await tasks.fire(approvalId, "fail", {
+            metadataPatch: {
+                error: errorMetadataFromUnknown(error)
+            }
+        });
+        return;
+    }
     await tasks.fire(approvalId, "start");
     try {
-        const command = findCommand(root, approval.commandPath);
-        const ctx = createHandlerContext(command, approval.params);
         const result = await command.handler(ctx);
         const serializedResult = serializeJsonResult(result);
         if (!serializedResult.ok) {
@@ -80,6 +104,21 @@ export async function runApproval(approvalId, runtimeOptions, root) {
         });
     }
 }
+function verifyStoredApprovalPlan(approval) {
+    const hasPlan = approval.plan !== undefined;
+    const hasPlanHash = approval.planHash !== undefined;
+    if (!hasPlan && !hasPlanHash) {
+        return;
+    }
+    if (approval.plan === undefined || approval.planHash === undefined) {
+        throw new UserError("Malformed approval plan metadata.");
+    }
+    const storedPlan = createApprovalPlan(approval.plan);
+    assertApprovalPlanHash(approval.planHash, storedPlan.hash);
+    if (!approval.message.endsWith(formatApprovalMessage("", storedPlan))) {
+        throw new UserError("Approval prompt does not match its stored plan hash.");
+    }
+}
 function readApprovalPayload(task) {
     const metadata = task.metadata;
     if (typeof metadata !== "object" || metadata === null) {
@@ -103,6 +142,8 @@ function readApprovalPayload(task) {
         params: metadata.params,
         message: metadata.message,
         declineInputPrompt,
+        plan: isApprovalPlanValue(metadata.plan) ? metadata.plan : undefined,
+        planHash: typeof metadata.planHash === "string" ? metadata.planHash : undefined,
         enqueuedAt: typeof metadata.enqueuedAt === "string" ? metadata.enqueuedAt : undefined,
         pid: typeof metadata.pid === "number" || metadata.pid === null ? metadata.pid : undefined,
         result: metadata.result,

package/dist/human-in-loop/types.d.ts

@@ -8,6 +8,10 @@ export interface HumanInLoopConfig<TParamsSchema extends ObjectSchema<any>> {
         params: Static<TParamsSchema>;
         commandPath: string;
     }) => string;
+    plan?: (ctx: {
+        params: Static<TParamsSchema>;
+        commandPath: string;
+    }) => unknown | Promise<unknown>;
     declineInputPrompt?: string;
 }
 export interface HumanInLoopRuntimeOptions {
@@ -27,6 +31,7 @@ export interface HumanInLoopPending {
     approvalId: string;
     message: string;
     enqueuedAt: string;
+    planHash?: string;
 }
 export declare class ApprovalDeclinedError extends UserError {
     readonly reason?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.99",
+  "version": "0.0.100",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -104,7 +104,7 @@
     "postpack": "node ../../scripts/manage-bundled-workspace-deps.mjs cleanup . toolcraft-design @poe-code/frontmatter @poe-code/agent-mcp-config @poe-code/agent-human-in-loop @poe-code/task-list @poe-code/agent-defs @poe-code/config-mutations @poe-code/process-runner tiny-mcp-client auth-store"
   },
   "dependencies": {
-    "toolcraft-schema": "0.0.99",
+    "toolcraft-schema": "0.0.100",
     "commander": "^13.1.0",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",