toolcraft 0.0.2 → 0.0.3

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

@@ -0,0 +1,31 @@
+import type { OpenTaskListOptions, TaskList, Tasks } from "@poe-code/task-list";
+import type { HumanInLoopPending, HumanInLoopRuntimeOptions } from "./types.js";
+export interface ApprovalPayload {
+    approvalId?: string;
+    commandPath: string;
+    params: Record<string, unknown>;
+    message: string;
+    declineInputPrompt?: string | null;
+    enqueuedAt?: string;
+    pid?: number | null;
+    result?: unknown;
+    error?: unknown;
+}
+export declare function ensureApprovalList(runtimeOptions: HumanInLoopRuntimeOptions | undefined, deps?: {
+    openTaskList?: (options: OpenTaskListOptions) => Promise<TaskList>;
+}): Promise<{
+    taskList: TaskList;
+    listName: string;
+    tasks: Tasks;
+}>;
+export declare function enqueueApproval(ctx: {
+    tasks: Tasks;
+    payload: ApprovalPayload;
+}): Promise<{
+    approvalId: string;
+    pending: HumanInLoopPending;
+}>;
+export declare function loadApproval(ctx: {
+    tasks: Tasks;
+    approvalId: string;
+}): Promise<ApprovalPayload | undefined>;

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

@@ -0,0 +1,201 @@
+import { TaskAlreadyExistsError, TaskNotFoundError, openTaskList } from "@poe-code/task-list";
+import { randomBytes } from "node:crypto";
+import { UserError } from "../user-error.js";
+import { approvalStateMachine } from "./state-machine.js";
+const DEFAULT_LIST_NAME = "approvals";
+const openedTaskListsByRuntime = new WeakMap();
+const validatedListsByRuntime = new WeakMap();
+export async function ensureApprovalList(runtimeOptions, deps = {}) {
+    if (runtimeOptions?.taskList === undefined) {
+        throw new UserError("humanInLoop.taskList required for async-mode commands");
+    }
+    const listName = runtimeOptions.listName ?? DEFAULT_LIST_NAME;
+    const taskList = await resolveTaskList(runtimeOptions, runtimeOptions.taskList, deps.openTaskList ?? openTaskList);
+    const tasks = taskList.list(listName);
+    if (!isListValidated(runtimeOptions, listName)) {
+        if (!isApprovalStateMachine(tasks.stateMachine)) {
+            throw new UserError("approvals task-list configured with a different state machine; pass approvalStateMachine when opening the list");
+        }
+        cacheValidatedList(runtimeOptions, listName);
+    }
+    return {
+        taskList,
+        listName,
+        tasks,
+    };
+}
+export async function enqueueApproval(ctx) {
+    const enqueuedAt = new Date().toISOString();
+    const approval = createApprovalRecord(ctx.payload, enqueuedAt);
+    try {
+        await createApprovalTask(ctx.tasks, approval);
+    }
+    catch (error) {
+        if (!(error instanceof TaskAlreadyExistsError)) {
+            throw error;
+        }
+        const retryApproval = createApprovalRecord(ctx.payload, enqueuedAt);
+        await createApprovalTask(ctx.tasks, retryApproval);
+        return retryApproval;
+    }
+    return approval;
+}
+export async function loadApproval(ctx) {
+    try {
+        const task = await ctx.tasks.get(ctx.approvalId);
+        return approvalPayloadFromTask(task);
+    }
+    catch (error) {
+        if (error instanceof TaskNotFoundError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function resolveTaskList(runtimeOptions, taskList, openTaskListFn) {
+    if (!isTaskListConfig(taskList)) {
+        return taskList;
+    }
+    const cachedTaskList = openedTaskListsByRuntime.get(runtimeOptions);
+    if (cachedTaskList !== undefined) {
+        return cachedTaskList;
+    }
+    const openedTaskList = openTaskListFn({
+        create: true,
+        type: taskList.format,
+        path: taskList.dir,
+        stateMachine: approvalStateMachine,
+    });
+    openedTaskListsByRuntime.set(runtimeOptions, openedTaskList);
+    return openedTaskList;
+}
+function cacheValidatedList(runtimeOptions, listName) {
+    const validatedLists = validatedListsByRuntime.get(runtimeOptions);
+    if (validatedLists === undefined) {
+        validatedListsByRuntime.set(runtimeOptions, new Set([listName]));
+        return;
+    }
+    validatedLists.add(listName);
+}
+function isListValidated(runtimeOptions, listName) {
+    return validatedListsByRuntime.get(runtimeOptions)?.has(listName) ?? false;
+}
+function createApprovalRecord(payload, enqueuedAt) {
+    const approvalId = `${enqueuedAt.slice(0, 19).replaceAll(":", "-")}-${randomBytes(3).toString("hex")}`;
+    return {
+        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,
+        },
+    };
+}
+async function createApprovalTask(tasks, approval) {
+    await tasks.create({
+        id: approval.approvalId,
+        name: approval.name,
+        metadata: approval.metadata,
+    });
+}
+function isApprovalStateMachine(stateMachine) {
+    if (stateMachine === approvalStateMachine) {
+        return true;
+    }
+    return isDeepEqualStateMachine(stateMachine, approvalStateMachine);
+}
+function isTaskListConfig(taskList) {
+    return taskList !== undefined && "dir" in taskList;
+}
+function isDeepEqualStateMachine(left, right) {
+    if (!areEqualStrings(left.states, right.states)) {
+        return false;
+    }
+    const leftEventNames = Object.keys(left.events);
+    const rightEventNames = Object.keys(right.events);
+    if (!areEqualStrings(leftEventNames, rightEventNames)) {
+        return false;
+    }
+    for (const eventName of leftEventNames) {
+        const leftEvent = left.events[eventName];
+        const rightEvent = right.events[eventName];
+        if (leftEvent === undefined || rightEvent === undefined) {
+            return false;
+        }
+        if (leftEvent.to !== rightEvent.to) {
+            return false;
+        }
+        if (!areEqualEventFrom(leftEvent.from, rightEvent.from)) {
+            return false;
+        }
+    }
+    return true;
+}
+function areEqualEventFrom(left, right) {
+    if (left === "*" || right === "*") {
+        return left === right;
+    }
+    return areEqualStrings(left, right);
+}
+function areEqualStrings(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] !== right[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+function approvalPayloadFromTask(task) {
+    const metadata = task.metadata;
+    if (typeof metadata !== "object" || metadata === null) {
+        return undefined;
+    }
+    if (metadata.schemaVersion !== 1) {
+        return undefined;
+    }
+    if (typeof metadata.approvalId !== "string") {
+        return undefined;
+    }
+    if (typeof metadata.commandPath !== "string") {
+        return undefined;
+    }
+    if (typeof metadata.message !== "string") {
+        return undefined;
+    }
+    if (typeof metadata.enqueuedAt !== "string") {
+        return undefined;
+    }
+    if (typeof metadata.params !== "object" || metadata.params === null) {
+        return undefined;
+    }
+    return {
+        approvalId: metadata.approvalId,
+        commandPath: metadata.commandPath,
+        params: metadata.params,
+        message: metadata.message,
+        declineInputPrompt: typeof metadata.declineInputPrompt === "string" || metadata.declineInputPrompt === null
+            ? metadata.declineInputPrompt
+            : undefined,
+        enqueuedAt: metadata.enqueuedAt,
+        pid: typeof metadata.pid === "number" || metadata.pid === null ? metadata.pid : undefined,
+        result: metadata.result,
+        error: metadata.error,
+    };
+}

package/dist/human-in-loop/approvals-commands.d.ts

@@ -0,0 +1,11 @@
+import type { CommandNode, Group } from "../index.js";
+import type { HumanInLoopRuntimeOptions } from "./types.js";
+interface ApprovalBuiltInServices {
+    runtimeOptions: HumanInLoopRuntimeOptions;
+    root: CommandNode<any>;
+}
+export declare const approvalsGroup: Group<ApprovalBuiltInServices> & {
+    readonly __agentKitGroupTypeInfo: import("../index.js").GroupTypeInfo<ApprovalBuiltInServices, string, readonly CommandNode<ApprovalBuiltInServices>[], undefined, undefined>;
+};
+export declare function mergeApprovalsGroup<TServices extends object>(root: Group<TServices>): Group<TServices>;
+export {};

package/dist/human-in-loop/approvals-commands.js

@@ -0,0 +1,191 @@
+import { S } from "toolcraft-schema";
+import { UserError, defineCommand, defineGroup } from "../index.js";
+import { ensureApprovalList } from "./approval-tasks.js";
+import { runApproval } from "./runner.js";
+const approvalsGroupSymbol = Symbol("toolcraft.humanInLoop.approvalsBuiltIn");
+const listScope = ["cli", "mcp", "sdk"];
+const runScope = ["cli"];
+const listParams = S.Object({
+    state: S.Optional(S.String()),
+});
+const showParams = S.Object({
+    approvalId: S.String(),
+});
+export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
+    name: "approvals",
+    description: "Inspect and execute queued approvals.",
+    children: [
+        defineCommand({
+            name: "list",
+            description: "List queued approvals.",
+            scope: listScope,
+            params: listParams,
+            handler: async ({ params, runtimeOptions }) => {
+                const { tasks } = await ensureApprovalList(runtimeOptions);
+                return loadApprovals(tasks, params.state);
+            },
+            render: {
+                rich: (result, primitives) => renderApprovalList(result, primitives),
+                markdown: (result) => renderApprovalListMarkdown(result),
+                json: (result) => result,
+            },
+        }),
+        defineCommand({
+            name: "show",
+            description: "Show one approval.",
+            scope: listScope,
+            params: showParams,
+            handler: async ({ params, runtimeOptions }) => {
+                const { tasks } = await ensureApprovalList(runtimeOptions);
+                return tasks.get(params.approvalId);
+            },
+            render: {
+                rich: (result, primitives) => renderApprovalDetails(result, primitives),
+                markdown: (result) => renderApprovalDetailsMarkdown(result),
+                json: (result) => result,
+            },
+        }),
+        defineCommand({
+            name: "run",
+            description: "Run one queued approval.",
+            scope: runScope,
+            params: showParams,
+            handler: async ({ params, runtimeOptions, root }) => runApproval(params.approvalId, runtimeOptions, root),
+        }),
+    ],
+}));
+export function mergeApprovalsGroup(root) {
+    const existing = root.children.find((child) => child.name === approvalsGroup.name);
+    if (existing !== undefined) {
+        if (isApprovalsBuiltIn(existing)) {
+            return root;
+        }
+        throw new UserError("Error: 'approvals' is reserved for human-in-loop built-ins");
+    }
+    root.children = [...root.children, approvalsGroup];
+    return root;
+}
+function markApprovalsBuiltIn(group) {
+    Object.defineProperty(group, approvalsGroupSymbol, {
+        configurable: false,
+        enumerable: false,
+        value: true,
+        writable: false,
+    });
+    return group;
+}
+function isApprovalsBuiltIn(node) {
+    return node.kind === "group" && node[approvalsGroupSymbol] === true;
+}
+async function loadApprovals(tasks, stateFilter) {
+    const states = splitStateFilter(stateFilter);
+    if (states.length === 0) {
+        return tasks.all();
+    }
+    const seenIds = new Set();
+    const approvals = [];
+    for (const state of states) {
+        const matching = await tasks.all({
+            state,
+        });
+        for (const task of matching) {
+            if (seenIds.has(task.qualifiedId)) {
+                continue;
+            }
+            seenIds.add(task.qualifiedId);
+            approvals.push(task);
+        }
+    }
+    return approvals;
+}
+function splitStateFilter(stateFilter) {
+    if (stateFilter === undefined) {
+        return [];
+    }
+    const seen = new Set();
+    const states = [];
+    for (const value of stateFilter.split(",")) {
+        const trimmed = value.trim();
+        if (trimmed.length === 0 || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        states.push(trimmed);
+    }
+    return states;
+}
+function renderApprovalList(result, { logger, renderTable, getTheme }) {
+    if (result.length === 0) {
+        logger.message("No approvals found.");
+        return;
+    }
+    logger.message(renderTable({
+        theme: getTheme(),
+        columns: [
+            { name: "id", title: "ID", alignment: "left", maxLen: 24 },
+            { name: "state", title: "State", alignment: "left", maxLen: 18 },
+            { name: "name", title: "Name", alignment: "left", maxLen: 60 },
+        ],
+        rows: result.map((task) => ({
+            id: task.id,
+            state: task.state,
+            name: task.name,
+        })),
+    }));
+}
+function renderApprovalListMarkdown(result) {
+    if (result.length === 0) {
+        return "No approvals found.";
+    }
+    const lines = ["| ID | State | Name |", "| :--- | :--- | :--- |"];
+    for (const task of result) {
+        lines.push(`| ${escapeMarkdownCell(task.id)} | ${escapeMarkdownCell(task.state)} | ${escapeMarkdownCell(task.name)} |`);
+    }
+    return lines.join("\n");
+}
+function renderApprovalDetails(result, { logger, renderTable, getTheme }) {
+    logger.message(renderTable({
+        theme: getTheme(),
+        columns: [
+            { name: "key", title: "Key", alignment: "left", maxLen: 18 },
+            { name: "value", title: "Value", alignment: "left", maxLen: 80 },
+        ],
+        rows: Object.entries(taskToRecord(result)).map(([key, value]) => ({
+            key,
+            value: stringifyValue(value),
+        })),
+    }));
+}
+function renderApprovalDetailsMarkdown(result) {
+    return Object.entries(taskToRecord(result))
+        .map(([key, value]) => `- ${key}: ${stringifyValue(value)}`)
+        .join("\n");
+}
+function taskToRecord(task) {
+    return {
+        list: task.list,
+        id: task.id,
+        qualifiedId: task.qualifiedId,
+        name: task.name,
+        state: task.state,
+        description: task.description,
+        metadata: task.metadata,
+    };
+}
+function stringifyValue(value) {
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function escapeMarkdownCell(value) {
+    return value.replaceAll("|", "\\|");
+}

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

@@ -0,0 +1,11 @@
+import type { ObjectSchema } from "toolcraft-schema";
+import type { HumanInLoopConfig } from "./types.js";
+type HumanInLoopValue<TParamsSchema extends ObjectSchema<any>> = HumanInLoopConfig<TParamsSchema> | null | undefined;
+export declare function validateHumanInLoopOnDefine<TParamsSchema extends ObjectSchema<any>>(config: {
+    name: string;
+    confirm?: boolean;
+    children?: readonly unknown[];
+    humanInLoop?: HumanInLoopValue<TParamsSchema>;
+}): void;
+export declare function mergeHumanInLoopFromGroup<TGroupParamsSchema extends ObjectSchema<any>, TChildParamsSchema extends ObjectSchema<any>>(groupHumanInLoop: HumanInLoopValue<TGroupParamsSchema>, childHumanInLoop: HumanInLoopValue<TChildParamsSchema>): HumanInLoopValue<TChildParamsSchema>;
+export {};

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

@@ -0,0 +1,21 @@
+export function validateHumanInLoopOnDefine(config) {
+    const label = Array.isArray(config.children) ? "group" : "command";
+    if (config.confirm === true && config.humanInLoop !== undefined && config.humanInLoop !== null) {
+        throw new Error(`${label} '${config.name}': use either confirm or humanInLoop, not both`);
+    }
+    if (config.humanInLoop === undefined || config.humanInLoop === null) {
+        return;
+    }
+    if (config.humanInLoop.mode !== "sync" && config.humanInLoop.mode !== "async") {
+        throw new Error(`${label} '${config.name}': humanInLoop.mode must be "sync" or "async"`);
+    }
+    if (typeof config.humanInLoop.message !== "function") {
+        throw new Error(`${label} '${config.name}': humanInLoop.message must be a function`);
+    }
+}
+export function mergeHumanInLoopFromGroup(groupHumanInLoop, childHumanInLoop) {
+    if (childHumanInLoop !== undefined) {
+        return childHumanInLoop;
+    }
+    return groupHumanInLoop;
+}

package/dist/human-in-loop/default-provider.d.ts

@@ -0,0 +1,2 @@
+import type { HumanInLoopProvider } from "@poe-code/agent-human-in-loop";
+export declare function defaultProviderForPlatform(): HumanInLoopProvider;

package/dist/human-in-loop/default-provider.js

@@ -0,0 +1,26 @@
+import process from "node:process";
+import { osascriptProvider } from "@poe-code/agent-human-in-loop";
+import { UserError } from "../user-error.js";
+function noProviderConfigured() {
+    return {
+        id: "noProviderConfigured",
+        async requestApproval() {
+            throw new UserError("no human-in-loop provider configured for this platform — pass humanInLoop.provider to the runtime");
+        },
+    };
+}
+function createDefaultProviderFactory() {
+    let provider;
+    return () => {
+        if (provider !== undefined) {
+            return provider;
+        }
+        provider =
+            process.platform === "darwin" ? osascriptProvider({ title: "Approval needed" }) : noProviderConfigured();
+        return provider;
+    };
+}
+const getDefaultProvider = createDefaultProviderFactory();
+export function defaultProviderForPlatform() {
+    return getDefaultProvider();
+}

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

@@ -0,0 +1,4 @@
+import type { Command, HandlerContext } from "../index.js";
+import type { HumanInLoopPending, HumanInLoopProvider, HumanInLoopRuntimeOptions } from "./types.js";
+export declare function resolveProvider(runtimeOptions: HumanInLoopRuntimeOptions | undefined): HumanInLoopProvider;
+export declare function invokeWithHumanInLoop<T>(node: Command<any, any, any, T>, ctx: HandlerContext<any, any, any>, runtimeOptions: HumanInLoopRuntimeOptions | undefined, commandPath: string): Promise<T | HumanInLoopPending>;

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

@@ -0,0 +1,57 @@
+import { enqueueApproval, ensureApprovalList } from "./approval-tasks.js";
+import { defaultProviderForPlatform } from "./default-provider.js";
+import { spawnApprovalRunner } from "./spawn.js";
+import { ApprovalDeclinedError } from "./types.js";
+const providersByRuntime = new WeakMap();
+let providerWithoutRuntime;
+export function resolveProvider(runtimeOptions) {
+    if (runtimeOptions?.provider !== undefined) {
+        return runtimeOptions.provider;
+    }
+    if (runtimeOptions === undefined) {
+        providerWithoutRuntime ??= defaultProviderForPlatform();
+        return providerWithoutRuntime;
+    }
+    const cachedProvider = providersByRuntime.get(runtimeOptions);
+    if (cachedProvider !== undefined) {
+        return cachedProvider;
+    }
+    const provider = defaultProviderForPlatform();
+    providersByRuntime.set(runtimeOptions, provider);
+    return provider;
+}
+export async function invokeWithHumanInLoop(node, ctx, runtimeOptions, commandPath) {
+    if (!node.humanInLoop) {
+        return node.handler(ctx);
+    }
+    const message = node.humanInLoop.message({
+        params: ctx.params,
+        commandPath,
+    });
+    if (node.humanInLoop.mode === "async") {
+        const { tasks } = await ensureApprovalList(runtimeOptions);
+        const { approvalId, pending } = await enqueueApproval({
+            tasks,
+            payload: {
+                commandPath,
+                params: ctx.params,
+                message,
+                declineInputPrompt: node.humanInLoop.declineInputPrompt,
+            },
+        });
+        spawnApprovalRunner(approvalId, runtimeOptions);
+        return pending;
+    }
+    const provider = resolveProvider(runtimeOptions);
+    const result = await provider.requestApproval({
+        message,
+        declineInputPrompt: node.humanInLoop.declineInputPrompt,
+    });
+    if (result.outcome === "declined") {
+        throw new ApprovalDeclinedError({
+            reason: result.reason,
+            commandPath,
+        });
+    }
+    return node.handler(ctx);
+}

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

@@ -0,0 +1,7 @@
+export { defaultProviderForPlatform } from "./default-provider.js";
+export { invokeWithHumanInLoop } from "./gate.js";
+export { approvalStateMachine } from "./state-machine.js";
+export { ApprovalDeclinedError } from "./types.js";
+export type { ApprovalEvent, ApprovalState } from "./state-machine.js";
+export type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntimeOptions } from "./types.js";
+export type { HumanInLoopProvider } from "@poe-code/agent-human-in-loop";

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

@@ -0,0 +1,4 @@
+export { defaultProviderForPlatform } from "./default-provider.js";
+export { invokeWithHumanInLoop } from "./gate.js";
+export { approvalStateMachine } from "./state-machine.js";
+export { ApprovalDeclinedError } from "./types.js";

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

@@ -0,0 +1,3 @@
+import type { CommandNode } from "../index.js";
+import type { HumanInLoopRuntimeOptions } from "./types.js";
+export declare function runApproval(approvalId: string, runtimeOptions: HumanInLoopRuntimeOptions, root: CommandNode<any>): Promise<void>;