qlogicagent 0.5.2 → 0.6.0

package/dist/types/skills/tools/shell/exec-permissions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Environment variables that can safely appear as prefixes.
+ * Ported from cc's SAFE_ENV_VARS.
+ *
+ * NEVER add:
+ *   PATH, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*   (execution/library loading)
+ *   PYTHONPATH, NODE_PATH, CLASSPATH, RUBYLIB     (module loading)
+ *   GOFLAGS, RUSTFLAGS, NODE_OPTIONS              (code execution flags)
+ *   HOME, TMPDIR, SHELL, BASH_ENV                 (system behavior)
+ */
+export declare const SAFE_ENV_VARS: Set<string>;
+/**
+ * Commands that execute their arguments — should not be treated
+ * as "first word" for permission prefix matching.
+ * Ported from cc's BARE_SHELL_PREFIXES.
+ */
+export declare const BARE_SHELL_PREFIXES: Set<string>;
+/**
+ * Strip safe env var prefixes and wrapper commands.
+ * Ported from cc's `stripSafeWrappers()`.
+ *
+ * `NODE_ENV=test timeout 30 grep -r foo .` → `grep -r foo .`
+ */
+export declare function stripSafeWrappers(command: string): string;
+/**
+ * Aggressively strip ALL leading env vars (not just safe ones).
+ * Used for deny-rule matching where the env prefix doesn't change
+ * the dangerousness of the underlying command.
+ * Ported from cc's `stripAllLeadingEnvVars()`.
+ */
+export declare function stripAllLeadingEnvVars(command: string, blocklist?: RegExp): string;
+/**
+ * Extract `<cmd> <subcommand>` prefix for rule matching.
+ * E.g. `git commit -m "foo"` → `git commit`
+ * Ported from cc's `getSimpleCommandPrefix()`.
+ */
+export declare function getSimpleCommandPrefix(command: string): string | null;
+/**
+ * Extract the first command word for prefix-based rule matching.
+ * Ported from cc's `getFirstWordPrefix()`.
+ */
+export declare function getFirstWordPrefix(command: string): string | null;
+/**
+ * Strip argv-level wrapper commands.
+ * Ported from cc's `stripWrappersFromArgv()`.
+ */
+export declare function stripWrappersFromArgv(argv: string[]): string[];
+/**
+ * Detect blocking sleep/wait patterns in commands.
+ * Ported from cc's `detectBlockedSleepPattern()`.
+ */
+export declare function detectBlockedSleepPattern(command: string): string | null;

package/dist/types/skills/tools/shell/index.d.ts

@@ -0,0 +1,17 @@
+export type { ShellType, BuildCommandOpts, BuiltCommand, ShellProvider, } from "./shell-provider.js";
+export { isPowerShellToolEnabled, getDefaultShellType, generateCommandId, } from "./shell-provider.js";
+export { createBashProvider } from "./bash-provider.js";
+export type { BashProviderOptions } from "./bash-provider.js";
+export { createPowerShellProvider, encodePowerShellCommand, } from "./powershell-provider.js";
+export type { CommandClassification } from "./command-classification.js";
+export { SEARCH_COMMANDS, READ_COMMANDS, LIST_COMMANDS, SEMANTIC_NEUTRAL_COMMANDS, SILENT_COMMANDS, classifyCommand, commandHasAnyCd, } from "./command-classification.js";
+export { SAFE_ENV_VARS, BARE_SHELL_PREFIXES, stripSafeWrappers, stripAllLeadingEnvVars, getSimpleCommandPrefix, getFirstWordPrefix, stripWrappersFromArgv, detectBlockedSleepPattern, } from "./exec-permissions.js";
+export { getDestructiveCommandWarning, getPowerShellDestructiveCommandWarning, } from "./destructive-command-warning.js";
+export type { CommandSemanticResult } from "./command-semantics.js";
+export { interpretCommandResult } from "./command-semantics.js";
+export { TaskOutput, generateTaskId, getTaskOutputDir, setTaskOutputDir, getTaskOutputPath, MAX_TASK_OUTPUT_BYTES, } from "./task-output.js";
+export type { ProgressCallback } from "./task-output.js";
+export type { ExecResult, ShellCommand } from "./shell-command.js";
+export { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
+export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, } from "./shell-exec.js";
+export type { ExecOptions } from "./shell-exec.js";

package/dist/types/skills/tools/shell/powershell-provider.d.ts

@@ -0,0 +1,15 @@
+import type { ShellProvider } from "./shell-provider.js";
+/**
+ * Encode a PowerShell command as UTF-16LE Base64 for -EncodedCommand.
+ * This avoids all quoting/escaping issues when passing complex commands
+ * through cmd.exe or other shell wrappers.
+ *
+ * Ported directly from cc's `encodePowerShellCommand()`.
+ */
+export declare function encodePowerShellCommand(psCommand: string): string;
+/**
+ * Create a PowerShell ShellProvider.
+ *
+ * @param shellPath Absolute path to pwsh.exe or powershell.exe
+ */
+export declare function createPowerShellProvider(shellPath: string): ShellProvider;

package/dist/types/skills/tools/shell/shell-command.d.ts

@@ -0,0 +1,54 @@
+import type { ChildProcess } from "node:child_process";
+import { TaskOutput } from "./task-output.js";
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    /** Exit code. 137 = SIGKILL, 143 = SIGTERM, 145 = aborted. */
+    code: number;
+    /** Whether the process was interrupted (killed or timed out). */
+    interrupted: boolean;
+    /** Set when backgrounded. */
+    backgroundTaskId?: string;
+    /** Set when the user explicitly backgrounded. */
+    backgroundedByUser?: boolean;
+    /** Set when assistant mode auto-backgrounded. */
+    assistantAutoBackgrounded?: boolean;
+    /** Path to raw output file for large outputs. */
+    outputFilePath?: string;
+    /** Total output file size in bytes. */
+    outputFileSize?: number;
+    /** Error message when command failed before spawning. */
+    preSpawnError?: string;
+}
+export interface ShellCommand {
+    /** Move the process to background. Returns true if successful. */
+    background(taskId: string): boolean;
+    /** Promise resolving when the process exits. */
+    result: Promise<ExecResult>;
+    /** Kill the process immediately. */
+    kill(): void;
+    /** Current lifecycle status. */
+    status: "running" | "backgrounded" | "completed" | "killed";
+    /** Clean up stream resources and listeners. */
+    cleanup(): void;
+    /** Register timeout callback (for auto-backgrounding). */
+    onTimeout?: (callback: (backgroundFn: (taskId: string) => boolean) => void) => void;
+    /** Output container. */
+    taskOutput: TaskOutput;
+}
+/**
+ * Wrap a child process with lifecycle management.
+ * Ported from cc's wrapSpawn().
+ */
+export declare function wrapSpawn(childProcess: ChildProcess, abortSignal: AbortSignal, timeout: number, taskOutput: TaskOutput, shouldAutoBackground?: boolean, maxOutputBytes?: number): ShellCommand;
+/**
+ * Create a ShellCommand for commands that were aborted before execution.
+ */
+export declare function createAbortedCommand(backgroundTaskId?: string, opts?: {
+    stderr?: string;
+    code?: number;
+}): ShellCommand;
+/**
+ * Create a ShellCommand for commands that failed before spawn.
+ */
+export declare function createFailedCommand(preSpawnError: string): ShellCommand;

package/dist/types/skills/tools/shell/shell-exec.d.ts

@@ -0,0 +1,33 @@
+import type { ShellProvider, ShellType } from "./shell-provider.js";
+import { type ShellCommand } from "./shell-command.js";
+import { type ProgressCallback } from "./task-output.js";
+export type { ExecResult } from "./shell-command.js";
+export declare function getCwd(): string;
+export declare function setCwd(path: string, relativeTo?: string): void;
+export declare function getOriginalCwd(): string;
+export declare function initCwd(cwd: string): void;
+export interface ExecOptions {
+    timeout?: number;
+    onProgress?: ProgressCallback;
+    /** When true, `cd` in the command does NOT update the session CWD. */
+    preventCwdChanges?: boolean;
+    shouldAutoBackground?: boolean;
+    /** When provided, stdout is piped and this callback fires per chunk. */
+    onStdout?: (data: string) => void;
+}
+/**
+ * Set the shell provider for this session.
+ * Must be called once at startup by the host.
+ */
+export declare function setShellProvider(provider: ShellProvider): void;
+/**
+ * Get the current shell provider, or throw if not configured.
+ */
+export declare function getShellProvider(): ShellProvider;
+/**
+ * Execute a shell command using the configured provider.
+ * Creates a new child process for each invocation.
+ *
+ * Ported from cc's Shell.ts — the tool owns process lifecycle.
+ */
+export declare function exec(command: string, abortSignal: AbortSignal, shellType?: ShellType, options?: ExecOptions): Promise<ShellCommand>;

package/dist/types/skills/tools/shell/shell-provider.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Discriminated shell type identifier.
+ */
+export type ShellType = "bash" | "powershell";
+/**
+ * Options passed to `buildExecCommand`.
+ */
+export interface BuildCommandOpts {
+    /** Unique command invocation ID (for CWD temp-file naming). */
+    id: string;
+    /** If set, sandbox TMPDIR root. */
+    sandboxTmpDir?: string;
+    /** Whether sandbox mode is active. */
+    useSandbox: boolean;
+}
+/**
+ * Result of `buildExecCommand` — the final command string
+ * and the path where the shell will write its post-command CWD.
+ */
+export interface BuiltCommand {
+    /** Fully-wrapped command string ready for spawn. */
+    commandString: string;
+    /**
+     * Temp file path where the shell writes its post-command CWD.
+     * Used by the host to track `cd` across invocations.
+     * undefined if CWD tracking is not supported / not needed.
+     */
+    cwdFilePath?: string;
+}
+/**
+ * Runtime-agnostic shell provider.
+ *
+ * Hosts (Gateway / Desktop / Hub) create a provider once, then
+ * use it for every `exec()` call. The tool itself never
+ * `spawn()`s — the host does, using args from this provider.
+ */
+export interface ShellProvider {
+    /** Shell type discriminator. */
+    readonly type: ShellType;
+    /** Absolute path to the shell binary. */
+    readonly shellPath: string;
+    /**
+     * Whether `spawn()` should use `detached: true`.
+     * Bash: true (allows job control / cleanup).
+     * PowerShell: false (no POSIX process groups on Windows).
+     */
+    readonly detached: boolean;
+    /**
+     * Wrap a raw user command into a full shell command string.
+     * Handles:
+     *   - Environment snapshots / session env sourcing (bash)
+     *   - UTF-16LE EncodedCommand wrapping (PowerShell)
+     *   - CWD tracking (`pwd -P > file` / `Get-Location | Out-File`)
+     *   - stdin redirect for interactive commands (bash)
+     */
+    buildExecCommand(command: string, opts: BuildCommandOpts): Promise<BuiltCommand>;
+    /**
+     * Return the argv array for `child_process.spawn()`.
+     * E.g. bash → `['-c', commandString]`
+     *      PS   → `['-NoProfile', '-NonInteractive', '-Command', cmd]`
+     */
+    getSpawnArgs(commandString: string): string[];
+    /**
+     * Return extra environment variables to merge into spawn env.
+     * E.g. `{ SHELL: '/bin/bash', GIT_EDITOR: 'true', CLAUDECODE: '1' }`
+     */
+    getEnvironmentOverrides(command: string): Promise<Record<string, string>>;
+}
+/**
+ * Check if PowerShell tool mode should be enabled.
+ * Mirrors cc's `isPowerShellToolEnabled()`.
+ *
+ * On Windows: enabled when `QLOGICAGENT_USE_POWERSHELL` is truthy.
+ * On non-Windows: always false.
+ */
+export declare function isPowerShellToolEnabled(): boolean;
+/**
+ * Default shell type for the current platform.
+ */
+export declare function getDefaultShellType(): ShellType;
+/**
+ * Generate a short random hex ID for CWD temp file naming.
+ * Matches cc's `Math.floor(Math.random() * 0x10000).toString(16)`.
+ */
+export declare function generateCommandId(): string;

package/dist/types/skills/tools/shell/task-output.d.ts

@@ -0,0 +1,45 @@
+/** Progress callback — matches cc's signature. */
+export type ProgressCallback = (lastLines: string, allLines: string, totalLines: number, totalBytes: number, isIncomplete: boolean) => void;
+/** Max output file on disk (background tasks). */
+export declare const MAX_TASK_OUTPUT_BYTES: number;
+export declare const MAX_TASK_OUTPUT_BYTES_DISPLAY = "5GB";
+/** Lazily generate session-scoped task output directory. */
+export declare function getTaskOutputDir(): string;
+/** Set the task output directory (for embedding hosts to override). */
+export declare function setTaskOutputDir(dir: string): void;
+export declare function getTaskOutputPath(taskId: string): string;
+export declare function generateTaskId(prefix?: string): string;
+/**
+ * Single source of truth for a shell command's output.
+ * Ported from cc's TaskOutput.
+ *
+ * For bash commands (file mode): both stdout/stderr go to file fd.
+ * For hooks (pipe mode): data flows through writeStdout/writeStderr.
+ */
+export declare class TaskOutput {
+    #private;
+    readonly taskId: string;
+    readonly path: string;
+    readonly stdoutToFile: boolean;
+    constructor(taskId: string, onProgress: ProgressCallback | null, stdoutToFile?: boolean, maxMemory?: number);
+    /** Write stdout data (pipe mode). */
+    writeStdout(data: string): void;
+    /** Write stderr data (pipe mode). */
+    writeStderr(data: string): void;
+    /** Get captured stdout. For file mode, reads from disk. */
+    getStdout(): Promise<string>;
+    /** Get captured stderr. In file mode stderr is interleaved with stdout. */
+    getStderr(): string;
+    get outputFileSize(): number;
+    /**
+     * Whether the output file content is fully contained in getStdout().
+     * If true, the file can be deleted.
+     */
+    get outputFileRedundant(): boolean;
+    /** Write in-memory buffer to disk file. */
+    spillToDisk(): void;
+    /** Delete the output file on disk. */
+    deleteOutputFile(): Promise<void>;
+    /** Clean up all resources. */
+    clear(): void;
+}

package/dist/types/skills/tools/skill-invoke-tool.d.ts

@@ -0,0 +1,46 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { WorkspaceSkill } from "../skill-system/skill-types.js";
+export declare const SKILL_TOOL_NAME: "skill_invoke";
+export interface SkillInvokeParams {
+    skill: string;
+    args?: string;
+}
+export declare const SKILL_INVOKE_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly skill: {
+            readonly type: "string";
+            readonly description: "Name of the skill to invoke. Use skill_list to see available skills.";
+        };
+        readonly args: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["skill"];
+};
+export interface SkillToolDeps {
+    /**
+     * Get all available skills (Layer 0 metadata).
+     * Returns name + description pairs for tool manifest enrichment.
+     */
+    listSkills(): WorkspaceSkill[];
+    /**
+     * Read skill content (Layer 1 instructions).
+     * Returns the full SKILL.md content for the named skill.
+     * Returns null if skill not found.
+     */
+    readSkillContent(name: string): Promise<string | null>;
+    /**
+     * Execute the skill instructions as a sub-turn.
+     * The implementation should:
+     *   1. Build system prompt from SKILL.md content
+     *   2. Run a sub-turn (fork) with skill instructions
+     *   3. Return the sub-turn's final response
+     *
+     * If not provided, the skill content is returned directly
+     * (the LLM can then follow the instructions in context).
+     */
+    executeSkillSubturn?(skillName: string, skillContent: string, userArgs: string | undefined, signal?: AbortSignal): Promise<string>;
+}
+export declare function createSkillTool(deps: SkillToolDeps): PortableTool<SkillInvokeParams>;

package/dist/types/skills/tools/skill-list-tool.d.ts

@@ -0,0 +1,33 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SKILL_LIST_TOOL_NAME: "skill_list";
+export interface SkillListToolParams {
+    category?: string;
+}
+export declare const SKILL_LIST_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly category: {
+            readonly type: "string";
+            readonly description: "Filter skills by category (e.g. 'devops', 'mlops'). Omit to list all.";
+        };
+    };
+    readonly required: readonly [];
+};
+export interface SkillListItem {
+    name: string;
+    description: string;
+    version?: string;
+    category?: string;
+}
+export interface SkillListOutput {
+    skills: SkillListItem[];
+    categories: string[];
+}
+/**
+ * Host-provided skill registry for listing.
+ */
+export interface SkillListToolDeps {
+    /** List all available skills, optionally filtered by category. */
+    listSkills(category?: string): Promise<SkillListOutput>;
+}
+export declare function createSkillListTool(deps: SkillListToolDeps): PortableTool<SkillListToolParams>;

package/dist/types/skills/tools/skill-manage-tool.d.ts

@@ -0,0 +1,73 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SKILL_MANAGE_TOOL_NAME: "skill_manage";
+export type SkillManageAction = "create" | "edit" | "patch" | "delete" | "write_file" | "remove_file";
+export interface SkillManageToolParams {
+    action: SkillManageAction;
+    name: string;
+    content?: string;
+    category?: string;
+    filePath?: string;
+    fileContent?: string;
+    oldString?: string;
+    newString?: string;
+}
+export declare const SKILL_MANAGE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["create", "edit", "patch", "delete", "write_file", "remove_file"];
+            readonly description: string;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Skill name (lowercase, max 64 chars, kebab-case: letters, digits, hyphens).";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly category: {
+            readonly type: "string";
+            readonly description: "Category/domain (e.g. 'devops', 'mlops'). Used by create to organize skills.";
+        };
+        readonly filePath: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly fileContent: {
+            readonly type: "string";
+            readonly description: "Content for write_file action. Max 1 MiB.";
+        };
+        readonly oldString: {
+            readonly type: "string";
+            readonly description: "Text to find for patch action (must match uniquely in SKILL.md).";
+        };
+        readonly newString: {
+            readonly type: "string";
+            readonly description: "Replacement text for patch action (can be empty to delete).";
+        };
+    };
+    readonly required: readonly ["action", "name"];
+};
+export interface SkillManageResult {
+    success: boolean;
+    message: string;
+    path?: string;
+}
+/**
+ * Host-provided skill management backend.
+ */
+export interface SkillManageToolDeps {
+    /**
+     * Execute a skill management action.
+     * The host handles file system operations, validation, and security scanning.
+     */
+    manageSkill(params: SkillManageToolParams): Promise<SkillManageResult>;
+    /**
+     * Validate skill name format.
+     * If not provided, tool uses built-in validation.
+     */
+    validateName?(name: string): string | null;
+}
+export declare function createSkillManageTool(deps: SkillManageToolDeps): PortableTool<SkillManageToolParams>;

package/dist/types/skills/tools/skill-view-tool.d.ts

@@ -0,0 +1,37 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SKILL_VIEW_TOOL_NAME: "skill_view";
+export interface SkillViewToolParams {
+    name: string;
+    filePath?: string;
+}
+export declare const SKILL_VIEW_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Skill name to view (e.g. 'code-review', 'deploy-ecs').";
+        };
+        readonly filePath: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["name"];
+};
+export interface SkillViewOutput {
+    name: string;
+    content: string;
+    referenceFiles?: string[];
+    tags?: string[];
+}
+/**
+ * Host-provided skill viewer.
+ */
+export interface SkillViewToolDeps {
+    /**
+     * Read skill content. Returns the main SKILL.md or a specific file.
+     * Returns null if skill not found.
+     */
+    viewSkill(name: string, filePath?: string): Promise<SkillViewOutput | null>;
+}
+export declare function createSkillViewTool(deps: SkillViewToolDeps): PortableTool<SkillViewToolParams>;

package/dist/types/skills/tools/sleep-tool.d.ts

@@ -0,0 +1,49 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SLEEP_TOOL_NAME: "sleep";
+export interface SleepToolParams {
+    /** Duration to sleep in seconds (1–3600). */
+    duration: number;
+    /** Reason for sleeping — helps the runtime decide whether to interrupt. */
+    reason?: string;
+}
+export declare const SLEEP_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly duration: {
+            readonly type: "number";
+            readonly description: "Duration to sleep in seconds (1–3600). Prefer short sleeps (10–60s) to stay responsive.";
+            readonly minimum: 1;
+            readonly maximum: 3600;
+        };
+        readonly reason: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["duration"];
+};
+/** The result returned after a sleep completes or is interrupted. */
+export interface SleepResult {
+    /** Actual time slept in seconds (may be less if interrupted). */
+    sleptSeconds: number;
+    /** Whether the sleep was interrupted before completing. */
+    interrupted: boolean;
+    /** The event that caused the interruption (undefined if not interrupted). */
+    interruptReason?: string;
+}
+/**
+ * Runtime dependencies injected by the host.
+ *
+ * The sleep mechanism is host-provided — the tool itself does NOT call
+ * setTimeout. The host decides how to implement the wait (timer, event loop
+ * integration, tick prompt scheduling, etc.).
+ */
+export interface SleepToolDeps {
+    /**
+     * Perform the actual sleep. Must resolve after `durationMs` or when
+     * interrupted (whichever is first). The AbortSignal fires if the user
+     * or the system requests an interrupt.
+     */
+    sleep(durationMs: number, signal: AbortSignal): Promise<SleepResult>;
+}
+export declare function createSleepTool(deps: SleepToolDeps): PortableTool<SleepToolParams>;

package/dist/types/skills/tools/structured-output-tool.d.ts

@@ -0,0 +1,116 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const STRUCTURED_OUTPUT_TOOL_NAME: "structured_output";
+/** Maximum content size for structured output results. */
+export declare const STRUCTURED_OUTPUT_MAX_CHARS = 100000;
+export interface StructuredOutputToolParams {
+    /** The structured data to return. Must conform to the session's output schema. */
+    data: Record<string, unknown>;
+}
+/**
+ * Base schema — accepts any object.
+ * When used with createConfiguredStructuredOutputTool, the host overrides
+ * this with the actual JSON Schema from `response_format.json_schema`.
+ */
+export declare const STRUCTURED_OUTPUT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly data: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: true;
+        };
+    };
+    readonly required: readonly ["data"];
+};
+/** Schema validation error detail. */
+export interface SchemaValidationError {
+    path: string;
+    message: string;
+    keyword?: string;
+}
+/** Result of structured output validation. */
+export interface StructuredOutputResult {
+    valid: boolean;
+    errors?: SchemaValidationError[];
+}
+/**
+ * Whether the structured output tool should be enabled for this session.
+ * CC equivalent: `isSyntheticOutputToolEnabled`.
+ */
+export declare function isStructuredOutputEnabled(opts: {
+    isNonInteractiveSession: boolean;
+}): boolean;
+/**
+ * Runtime dependencies injected by the host.
+ *
+ * The host provides:
+ * 1. The JSON Schema to validate against (from session config)
+ * 2. A validator function (host may use Ajv, Zod, or any validator)
+ * 3. An output sink to deliver the validated data
+ *
+ * The tool is only available in non-interactive (SDK/API) sessions
+ * where a `response_format.json_schema` has been specified.
+ */
+export interface StructuredOutputToolDeps {
+    /**
+     * Get the JSON Schema that the output must conform to.
+     * Returns undefined if no schema is configured (tool should not be registered).
+     */
+    getOutputSchema(): Record<string, unknown> | undefined;
+    /**
+     * Validate data against the output schema.
+     * Returns { valid: true } or { valid: false, errors: [...] }.
+     */
+    validateOutput(data: Record<string, unknown>): StructuredOutputResult;
+    /**
+     * Deliver the validated output to the caller.
+     * Called only after successful validation.
+     */
+    deliverOutput(data: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Create the base structured output tool with DI-based validation.
+ * This is the standard factory for runtime integration.
+ */
+export declare function createStructuredOutputTool(deps: StructuredOutputToolDeps): PortableTool<StructuredOutputToolParams>;
+/**
+ * Result of creating a configured structured output tool.
+ * Success: { tool } — ready-to-use tool with compiled schema.
+ * Failure: { error } — schema was invalid.
+ */
+export type ConfiguredToolResult = {
+    tool: PortableTool<StructuredOutputToolParams>;
+} | {
+    error: string;
+};
+/**
+ * Host-provided schema compilation interface.
+ * Allows the host to use any validator (Ajv, Zod, custom).
+ */
+export interface SchemaCompiler {
+    /**
+     * Validate that the schema itself is a valid JSON Schema.
+     * Returns null if valid, or an error message string if invalid.
+     */
+    validateSchema(schema: Record<string, unknown>): string | null;
+    /**
+     * Compile the schema into a reusable validator function.
+     * Returns a function that validates data and returns StructuredOutputResult.
+     */
+    compile(schema: Record<string, unknown>): (data: Record<string, unknown>) => StructuredOutputResult;
+}
+/**
+ * Create a StructuredOutputTool configured with a specific JSON Schema.
+ * Mirrors CC's `createSyntheticOutputTool(jsonSchema)`.
+ *
+ * Features:
+ * - Validates the schema itself at creation time
+ * - Compiles the validator for reuse (cached via WeakMap)
+ * - Overrides the tool's `parameters` with the provided schema (dynamic input)
+ * - Returns { tool } on success or { error } if schema is invalid
+ *
+ * @param jsonSchema  The JSON Schema to validate output against.
+ * @param compiler    Schema compiler/validator provided by the host.
+ * @param deliver     Output delivery function (called after successful validation).
+ */
+export declare function createConfiguredStructuredOutputTool(jsonSchema: Record<string, unknown>, compiler: SchemaCompiler, deliver: (data: Record<string, unknown>) => Promise<void>): ConfiguredToolResult;