toolcraft 0.0.2 → 0.0.4

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

@@ -0,0 +1,196 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import { UserError, resolveCommandSecrets } from "../index.js";
+import { ensureApprovalList } from "./approval-tasks.js";
+import { resolveProvider } from "./gate.js";
+export async function runApproval(approvalId, runtimeOptions, root) {
+    const { tasks } = await ensureApprovalList(runtimeOptions);
+    const task = await tasks.get(approvalId);
+    if (task.state !== "pending") {
+        return;
+    }
+    const approval = readApprovalPayload(task);
+    const provider = resolveProvider(runtimeOptions);
+    try {
+        const approvalResult = await provider.requestApproval({
+            message: approval.message,
+            declineInputPrompt: approval.declineInputPrompt ?? undefined,
+        });
+        if (approvalResult.outcome === "declined") {
+            await tasks.fire(approvalId, "decline", {
+                metadataPatch: {
+                    error: {
+                        reason: approvalResult.reason,
+                    },
+                },
+            });
+            return;
+        }
+    }
+    catch (error) {
+        await failPendingApproval(tasks, approvalId, error);
+        return;
+    }
+    await tasks.fire(approvalId, "start", {
+        metadataPatch: {
+            pid: process.pid,
+        },
+    });
+    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) {
+            await tasks.fire(approvalId, "fail", {
+                metadataPatch: {
+                    error: {
+                        message: "result not JSON-serializable",
+                    },
+                },
+            });
+            return;
+        }
+        await tasks.fire(approvalId, "succeed", {
+            metadataPatch: {
+                result: serializedResult.value,
+            },
+        });
+    }
+    catch (error) {
+        await tasks.fire(approvalId, "fail", {
+            metadataPatch: {
+                error: errorMetadataFromUnknown(error),
+            },
+        });
+    }
+}
+function readApprovalPayload(task) {
+    const metadata = task.metadata;
+    if (typeof metadata !== "object" || metadata === null) {
+        throw new UserError(`Malformed approval metadata for "${task.qualifiedId}".`);
+    }
+    if (metadata.schemaVersion !== 1) {
+        throw new UserError(`Malformed approval metadata for "${task.qualifiedId}".`);
+    }
+    if (typeof metadata.commandPath !== "string" ||
+        typeof metadata.message !== "string" ||
+        typeof metadata.params !== "object" ||
+        metadata.params === null) {
+        throw new UserError(`Malformed approval metadata for "${task.qualifiedId}".`);
+    }
+    const declineInputPrompt = typeof metadata.declineInputPrompt === "string" || metadata.declineInputPrompt === null
+        ? metadata.declineInputPrompt
+        : undefined;
+    return {
+        approvalId: typeof metadata.approvalId === "string" ? metadata.approvalId : undefined,
+        commandPath: metadata.commandPath,
+        params: metadata.params,
+        message: metadata.message,
+        declineInputPrompt,
+        enqueuedAt: typeof metadata.enqueuedAt === "string" ? metadata.enqueuedAt : undefined,
+        pid: typeof metadata.pid === "number" || metadata.pid === null ? metadata.pid : undefined,
+        result: metadata.result,
+        error: metadata.error,
+    };
+}
+function findCommand(root, commandPath) {
+    const pathSegments = commandPath.split(".").filter((segment) => segment.length > 0);
+    if (pathSegments.length === 0) {
+        throw new UserError(`Unknown approval command path "${commandPath}".`);
+    }
+    let current = root;
+    for (const segment of pathSegments) {
+        if (current.kind !== "group") {
+            throw new UserError(`Unknown approval command path "${commandPath}".`);
+        }
+        const next = current.children.find((child) => child.name === segment);
+        if (next === undefined) {
+            throw new UserError(`Unknown approval command path "${commandPath}".`);
+        }
+        current = next;
+    }
+    if (current.kind !== "command") {
+        throw new UserError(`Unknown approval command path "${commandPath}".`);
+    }
+    return current;
+}
+function createHandlerContext(command, params) {
+    return {
+        params,
+        secrets: resolveCommandSecrets(command),
+        fetch: globalThis.fetch,
+        fs: createFs(),
+        env: createEnv(),
+        progress() {
+            return undefined;
+        },
+    };
+}
+function createFs() {
+    return {
+        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
+        writeFile: async (path, contents) => {
+            await writeFile(path, contents);
+        },
+        exists: async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+function createEnv(values = process.env) {
+    return {
+        get(key) {
+            return values[key];
+        },
+    };
+}
+function serializeJsonResult(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined) {
+            return {
+                ok: false,
+            };
+        }
+        return {
+            ok: true,
+            value: JSON.parse(serialized),
+        };
+    }
+    catch {
+        return {
+            ok: false,
+        };
+    }
+}
+function errorMetadataFromUnknown(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return {
+        name: "Error",
+        message: String(error),
+    };
+}
+async function failPendingApproval(tasks, approvalId, error) {
+    await tasks.fire(approvalId, "start", {
+        metadataPatch: {
+            pid: process.pid,
+        },
+    });
+    await tasks.fire(approvalId, "fail", {
+        metadataPatch: {
+            error: errorMetadataFromUnknown(error),
+        },
+    });
+}

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

@@ -0,0 +1,3 @@
+import type { HumanInLoopRuntimeOptions } from "./types.js";
+export declare function spawnApprovalRunner(approvalId: string, runtimeOptions: HumanInLoopRuntimeOptions, spawnFn?: typeof import("node:child_process").spawn): void;
+export default spawnApprovalRunner;

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

@@ -0,0 +1,16 @@
+import { spawn } from "node:child_process";
+export function spawnApprovalRunner(approvalId, runtimeOptions, spawnFn) {
+    const { execPath, entryArgs } = runtimeOptions.binPath ?? {
+        execPath: process.execPath,
+        entryArgs: [process.argv[1]],
+    };
+    const fn = spawnFn ?? spawn;
+    const child = fn(execPath, [...entryArgs, "approvals", "run", approvalId], {
+        detached: true,
+        stdio: "ignore",
+        env: process.env,
+        cwd: process.cwd(),
+    });
+    child.unref();
+}
+export default spawnApprovalRunner;

package/dist/human-in-loop/state-machine.d.ts

@@ -0,0 +1,4 @@
+import type { StateMachineDef } from "@poe-code/task-list";
+export type ApprovalState = "pending" | "approved-running" | "approved-done" | "approved-failed" | "declined";
+export type ApprovalEvent = "start" | "succeed" | "fail" | "decline";
+export declare const approvalStateMachine: StateMachineDef<ApprovalState, ApprovalEvent>;

package/dist/human-in-loop/state-machine.js

@@ -0,0 +1,10 @@
+export const approvalStateMachine = {
+    initial: "pending",
+    states: ["pending", "approved-running", "approved-done", "approved-failed", "declined"],
+    events: {
+        start: { from: ["pending"], to: "approved-running" },
+        succeed: { from: ["approved-running"], to: "approved-done" },
+        fail: { from: ["approved-running"], to: "approved-failed" },
+        decline: { from: ["pending"], to: "declined" },
+    },
+};

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

@@ -0,0 +1,41 @@
+import type { HumanInLoopProvider } from "@poe-code/agent-human-in-loop";
+import type { TaskList } from "@poe-code/task-list";
+import type { ObjectSchema, Static } from "toolcraft-schema";
+import { UserError } from "../user-error.js";
+export interface HumanInLoopConfig<TParamsSchema extends ObjectSchema<any>> {
+    mode: "sync" | "async";
+    message: (ctx: {
+        params: Static<TParamsSchema>;
+        commandPath: string;
+    }) => string;
+    declineInputPrompt?: string;
+}
+export interface HumanInLoopRuntimeOptions {
+    provider?: HumanInLoopProvider;
+    taskList?: TaskList | {
+        dir: string;
+        format: "markdown-dir" | "yaml-file";
+    };
+    listName?: string;
+    binPath?: {
+        execPath: string;
+        entryArgs: readonly string[];
+    };
+}
+export interface HumanInLoopPending {
+    status: "pending-approval";
+    approvalId: string;
+    message: string;
+    enqueuedAt: string;
+}
+export declare class ApprovalDeclinedError extends UserError {
+    readonly reason?: string;
+    readonly approvalId?: string;
+    readonly commandPath: string;
+    constructor(options: {
+        commandPath: string;
+        reason?: string;
+        approvalId?: string;
+    });
+}
+export type { HumanInLoopProvider } from "@poe-code/agent-human-in-loop";

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

@@ -0,0 +1,13 @@
+import { UserError } from "../user-error.js";
+export class ApprovalDeclinedError extends UserError {
+    reason;
+    approvalId;
+    commandPath;
+    constructor(options) {
+        super(options.reason === undefined ? "Declined." : `Declined: ${options.reason}`);
+        this.name = "ApprovalDeclinedError";
+        this.reason = options.reason;
+        this.approvalId = options.approvalId;
+        this.commandPath = options.commandPath;
+    }
+}

package/dist/index.compile-check.js

@@ -38,6 +38,30 @@ const ignoredGroup = defineGroup({
     children: [ignoredCommand],
     default: ignoredCommand,
 });
+const ignoredMcpGroup = defineGroup({
+    name: "mcp-root",
+    mcp: {
+        transport: "stdio",
+        command: "server",
+    },
+    children: [],
+});
+const ignoredToolsGroup = defineGroup({
+    name: "tools-root",
+    tools: ["usage"],
+    children: [],
+});
+const ignoredRenameGroup = defineGroup({
+    name: "rename-root",
+    rename: {
+        usage: "bot.create",
+    },
+    children: [],
+});
+const ignoredPlainGroup = defineGroup({
+    name: "plain-root",
+    children: [],
+});
 const ignoredStringSchema = S.String();
 const ignoredNumberSchema = S.Number();
 const ignoredBooleanSchema = S.Boolean();

package/dist/index.d.ts

@@ -1,10 +1,19 @@
+import type { McpServerConfig } from "@poe-code/agent-mcp-config";
 import type { ObjectSchema, Static } from "toolcraft-schema";
 import type { LoggerOutput, RenderTableOptions, ThemePalette } from "@poe-code/design-system";
+import { ApprovalDeclinedError } from "./human-in-loop/types.js";
+import type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntimeOptions } from "./human-in-loop/types.js";
+import { UserError } from "./user-error.js";
 type ScopeValue = "cli" | "mcp" | "sdk";
 type AnyObjectSchema = ObjectSchema<Record<string, never>>;
 type EmptyServices = Record<string, never>;
 type ScopeInput = readonly Scope[] | undefined;
+type HumanInLoopMode = "sync" | "async";
+type HumanInLoopModeInput = HumanInLoopMode | null | undefined;
 export type Scope = ScopeValue;
+type ResolveOwnHumanInLoopMode<TValue> = TValue extends {
+    mode: infer TMode extends HumanInLoopMode;
+} ? TMode : TValue extends null ? null : undefined;
 export interface SecretDefinition {
     env: string;
     description?: string;
@@ -83,6 +92,7 @@ export interface CommandConfig<TServices extends object, TParamsSchema extends O
     secrets?: TSecrets;
     scope?: Scope[];
     confirm?: boolean;
+    humanInLoop?: HumanInLoopConfig<TParamsSchema> | null;
     requires?: Requires<CommandCheckContext<TParamsSchema, TSecrets, TServices>>;
     handler: (ctx: HandlerContext<TParamsSchema, TSecrets, TServices>) => Promise<TResult>;
     render?: Renderers<TResult>;
@@ -97,6 +107,7 @@ export interface Command<TServices extends object = EmptyServices, TParamsSchema
     secrets: SecretDeclarations;
     scope: Scope[];
     confirm: boolean;
+    humanInLoop?: HumanInLoopConfig<TParamsSchema> | null;
     requires?: Requires<any>;
     handler: (ctx: HandlerContext<TParamsSchema, TSecrets, TServices>) => Promise<TResult>;
     render?: Renderers<TResult>;
@@ -105,8 +116,12 @@ export interface GroupConfig<TServices extends object> {
     name: string;
     description?: string;
     aliases?: string[];
+    mcp?: McpServerConfig;
     scope?: Scope[];
+    humanInLoop?: HumanInLoopConfig<AnyObjectSchema> | null;
     secrets?: SecretDeclarations;
+    tools?: string[];
+    rename?: Record<string, string>;
     requires?: Requires<GroupCheckContext<TServices>>;
     children: Array<CommandNode<TServices>>;
     default?: Command<TServices, any, any, any>;
@@ -117,32 +132,32 @@ export interface Group<TServices extends object = EmptyServices> {
     description?: string;
     aliases: string[];
     scope?: Scope[];
+    humanInLoop?: HumanInLoopConfig<AnyObjectSchema> | null;
     secrets: SecretDeclarations;
     requires?: Requires<any>;
     children: Array<CommandNode<TServices>>;
     default?: Command<TServices, any, any, any>;
 }
 export type CommandNode<TServices extends object = EmptyServices> = Command<TServices, any, any, any> | Group<TServices>;
-export interface CommandTypeInfo<TName extends string = string, TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TResult = unknown, TOwnScope extends ScopeInput = ScopeInput> {
+export interface CommandTypeInfo<TName extends string = string, TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TResult = unknown, TOwnScope extends ScopeInput = ScopeInput, TOwnHumanInLoopMode extends HumanInLoopModeInput = undefined> {
     name: TName;
     params: TParamsSchema;
     result: TResult;
     ownScope: TOwnScope;
+    ownHumanInLoopMode: TOwnHumanInLoopMode;
 }
-export interface GroupTypeInfo<TServices extends object = EmptyServices, TName extends string = string, TChildren extends readonly unknown[] = readonly CommandNode<TServices>[], TOwnScope extends ScopeInput = ScopeInput> {
+export interface GroupTypeInfo<TServices extends object = EmptyServices, TName extends string = string, TChildren extends readonly unknown[] = readonly CommandNode<TServices>[], TOwnScope extends ScopeInput = ScopeInput, TOwnHumanInLoopMode extends HumanInLoopModeInput = undefined> {
     name: TName;
     children: TChildren;
     ownScope: TOwnScope;
+    ownHumanInLoopMode: TOwnHumanInLoopMode;
 }
-type TypedCommandMetadata<TName extends string, TParamsSchema extends ObjectSchema<any>, TResult, TOwnScope extends ScopeInput> = {
-    readonly __agentKitCommandTypeInfo: CommandTypeInfo<TName, TParamsSchema, TResult, TOwnScope>;
+type TypedCommandMetadata<TName extends string, TParamsSchema extends ObjectSchema<any>, TResult, TOwnScope extends ScopeInput, TOwnHumanInLoopMode extends HumanInLoopModeInput> = {
+    readonly __agentKitCommandTypeInfo: CommandTypeInfo<TName, TParamsSchema, TResult, TOwnScope, TOwnHumanInLoopMode>;
 };
-type TypedGroupMetadata<TServices extends object, TName extends string, TChildren extends readonly unknown[], TOwnScope extends ScopeInput> = {
-    readonly __agentKitGroupTypeInfo: GroupTypeInfo<TServices, TName, TChildren, TOwnScope>;
+type TypedGroupMetadata<TServices extends object, TName extends string, TChildren extends readonly unknown[], TOwnScope extends ScopeInput, TOwnHumanInLoopMode extends HumanInLoopModeInput> = {
+    readonly __agentKitGroupTypeInfo: GroupTypeInfo<TServices, TName, TChildren, TOwnScope, TOwnHumanInLoopMode>;
 };
-export declare class UserError extends Error {
-    constructor(message: string);
-}
 export interface CommandRequirementOptions {
     apiVersion?: string;
     authEnvVar?: string;
@@ -150,15 +165,19 @@ export interface CommandRequirementOptions {
 }
 export declare function resolveCommandSecrets(command: Command<any, any, any, any>, env?: Record<string, string | undefined>): Record<string, string | undefined>;
 export declare function assertCommandRequirements(command: Command<any, any, any, any>, context: GroupCheckContext<any>, options?: CommandRequirementOptions): Promise<void>;
-export declare function defineCommand<TServices extends object = EmptyServices, TName extends string = string, TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TSecrets extends SecretDeclarations | undefined = undefined, TResult = unknown, TOwnScope extends ScopeInput = undefined>(config: Omit<CommandConfig<TServices, TParamsSchema, TSecrets, TResult>, "name" | "scope"> & {
+export declare function defineCommand<TServices extends object = EmptyServices, TName extends string = string, TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TSecrets extends SecretDeclarations | undefined = undefined, TResult = unknown, TOwnScope extends ScopeInput = undefined, TOwnHumanInLoop extends HumanInLoopConfig<TParamsSchema> | null | undefined = undefined>(config: Omit<CommandConfig<TServices, TParamsSchema, TSecrets, TResult>, "name" | "scope" | "humanInLoop"> & {
     name: TName;
     scope?: TOwnScope;
-}): Command<TServices, TParamsSchema, TSecrets, TResult> & TypedCommandMetadata<TName, TParamsSchema, TResult, TOwnScope>;
-export declare function defineGroup<TServices extends object = EmptyServices, TName extends string = string, TChildren extends readonly unknown[] = readonly CommandNode<TServices>[], TOwnScope extends ScopeInput = undefined>(config: Omit<GroupConfig<TServices>, "name" | "children" | "scope"> & {
+    humanInLoop?: TOwnHumanInLoop;
+}): Command<TServices, TParamsSchema, TSecrets, TResult> & TypedCommandMetadata<TName, TParamsSchema, TResult, TOwnScope, ResolveOwnHumanInLoopMode<TOwnHumanInLoop>>;
+export declare function defineGroup<TServices extends object = EmptyServices, TName extends string = string, TChildren extends readonly unknown[] = readonly CommandNode<TServices>[], TOwnScope extends ScopeInput = undefined, TOwnHumanInLoop extends HumanInLoopConfig<AnyObjectSchema> | null | undefined = undefined>(config: Omit<GroupConfig<TServices>, "name" | "children" | "scope" | "humanInLoop"> & {
     name: TName;
     children: TChildren & readonly CommandNode<TServices>[];
     scope?: TOwnScope;
-}): Group<TServices> & TypedGroupMetadata<TServices, TName, TChildren, TOwnScope>;
+    humanInLoop?: TOwnHumanInLoop;
+}): Group<TServices> & TypedGroupMetadata<TServices, TName, TChildren, TOwnScope, ResolveOwnHumanInLoopMode<TOwnHumanInLoop>>;
 export declare function getCommandSourcePath(command: Command<any, any, any, any>): string | undefined;
 export { S, toJsonSchema } from "toolcraft-schema";
+export { ApprovalDeclinedError, UserError };
 export type { AnySchema, ArraySchema, BooleanSchema, EnumSchema, JsonSchema, NumberSchema, ObjectSchema, OptionalSchema, Static, StringSchema } from "toolcraft-schema";
+export type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntimeOptions };

package/dist/index.js

@@ -1,13 +1,10 @@
 import { fileURLToPath } from "node:url";
+import { ApprovalDeclinedError } from "./human-in-loop/types.js";
+import { mergeHumanInLoopFromGroup, validateHumanInLoopOnDefine } from "./human-in-loop/config.js";
+import { UserError } from "./user-error.js";
 const commandConfigSymbol = Symbol("toolcraft.command.config");
 const groupConfigSymbol = Symbol("toolcraft.group.config");
 const commandSourcePathSymbol = Symbol("toolcraft.command.sourcePath");
-export class UserError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "UserError";
-    }
-}
 function cloneScope(scope) {
     return scope === undefined ? undefined : [...scope];
 }
@@ -34,6 +31,52 @@ function cloneRequires(requires) {
         check: requires.check,
     };
 }
+function cloneStringArray(values) {
+    return values === undefined ? undefined : [...values];
+}
+function cloneStringRecord(values) {
+    return values === undefined ? undefined : { ...values };
+}
+function cloneMcpServerConfig(config) {
+    if (config === undefined) {
+        return undefined;
+    }
+    if (config.transport === "stdio") {
+        return {
+            transport: "stdio",
+            command: config.command,
+            args: cloneStringArray(config.args),
+            env: cloneStringRecord(config.env),
+        };
+    }
+    return {
+        transport: "http",
+        url: config.url,
+        headers: cloneStringRecord(config.headers),
+    };
+}
+function cloneRenameMap(rename) {
+    return rename === undefined ? undefined : { ...rename };
+}
+function validateRenameMap(rename) {
+    if (rename === undefined) {
+        return;
+    }
+    const seenTargets = new Map();
+    for (const [upstreamName, targetPath] of Object.entries(rename)) {
+        if (targetPath.length === 0) {
+            throw new UserError(`Invalid rename target for upstream tool "${upstreamName}": path cannot be empty.`);
+        }
+        if (targetPath.split(".").some((segment) => segment.length === 0)) {
+            throw new UserError(`Invalid rename target for upstream tool "${upstreamName}": "${targetPath}" contains an empty segment.`);
+        }
+        const existingUpstreamName = seenTargets.get(targetPath);
+        if (existingUpstreamName !== undefined) {
+            throw new UserError(`Duplicate rename target "${targetPath}" for upstream tools "${existingUpstreamName}" and "${upstreamName}".`);
+        }
+        seenTargets.set(targetPath, upstreamName);
+    }
+}
 function parseStackPath(candidate) {
     if (candidate.startsWith("file://")) {
         try {
@@ -224,6 +267,7 @@ function createBaseCommand(config) {
         secrets: cloneSecrets(config.secrets),
         scope: resolveCommandScope(config.scope, undefined),
         confirm: config.confirm ?? false,
+        humanInLoop: config.humanInLoop,
         requires: cloneRequires(config.requires),
         handler: config.handler,
         render: config.render,
@@ -231,6 +275,7 @@ function createBaseCommand(config) {
     Object.defineProperty(command, commandConfigSymbol, {
         value: {
             scope: cloneScope(config.scope),
+            humanInLoop: config.humanInLoop,
             secrets: cloneSecrets(config.secrets),
             requires: cloneRequires(config.requires),
             sourcePath: inferCommandSourcePath(),
@@ -245,6 +290,7 @@ function createBaseGroup(config) {
         description: config.description,
         aliases: [...(config.aliases ?? [])],
         scope: resolveGroupScope(config.scope, undefined),
+        humanInLoop: config.humanInLoop,
         secrets: cloneSecrets(config.secrets),
         requires: cloneRequires(config.requires),
         children: [],
@@ -252,8 +298,12 @@ function createBaseGroup(config) {
     };
     Object.defineProperty(group, groupConfigSymbol, {
         value: {
+            mcp: cloneMcpServerConfig(config.mcp),
             scope: cloneScope(config.scope),
+            humanInLoop: config.humanInLoop,
             secrets: cloneSecrets(config.secrets),
+            tools: cloneStringArray(config.tools),
+            rename: cloneRenameMap(config.rename),
             requires: cloneRequires(config.requires),
             children: [...config.children],
             default: config.default,
@@ -279,6 +329,7 @@ function materializeCommand(command, inherited) {
         secrets: mergeSecrets(inherited.secrets, internal.secrets),
         scope: resolveCommandScope(internal.scope, inherited.scope),
         confirm: command.confirm,
+        humanInLoop: mergeHumanInLoopFromGroup(inherited.humanInLoop, internal.humanInLoop),
         requires: mergeRequires(inherited.requires, internal.requires),
         handler: command.handler,
         render: command.render,
@@ -286,6 +337,7 @@ function materializeCommand(command, inherited) {
     Object.defineProperty(materialized, commandConfigSymbol, {
         value: {
             scope: cloneScope(internal.scope),
+            humanInLoop: internal.humanInLoop,
             secrets: cloneSecrets(internal.secrets),
             requires: cloneRequires(internal.requires),
             sourcePath: internal.sourcePath,
@@ -296,16 +348,18 @@ function materializeCommand(command, inherited) {
     });
     return materialized;
 }
+function mergeInheritedMetadata(group, inherited) {
+    return {
+        scope: resolveGroupScope(group.scope, inherited.scope),
+        humanInLoop: mergeHumanInLoopFromGroup(inherited.humanInLoop, group.humanInLoop),
+        secrets: mergeSecrets(inherited.secrets, group.secrets),
+        requires: mergeRequires(inherited.requires, group.requires),
+    };
+}
 function materializeGroup(group, inherited) {
     const internal = getInternalGroupConfig(group);
-    const scope = resolveGroupScope(internal.scope, inherited.scope);
-    const secrets = mergeSecrets(inherited.secrets, internal.secrets);
-    const requires = mergeRequires(inherited.requires, internal.requires);
-    const materializedChildren = internal.children.map((child) => materializeNode(child, {
-        scope,
-        secrets,
-        requires,
-    }));
+    const mergedInherited = mergeInheritedMetadata(internal, inherited);
+    const materializedChildren = internal.children.map((child) => materializeNode(child, mergedInherited));
     let defaultChild;
     if (internal.default !== undefined) {
         const defaultIndex = internal.children.indexOf(internal.default);
@@ -323,16 +377,21 @@ function materializeGroup(group, inherited) {
         name: group.name,
         description: group.description,
         aliases: [...group.aliases],
-        scope,
-        secrets,
-        requires,
+        scope: mergedInherited.scope,
+        humanInLoop: mergedInherited.humanInLoop,
+        secrets: mergedInherited.secrets,
+        requires: mergedInherited.requires,
         children: materializedChildren,
         default: defaultChild,
     };
     Object.defineProperty(materialized, groupConfigSymbol, {
         value: {
+            mcp: cloneMcpServerConfig(internal.mcp),
             scope: cloneScope(internal.scope),
+            humanInLoop: internal.humanInLoop,
             secrets: cloneSecrets(internal.secrets),
+            tools: cloneStringArray(internal.tools),
+            rename: cloneRenameMap(internal.rename),
             requires: cloneRequires(internal.requires),
             children: [...internal.children],
             default: internal.default,
@@ -347,15 +406,20 @@ function materializeNode(node, inherited) {
     return materializeGroup(node, inherited);
 }
 export function defineCommand(config) {
+    validateHumanInLoopOnDefine(config);
     return materializeCommand(createBaseCommand(config), {
         scope: undefined,
+        humanInLoop: undefined,
         secrets: {},
         requires: undefined,
     });
 }
 export function defineGroup(config) {
+    validateRenameMap(config.rename);
+    validateHumanInLoopOnDefine(config);
     return materializeGroup(createBaseGroup(config), {
         scope: undefined,
+        humanInLoop: undefined,
         secrets: {},
         requires: undefined,
     });
@@ -364,3 +428,4 @@ export function getCommandSourcePath(command) {
     return command[commandSourcePathSymbol];
 }
 export { S, toJsonSchema } from "toolcraft-schema";
+export { ApprovalDeclinedError, UserError };

package/dist/json-schema-converter.d.ts

@@ -0,0 +1,21 @@
+import type { AnySchema } from "toolcraft-schema";
+type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "array" | "object" | "null";
+export interface JsonSchema {
+    $defs?: Record<string, JsonSchema>;
+    $ref?: string;
+    additionalProperties?: boolean | JsonSchema;
+    anyOf?: readonly JsonSchema[];
+    const?: unknown;
+    default?: unknown;
+    description?: string;
+    enum?: readonly unknown[];
+    items?: JsonSchema;
+    nullable?: boolean;
+    oneOf?: readonly JsonSchema[];
+    pattern?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    type?: JsonSchemaType | readonly JsonSchemaType[];
+}
+export declare function convertJsonSchema(schema: JsonSchema): AnySchema;
+export {};