toolcraft 0.0.66 → 0.0.68

package/dist/cli.compile-check.js

@@ -18,10 +18,15 @@ const ignoredOptions = {
     fetch: globalThis.fetch,
     controls: {
         debug: true,
+        logLevel: true,
         output: true,
         verbose: true,
         yes: true,
     },
+    logLevel: "warn",
+    logger: (event) => {
+        event.level;
+    },
     humanInLoop: {},
     version: "1.0.0",
 };

package/dist/cli.d.ts

@@ -1,11 +1,12 @@
 import { configureTheme } from "toolcraft-design";
-import type { Group } from "./index.js";
+import type { Group, LogLevel, RuntimeLoggerInput } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import type { HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 export { configureTheme };
 type Casing = "kebab" | "snake";
 export interface CLIControls {
     debug?: boolean;
+    logLevel?: boolean;
     output?: boolean;
     verbose?: boolean;
     yes?: boolean;
@@ -18,6 +19,8 @@ export interface RunCLIOptions<TServices extends object = Record<string, unknown
     controls?: CLIControls;
     fetch?: typeof globalThis.fetch;
     humanInLoop?: HumanInLoopRuntimeOptions;
+    logLevel?: LogLevel;
+    logger?: RuntimeLoggerInput;
     projectRoot?: string;
     rootDisplayName?: string;
     rootUsageName?: string;

package/dist/cli.js

@@ -4,7 +4,6 @@ import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Opti
 import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
 import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
 import { hasOwnErrorCode } from "./error-codes.js";
-import { summarizeHttpError } from "./api-error-summary.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
 import { writeErrorReport } from "./error-report.js";
 import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
@@ -12,6 +11,8 @@ import { resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
 import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { redactHttpBody, redactHttpHeaderValue } from "./redaction.js";
+import { createRuntimeLogger, isLogLevel, LOG_LEVELS } from "./runtime-logging.js";
+import { summarizeHttpError } from "./api-error-summary.js";
 import { renderResult } from "./renderer.js";
 import { renderSourceSnippet } from "./source-snippet.js";
 import { enableSourceMaps, formatDebugStack } from "./stack-trim.js";
@@ -25,11 +26,12 @@ const RESERVED_SERVICE_NAMES = new Set([
     "fetch",
     "fs",
     "env",
+    "diagnostics",
     "progress",
     "runtimeOptions",
     "root"
 ]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
+const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 const NULL_OPTION_VALUE = Symbol("toolcraft.cli.null");
 function inferProgramName(argv) {
     const entrypoint = argv[1];
@@ -641,6 +643,7 @@ function createOption(field, globalLongOptionFlags) {
 function resolveCLIControls(controls) {
     return {
         debug: controls?.debug === true,
+        logLevel: controls?.logLevel === true,
         output: controls?.output === true,
         verbose: controls?.verbose === true,
         yes: controls?.yes === true
@@ -660,6 +663,9 @@ function getGlobalLongOptionFlags(presetsEnabled, versionEnabled, controls) {
     if (controls.debug) {
         flags.push("--debug");
     }
+    if (controls.logLevel) {
+        flags.push("--log-level");
+    }
     if (controls.verbose) {
         flags.push("--verbose");
     }
@@ -699,6 +705,9 @@ function createCommanderOption(flags, description, field) {
 function hasHelpFlag(argv) {
     return argv.some((token) => HELP_FLAGS.has(token));
 }
+function normalizeVerboseAlias(argv) {
+    return argv.map((token) => (token === "-v" ? "--verbose" : token));
+}
 function resolveHelpOutput(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index] ?? "";
@@ -1095,11 +1104,17 @@ function formatGlobalOptionsLine(ctx) {
     if (ctx.controls.output) {
         flags.push("--output <format>");
     }
+    if (ctx.controls.verbose) {
+        flags.push("-v, --verbose");
+    }
     if (ctx.showVersion) {
         flags.push("--version");
     }
     return flags.length > 0 ? `${text.section("Options:")} ${flags.join("  ")}` : "";
 }
+function formatLeafGlobalOptionsLine(ctx) {
+    return ctx.controls.verbose ? `${text.section("Options:")} -v, --verbose` : "";
+}
 function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
     const seen = new Map();
     const visit = (node) => {
@@ -1200,6 +1215,10 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     if (optionRows.length > 0) {
         sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(optionRows)}`);
     }
+    const builtInLine = formatLeafGlobalOptionsLine(globalOptions);
+    if (builtInLine.length > 0) {
+        sections.push(builtInLine);
+    }
     const secretRows = formatSecretRows(command.secrets);
     if (secretRows.length > 0) {
         sections.push(`${text.sectionHeader("Secrets (environment)")}\n${formatHelpOptionList(secretRows)}`);
@@ -1444,7 +1463,9 @@ function isToolcraftHiddenCommander(command) {
 }
 function getToolcraftHiddenDefaultNames(command) {
     const value = Reflect.get(command, "_toolcraftHiddenDefaultNames");
-    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
 }
 function getToolcraftReservedChildNames(command) {
     const value = Reflect.get(command, "_toolcraftReservedChildNames");
@@ -1482,6 +1503,9 @@ function addGlobalOptions(command, presetsEnabled, controls) {
             .preset("trim")
             .argParser(parseDebugStackMode));
     }
+    if (controls.logLevel) {
+        options.push(new Option("--log-level <level>", "Set runtime diagnostic log level.").argParser(parseLogLevel));
+    }
     if (controls.verbose) {
         options.push(new Option("--verbose", "Print detailed runtime diagnostics."));
     }
@@ -1499,6 +1523,26 @@ function parseDebugStackMode(value) {
     }
     throw new InvalidArgumentError(formatInvalidEnumMessage("--debug", String(value), ["raw"], { candidates: ["raw"] }));
 }
+function parseLogLevel(value) {
+    if (isLogLevel(value)) {
+        return value;
+    }
+    throw new InvalidArgumentError(formatInvalidEnumMessage("--log-level", value, [...LOG_LEVELS], {
+        candidates: ["warn", "debug", "trace"],
+        threshold: 3
+    }));
+}
+function writeCLIDiagnosticEvent(event) {
+    const transcript = event.data?.transcript;
+    if (typeof transcript === "string") {
+        process.stderr.write(transcript);
+        return;
+    }
+    if (event.category === "progress" || event.level === "trace") {
+        return;
+    }
+    process.stderr.write(`${event.message}\n`);
+}
 function setNestedValue(target, path, value) {
     let cursor = target;
     for (let index = 0; index < path.length - 1; index += 1) {
@@ -2763,7 +2807,7 @@ function getResolvedFlags(command) {
     const flags = command.optsWithGlobals();
     return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, onErrorReportContext) {
+async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, diagnosticsOptions, onErrorReportContext) {
     const logger = createLogger();
     const primitives = {
         logger,
@@ -2774,6 +2818,13 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
     const optionValues = state.actionCommand.optsWithGlobals();
     const resolvedFlags = optionValues;
     const output = resolveOutput(resolvedFlags);
+    const diagnostics = createRuntimeLogger({
+        level: resolvedFlags.logLevel ??
+            (diagnosticsOptions.verboseControlEnabled && resolvedFlags.verbose
+                ? "trace"
+                : diagnosticsOptions.logLevel),
+        logger: diagnosticsOptions.logger ?? writeCLIDiagnosticEvent
+    });
     const shouldPrompt = !resolvedFlags.yes && Boolean(process.stdin.isTTY);
     const runtime = await resolveFixtureRuntime(state.command, services, requirementOptions, runtimeFetch);
     const preflightContext = {
@@ -2782,7 +2833,9 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
         fetch: runtime.fetch,
         fs: runtime.fs,
         env: runtime.env,
+        diagnostics,
         progress(message) {
+            diagnostics.emit({ level: "info", message, category: "progress" });
             logger.info(message);
         }
     };
@@ -3311,7 +3364,10 @@ function configureCommanderSuggestionOutput(command) {
 }
 export async function runCLI(roots, options = {}) {
     enableSourceMaps();
-    const argv = [...(options.argv ?? process.argv)];
+    const controls = resolveCLIControls(options.controls);
+    const argv = controls.verbose
+        ? normalizeVerboseAlias([...(options.argv ?? process.argv)])
+        : [...(options.argv ?? process.argv)];
     const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
     let lastActionCommand;
     let resolvedCommandPath = "";
@@ -3328,7 +3384,6 @@ export async function runCLI(roots, options = {}) {
         const runtimeOptions = options.humanInLoop ?? {};
         const runtimeFetch = options.fetch ?? globalThis.fetch;
         version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
-        const controls = resolveCLIControls(options.controls);
         const servicesWithBuiltIns = {
             ...services,
             runtimeOptions,
@@ -3343,6 +3398,11 @@ export async function runCLI(roots, options = {}) {
             await renderGeneratedHelp(root, argv, { ...options, version });
             return;
         }
+        if (argv.length <= 2 && root.default?.scope.includes("cli") !== true) {
+            userErrorPattern = "usage";
+            await renderGeneratedHelp(root, argv, { ...options, version });
+            return;
+        }
         program = new CommanderCommand();
         program.name(root.name);
         program.exitOverride();
@@ -3360,7 +3420,11 @@ export async function runCLI(roots, options = {}) {
         const execute = async (state) => {
             lastActionCommand = state.actionCommand;
             resolvedCommandPath = formatCliCommandPath(state.commandPath);
-            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, (context) => {
+            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, {
+                logLevel: options.logLevel,
+                logger: options.logger,
+                verboseControlEnabled: controls.verbose
+            }, (context) => {
                 errorReportContext = context;
             });
         };
@@ -3415,9 +3479,7 @@ export async function runCLI(roots, options = {}) {
             debugStackMode: resolvedFlags !== undefined
                 ? resolveDebugStackMode(resolvedFlags.debug)
                 : getDebugStackModeFromArgv(argv),
-            output: resolvedFlags !== undefined
-                ? resolveOutput(resolvedFlags)
-                : resolveOutputFromArgv(argv),
+            output: resolvedFlags !== undefined ? resolveOutput(resolvedFlags) : resolveOutputFromArgv(argv),
             verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : argv.includes("--verbose"),
             program,
             argv,

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

@@ -3,6 +3,7 @@ import { InvalidTransitionError } from "@poe-code/task-list";
 import { UserError, resolveCommandSecrets } from "../index.js";
 import { ensureApprovalList } from "./approval-tasks.js";
 import { resolveProvider } from "./gate.js";
+import { createRuntimeLogger } from "../runtime-logging.js";
 const MAX_AVAILABLE_COMMAND_PATHS = 20;
 export async function runApproval(approvalId, runtimeOptions, root) {
     const { tasks } = await ensureApprovalList(runtimeOptions);
@@ -15,8 +16,8 @@ export async function runApproval(approvalId, runtimeOptions, root) {
     try {
         await tasks.fire(approvalId, "claim", {
             metadataPatch: {
-                pid: process.pid,
-            },
+                pid: process.pid
+            }
         });
     }
     catch (error) {
@@ -28,15 +29,15 @@ export async function runApproval(approvalId, runtimeOptions, root) {
     try {
         const approvalResult = await provider.requestApproval({
             message: approval.message,
-            declineInputPrompt: approval.declineInputPrompt ?? undefined,
+            declineInputPrompt: approval.declineInputPrompt ?? undefined
         });
         if (approvalResult.outcome === "declined") {
             await tasks.fire(approvalId, "decline", {
                 metadataPatch: {
                     error: {
-                        reason: approvalResult.reason,
-                    },
-                },
+                        reason: approvalResult.reason
+                    }
+                }
             });
             return;
         }
@@ -44,8 +45,8 @@ export async function runApproval(approvalId, runtimeOptions, root) {
     catch (error) {
         await tasks.fire(approvalId, "fail", {
             metadataPatch: {
-                error: errorMetadataFromUnknown(error),
-            },
+                error: errorMetadataFromUnknown(error)
+            }
         });
         return;
     }
@@ -59,23 +60,23 @@ export async function runApproval(approvalId, runtimeOptions, root) {
             await tasks.fire(approvalId, "fail", {
                 metadataPatch: {
                     error: {
-                        message: "result not JSON-serializable",
-                    },
-                },
+                        message: "result not JSON-serializable"
+                    }
+                }
             });
             return;
         }
         await tasks.fire(approvalId, "succeed", {
             metadataPatch: {
-                result: serializedResult.value,
-            },
+                result: serializedResult.value
+            }
         });
     }
     catch (error) {
         await tasks.fire(approvalId, "fail", {
             metadataPatch: {
-                error: errorMetadataFromUnknown(error),
-            },
+                error: errorMetadataFromUnknown(error)
+            }
         });
     }
 }
@@ -105,7 +106,7 @@ function readApprovalPayload(task) {
         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,
+        error: metadata.error
     };
 }
 function findCommand(root, commandPath) {
@@ -170,15 +171,17 @@ function getVisibleCliChildren(root) {
     return root.kind === "group" ? root.children.filter(isNodeVisibleInCli) : [];
 }
 function createHandlerContext(command, params) {
+    const diagnostics = createRuntimeLogger();
     return {
         params,
         secrets: resolveCommandSecrets(command),
         fetch: globalThis.fetch,
         fs: createFs(),
         env: createEnv(),
-        progress() {
-            return undefined;
-        },
+        diagnostics,
+        progress(message) {
+            diagnostics.emit({ level: "info", message, category: "progress" });
+        }
     };
 }
 function createFs() {
@@ -198,14 +201,14 @@ function createFs() {
         },
         lstat: async (path) => lstat(path),
         rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path),
+        unlink: async (path) => unlink(path)
     };
 }
 function createEnv(values = process.env) {
     return {
         get(key) {
             return values[key];
-        },
+        }
     };
 }
 function serializeJsonResult(value) {
@@ -213,17 +216,17 @@ function serializeJsonResult(value) {
         const serialized = JSON.stringify(value);
         if (serialized === undefined) {
             return {
-                ok: false,
+                ok: false
             };
         }
         return {
             ok: true,
-            value: JSON.parse(serialized),
+            value: JSON.parse(serialized)
         };
     }
     catch {
         return {
-            ok: false,
+            ok: false
         };
     }
 }
@@ -232,11 +235,11 @@ function errorMetadataFromUnknown(error) {
         return {
             name: error.name,
             message: error.message,
-            stack: error.stack,
+            stack: error.stack
         };
     }
     return {
         name: "Error",
-        message: String(error),
+        message: String(error)
     };
 }

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import type { LoggerOutput, RenderTableOptions, ThemePalette } from "toolcraft-d
 import { ApprovalDeclinedError } from "./human-in-loop/types.js";
 import type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntimeOptions } from "./human-in-loop/types.js";
 import { ToolcraftBugError, UserError } from "./user-error.js";
+import type { RuntimeLogger } from "./runtime-logging.js";
 type ScopeValue = "cli" | "mcp" | "sdk";
 type AnyObjectSchema = ObjectSchema<Record<string, never>>;
 type EmptyServices = Record<string, never>;
@@ -68,6 +69,7 @@ export type GroupCheckContext<TServices extends object = EmptyServices> = TServi
     fetch: typeof globalThis.fetch;
     fs: HandlerFs;
     env: HandlerEnv;
+    diagnostics: RuntimeLogger;
     progress(message: string): void;
 };
 export type CommandCheckContext<TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TSecrets extends SecretDeclarations | undefined = undefined, TServices extends object = EmptyServices> = TServices & {
@@ -76,6 +78,7 @@ export type CommandCheckContext<TParamsSchema extends ObjectSchema<any> = AnyObj
     fetch: typeof globalThis.fetch;
     fs: HandlerFs;
     env: HandlerEnv;
+    diagnostics: RuntimeLogger;
     progress(message: string): void;
 };
 export interface Requires<TContext = unknown> {
@@ -94,6 +97,7 @@ export type HandlerContext<TParamsSchema extends ObjectSchema<any> = AnyObjectSc
     fetch: typeof globalThis.fetch;
     fs: HandlerFs;
     env: HandlerEnv;
+    diagnostics: RuntimeLogger;
     progress(message: string): void;
 };
 export interface CommandConfig<TServices extends object, TParamsSchema extends ObjectSchema<any>, TSecrets extends SecretDeclarations | undefined, TResult> {
@@ -200,7 +204,9 @@ export { S, toJsonSchema } from "toolcraft-schema";
 export { AuthenticationError, BadRequestError, ClientError, ConflictError, HttpError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, ServiceUnavailableError, UnprocessableEntityError, createHttpError } from "./http-errors.js";
 export type { HttpErrorRequest, HttpErrorResponse } from "./http-errors.js";
 export { ApprovalDeclinedError, ToolcraftBugError, UserError };
+export { createRuntimeLogger, isLogLevel, shouldEmitDiagnostic } from "./runtime-logging.js";
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";
 export type { PackageMetadata } from "./package-metadata.js";
+export type { DiagnosticLogEvent, LogLevel, RuntimeLogger, RuntimeLoggerInput } from "./runtime-logging.js";
 export type { AnySchema, ArraySchema, BooleanSchema, EnumSchema, JsonSchema, NumberSchema, ObjectSchema, OptionalSchema, Static, StringSchema } from "toolcraft-schema";
 export type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntimeOptions };

package/dist/index.js

@@ -236,8 +236,7 @@ function suggestSecretEnv(input, candidates) {
     const lastPart = inputParts[inputParts.length - 1];
     const relatedCandidates = candidates.filter((candidate) => {
         const candidateParts = candidate.split("_");
-        return (candidateParts[0] === firstPart &&
-            candidateParts[candidateParts.length - 1] === lastPart);
+        return (candidateParts[0] === firstPart && candidateParts[candidateParts.length - 1] === lastPart);
     });
     const expandedSuggestions = suggest(input, relatedCandidates, {
         threshold: Math.max(4, Math.floor(input.length / 4))
@@ -473,4 +472,5 @@ export function getCommandSourcePath(command) {
 export { S, toJsonSchema } from "toolcraft-schema";
 export { AuthenticationError, BadRequestError, ClientError, ConflictError, HttpError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, ServiceUnavailableError, UnprocessableEntityError, createHttpError } from "./http-errors.js";
 export { ApprovalDeclinedError, ToolcraftBugError, UserError };
+export { createRuntimeLogger, isLogLevel, shouldEmitDiagnostic } from "./runtime-logging.js";
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { type SDKTransport, type Server as TinyServer } from "tiny-stdio-mcp-server";
-import type { Group } from "./index.js";
+import type { Group, LogLevel, RuntimeLoggerInput } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import { type HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type Casing = "snake" | "camel";
@@ -13,6 +13,8 @@ export interface RunMCPOptions<TServices extends object = Record<string, unknown
     version?: string;
     humanInLoop?: HumanInLoopRuntimeOptions;
     projectRoot?: string;
+    logLevel?: LogLevel;
+    logger?: RuntimeLoggerInput;
     /**
      * Optional allowlist of MCP tool names or group prefixes.
      *

package/dist/mcp.js

@@ -13,17 +13,19 @@ import { filterSchemaForScope } from "./schema-scope.js";
 import { enableSourceMaps } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
+import { createRuntimeLogger } from "./runtime-logging.js";
 const RESERVED_SERVICE_NAMES = new Set([
     "params",
     "secrets",
     "fetch",
     "fs",
     "env",
+    "diagnostics",
     "progress",
     "runtimeOptions",
     "root"
 ]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
+const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 function normalizeRoots(roots) {
     if (!Array.isArray(roots)) {
         return roots;
@@ -755,6 +757,10 @@ function createResolvedMCPServer(root, options) {
     const services = (options.services ?? {});
     const runtimeOptions = options.humanInLoop ?? {};
     const runtimeFetch = options.fetch ?? globalThis.fetch;
+    const diagnostics = createRuntimeLogger({
+        level: options.logLevel,
+        logger: options.logger
+    });
     const servicesWithBuiltIns = {
         ...services,
         runtimeOptions,
@@ -780,8 +786,9 @@ function createResolvedMCPServer(root, options) {
                     fetch: runtimeFetch,
                     fs: createFs(),
                     env: createEnv(),
-                    progress() {
-                        return undefined;
+                    diagnostics,
+                    progress(message) {
+                        diagnostics.emit({ level: "info", message, category: "progress" });
                     }
                 };
                 await assertCommandRequirements(tool.command, { ...baseContext, params: undefined });

package/dist/runtime-logging.d.ts

@@ -0,0 +1,19 @@
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug" | "trace";
+export interface DiagnosticLogEvent {
+    level: Exclude<LogLevel, "silent">;
+    message: string;
+    category?: "runtime" | "http" | "auth" | "retry" | "progress";
+    data?: Record<string, unknown>;
+}
+export interface RuntimeLogger {
+    level: LogLevel;
+    emit(event: DiagnosticLogEvent): void;
+}
+export type RuntimeLoggerInput = RuntimeLogger | ((event: DiagnosticLogEvent) => void);
+export declare const LOG_LEVELS: readonly ["silent", "error", "warn", "info", "debug", "trace"];
+export declare function isLogLevel(value: string): value is LogLevel;
+export declare function shouldEmitDiagnostic(eventLevel: LogLevel, configuredLevel: LogLevel): boolean;
+export declare function createRuntimeLogger(options?: {
+    level?: LogLevel;
+    logger?: RuntimeLoggerInput;
+}): RuntimeLogger;

package/dist/runtime-logging.js

@@ -0,0 +1,42 @@
+const LOG_LEVEL_RANK = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5
+};
+export const LOG_LEVELS = Object.freeze([
+    "silent",
+    "error",
+    "warn",
+    "info",
+    "debug",
+    "trace"
+]);
+export function isLogLevel(value) {
+    return LOG_LEVELS.includes(value);
+}
+export function shouldEmitDiagnostic(eventLevel, configuredLevel) {
+    if (eventLevel === "silent" || configuredLevel === "silent") {
+        return false;
+    }
+    return LOG_LEVEL_RANK[eventLevel] <= LOG_LEVEL_RANK[configuredLevel];
+}
+export function createRuntimeLogger(options = {}) {
+    const level = options.level ?? "warn";
+    const sink = options.logger;
+    return {
+        level,
+        emit(event) {
+            if (!shouldEmitDiagnostic(event.level, level)) {
+                return;
+            }
+            if (typeof sink === "function") {
+                sink(event);
+                return;
+            }
+            sink?.emit(event);
+        }
+    };
+}

package/dist/sdk.d.ts

@@ -1,5 +1,5 @@
 import type { ObjectSchema, Static } from "toolcraft-schema";
-import type { Group, Scope } from "./index.js";
+import type { Group, LogLevel, RuntimeLoggerInput, Scope } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import type { HumanInLoopPending, HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type ScopeInput = readonly Scope[] | undefined;
@@ -69,6 +69,8 @@ export interface CreateSDKOptions<TServices extends object = Record<string, unkn
     apiVersion?: string;
     projectRoot?: string;
     errorReports?: ErrorReportsOption;
+    logLevel?: LogLevel;
+    logger?: RuntimeLoggerInput;
 }
 export declare function createSDK<TRootInfo, TServices extends object = Record<string, unknown>>(root: Group<any> & {
     readonly __agentKitGroupTypeInfo: TRootInfo;

package/dist/sdk.js

@@ -9,17 +9,19 @@ import { filterSchemaForScope } from "./schema-scope.js";
 import { enableSourceMaps } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
+import { createRuntimeLogger } from "./runtime-logging.js";
 const RESERVED_SERVICE_NAMES = new Set([
     "params",
     "secrets",
     "fetch",
     "fs",
     "env",
+    "diagnostics",
     "progress",
     "runtimeOptions",
     "root"
 ]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
+const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 function splitWords(value) {
     const words = [];
     let current = "";
@@ -362,6 +364,10 @@ function createResolvedSDK(root, options = {}) {
     const services = options.services ?? {};
     const runtimeOptions = options.humanInLoop ?? {};
     const runtimeFetch = options.fetch ?? globalThis.fetch;
+    const diagnostics = createRuntimeLogger({
+        level: options.logLevel,
+        logger: options.logger
+    });
     void options.casing;
     validateServices(services);
     function build(node, path) {
@@ -384,8 +390,9 @@ function createResolvedSDK(root, options = {}) {
                         fetch: runtimeFetch,
                         fs: createFs(),
                         env: createEnv(),
-                        progress() {
-                            return undefined;
+                        diagnostics,
+                        progress(message) {
+                            diagnostics.emit({ level: "info", message, category: "progress" });
                         }
                     };
                     await assertCommandRequirements(node, { ...baseContext, params: undefined }, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.66",
+  "version": "0.0.68",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,7 +47,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 mcp-oauth auth-store"
   },
   "dependencies": {
-    "toolcraft-schema": "0.0.66",
+    "toolcraft-schema": "0.0.68",
     "commander": "^14.0.3",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",