qlogicagent 2.13.4 → 2.13.5

package/dist/skills/tools/structured-output-tool.js

@@ -0,0 +1,176 @@
+// ============================================================
+// Structured Output Tool — validated JSON schema output for
+// non-interactive (SDK/API) sessions.
+// Reference: claude-code-haha/src/tools/SyntheticOutputTool/SyntheticOutputTool.ts
+// Category: output / structured
+// ============================================================
+export const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
+/** Maximum content size for structured output results. */
+export const STRUCTURED_OUTPUT_MAX_CHARS = 100_000;
+/**
+ * Base schema — accepts any object.
+ * When used with createConfiguredStructuredOutputTool, the host overrides
+ * this with the actual JSON Schema from `response_format.json_schema`.
+ */
+export const STRUCTURED_OUTPUT_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        data: {
+            type: "object",
+            description: "The structured JSON data to return as this turn's output. " +
+                "Must conform to the output schema specified for this session.",
+            additionalProperties: true,
+        },
+    },
+    required: ["data"],
+};
+/**
+ * Whether the structured output tool should be enabled for this session.
+ * CC equivalent: `isSyntheticOutputToolEnabled`.
+ */
+export function isStructuredOutputEnabled(opts) {
+    return opts.isNonInteractiveSession;
+}
+/**
+ * Create the base structured output tool with DI-based validation.
+ * This is the standard factory for runtime integration.
+ */
+export function createStructuredOutputTool(deps) {
+    return {
+        name: STRUCTURED_OUTPUT_TOOL_NAME,
+        label: "Structured Output",
+        shouldDefer: false,
+        isConcurrencySafe: true,
+        isReadOnly: true,
+        searchHint: "return the final response as structured JSON",
+        maxResultSizeChars: STRUCTURED_OUTPUT_MAX_CHARS,
+        description: [
+            "Return your final response as structured JSON data.",
+            "",
+            "Use this tool ONLY when the session requests structured output (via response_format).",
+            "You MUST call this tool exactly once at the end of your response to provide the structured output.",
+            "The data you provide must conform to the output JSON Schema specified for this session.",
+            "",
+            "Rules:",
+            "• Call this exactly once at the end of your turn to deliver results",
+            "• The data must be a valid JSON object matching the required schema",
+            "• If validation fails, you'll see the errors — fix your data and try again",
+            "• This is typically the last tool call in a turn",
+        ].join("\n"),
+        parameters: STRUCTURED_OUTPUT_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const schema = deps.getOutputSchema();
+            if (!schema) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: No output schema configured for this session. " +
+                                "structured_output is only available when response_format.json_schema is specified.",
+                        }],
+                    details: { valid: false, error: "no_schema" },
+                };
+            }
+            const validation = deps.validateOutput(params.data);
+            if (!validation.valid) {
+                const errorLines = (validation.errors ?? []).map((e) => `  • ${e.path || "/"}: ${e.message}`);
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                "Output does not match required schema:",
+                                ...errorLines,
+                            ].join("\n"),
+                        }],
+                    details: { valid: false, errors: validation.errors },
+                };
+            }
+            // Validation passed — deliver the output
+            await deps.deliverOutput(params.data);
+            return {
+                content: [{ type: "text", text: "Structured output provided successfully." }],
+                details: { valid: true, structured_output: params.data },
+            };
+        },
+    };
+}
+/** WeakMap cache for compiled schema tools (mirrors CC's toolCache). */
+const configuredToolCache = new WeakMap();
+/**
+ * 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 function createConfiguredStructuredOutputTool(jsonSchema, compiler, deliver) {
+    const cached = configuredToolCache.get(jsonSchema);
+    if (cached)
+        return cached;
+    const result = buildConfiguredTool(jsonSchema, compiler, deliver);
+    configuredToolCache.set(jsonSchema, result);
+    return result;
+}
+function buildConfiguredTool(jsonSchema, compiler, deliver) {
+    try {
+        // Step 1: Validate the schema itself
+        const schemaError = compiler.validateSchema(jsonSchema);
+        if (schemaError) {
+            return { error: `Invalid JSON Schema: ${schemaError}` };
+        }
+        // Step 2: Compile the validator
+        const validate = compiler.compile(jsonSchema);
+        // Step 3: Build the tool with dynamic input schema
+        const tool = {
+            name: STRUCTURED_OUTPUT_TOOL_NAME,
+            label: "Structured Output",
+            shouldDefer: false,
+            isConcurrencySafe: true,
+            isReadOnly: true,
+            searchHint: "return the final response as structured JSON",
+            maxResultSizeChars: STRUCTURED_OUTPUT_MAX_CHARS,
+            description: [
+                "Use this tool to return your final response in the requested structured format.",
+                "You MUST call this tool exactly once at the end of your response to provide the structured output.",
+            ].join(" "),
+            // Dynamic: override with the actual JSON Schema so LLM gets type guidance
+            parameters: {
+                type: "object",
+                properties: {
+                    data: jsonSchema,
+                },
+                required: ["data"],
+            },
+            execute: async (_toolCallId, params) => {
+                const validation = validate(params.data);
+                if (!validation.valid) {
+                    const errors = (validation.errors ?? [])
+                        .map((e) => `${e.path || "root"}: ${e.message}`)
+                        .join(", ");
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Output does not match required schema: ${errors}`,
+                            }],
+                        details: { valid: false, errors: validation.errors },
+                    };
+                }
+                await deliver(params.data);
+                return {
+                    content: [{ type: "text", text: "Structured output provided successfully." }],
+                    details: { valid: true, structured_output: params.data },
+                };
+            },
+        };
+        return { tool };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/skills/tools/stt-tool.d.ts

@@ -0,0 +1,33 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const STT_TOOL_NAME: "stt";
+export interface SttToolParams {
+    audio_url: string;
+    language?: string;
+}
+export declare const STT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly audio_url: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly language: {
+            readonly type: "string";
+            readonly description: "Language hint for transcription: 'zh' (Chinese), 'en' (English), or auto-detect if omitted.";
+        };
+    };
+    readonly required: readonly ["audio_url"];
+};
+export interface SttResult {
+    transcription: string;
+    model?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for STT. */
+export interface SttToolDeps {
+    speechToText(params: {
+        audioUrl: string;
+        language?: string;
+    }): Promise<SttResult>;
+}
+export declare function createSttTool(deps: SttToolDeps): PortableTool<SttToolParams>;

package/dist/skills/tools/stt-tool.js

@@ -0,0 +1,58 @@
+// ============================================================
+// STT Tool — speech-to-text (audio transcription) via backend.
+// Category: media
+// ============================================================
+export const STT_TOOL_NAME = "stt";
+export const STT_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        audio_url: {
+            type: "string",
+            description: "URL of the audio file to transcribe. Supports mp3, wav, m4a, ogg, flac formats. " +
+                "MUST be a publicly accessible HTTP/HTTPS URL. " +
+                "Use file_upload tool first if the user provides a local file.",
+        },
+        language: {
+            type: "string",
+            description: "Language hint for transcription: 'zh' (Chinese), 'en' (English), or auto-detect if omitted.",
+        },
+    },
+    required: ["audio_url"],
+};
+export function createSttTool(deps) {
+    return {
+        name: STT_TOOL_NAME,
+        label: "STT",
+        searchHint: "stt speech-to-text transcribe transcription audio 转写 语音转文字 听写 录音转文字",
+        description: "Transcribe audio to text (Speech-to-Text). " +
+            "Provide an audio file URL and receive the spoken content as text. " +
+            "Supports Chinese and English. Use for meeting transcription, voice message reading, " +
+            "subtitle generation, or any audio-to-text conversion.",
+        parameters: STT_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            if (!params.audio_url) {
+                return {
+                    content: [{ type: "text", text: "Error: audio_url parameter is required. Provide a publicly accessible HTTP/HTTPS URL to an audio file." }],
+                    details: { error: "audio_url parameter is required" },
+                };
+            }
+            const result = await deps.speechToText({
+                audioUrl: params.audio_url,
+                language: params.language,
+            });
+            const preview = result.transcription.length > 200
+                ? result.transcription.slice(0, 200) + "…"
+                : result.transcription;
+            return {
+                content: [{ type: "text", text: result.transcription }],
+                details: {
+                    type: "stt",
+                    model: result.model,
+                    durationMs: result.durationMs,
+                    transcriptionLength: result.transcription.length,
+                    preview,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/task-tool.d.ts

@@ -0,0 +1,125 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const TASK_TOOL_NAME: "task";
+export declare const TASK_ACTIONS: readonly ["create", "update", "delete", "list", "get", "output", "cancel"];
+export type TaskAction = (typeof TASK_ACTIONS)[number];
+/**
+ * Structural view of the host's background task registry
+ * (implemented by BackgroundTaskManager; kept structural so this file stays zero-dep).
+ */
+export interface TaskRuntimeAccess {
+    getTask(taskId: string): RuntimeTaskView | undefined;
+    listTasks(): RuntimeTaskView[];
+    readOutput(taskId: string): Promise<{
+        task: RuntimeTaskView;
+        output: string;
+        running: boolean;
+    } | null>;
+    cancelTask(taskId: string): boolean;
+}
+export interface RuntimeTaskView {
+    taskId: string;
+    type: string;
+    label: string;
+    lifecycle: string;
+    startedAt: number;
+    endedAt?: number;
+    error?: string;
+}
+export interface TaskToolRuntimeDeps {
+    /** Live accessor — the registry is bound by the host after bootstrap. */
+    getRuntime(): TaskRuntimeAccess | null;
+}
+export type TaskStatus = "not-started" | "in-progress" | "completed";
+export declare const TASK_STATUS_VALUES: readonly TaskStatus[];
+export interface TaskItem {
+    id: number;
+    title: string;
+    status: TaskStatus;
+    description?: string;
+    owner?: string;
+    blockedBy?: number[];
+    blocks?: number[];
+}
+export interface TaskListSummary {
+    total: number;
+    completed: number;
+    inProgress: number;
+    notStarted: number;
+    blocked: number;
+}
+export interface TaskToolParams {
+    action: TaskAction;
+    id?: number;
+    taskId?: string;
+    title?: string;
+    description?: string;
+    status?: TaskStatus;
+    owner?: string;
+    addBlocks?: number[];
+    addBlockedBy?: number[];
+}
+export declare const TASK_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["create", "update", "delete", "list", "get", "output", "cancel"];
+            readonly description: string;
+        };
+        readonly id: {
+            readonly type: "number";
+            readonly description: "[update|delete|get] Checklist task id to operate on.";
+        };
+        readonly taskId: {
+            readonly type: "string";
+            readonly description: "[output|cancel] Background task id (returned by agent background=true / exec background=true).";
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly description: "[create|update] Task title (3-7 words, imperative form).";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "[create|update] Detailed task description.";
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["not-started", "in-progress", "completed"];
+            readonly description: "[create|update] Task status. create defaults to not-started.";
+        };
+        readonly owner: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly addBlocks: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly description: "[update] Task IDs that this task should block (they depend on this task).";
+        };
+        readonly addBlockedBy: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly description: "[update] Task IDs that should block this task (this task depends on them).";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface TaskToolOptions {
+    /** Unique agent/session identifier for per-agent task isolation. */
+    agentId?: string;
+    /** Enable verification nudge (default: true). */
+    verificationNudge?: boolean;
+}
+export interface TaskToolHooks {
+    onTaskCreated?: (task: TaskItem) => void;
+    onTaskCompleted?: (task: TaskItem) => void;
+}
+export declare function summarizeTaskList(items: readonly TaskItem[]): TaskListSummary;
+/**
+ * Create a stateful task tool instance (V2 — CC TaskCreate/Update/List/Get aligned).
+ */
+export declare function createTaskTool(options?: TaskToolOptions, hooks?: TaskToolHooks, runtimeDeps?: TaskToolRuntimeDeps): PortableTool<TaskToolParams>;