qlogicagent 2.1.0 → 2.3.0

package/dist/types/cli/stdio-server.d.ts

@@ -41,6 +41,8 @@ export declare class StdioServer {
     private sessionState;
     private currentMediaApiKeys;
     private taskStore;
+    /** Media auto-download service — persists generated media files locally. */
+    private mediaPersistence;
     /** Session-scoped memory prefetch state (LRU dedup + byte limit). */
     private memoryPrefetchState;
     /** QMemory adapter (when QMEMORY_BASE_URL env is set). Used by Dream hippocampus bridge. */
@@ -49,7 +51,6 @@ export declare class StdioServer {
     /** MEMDIR file-based memory (CC memdir parity). */
     private memdir;
     /** Memory write gate state (P2+P3: category gate + supersedes). */
-    private memoryWriteState;
     private fileWatcher;
     /** Pending ask_user requests waiting for host response */
     private pendingAskUser;
@@ -91,6 +92,11 @@ export declare class StdioServer {
      * Always returns the InitializeResult shape.
      */
     private handleInitialize;
+    /**
+     * Ensure a default project exists on first start.
+     * Called from both legacy handleInitialize and ACP acpHandleInitialize.
+     */
+    private ensureDefaultProject;
     /**
      * `thread.create` — create a new thread (session container).
      * Maps threadId → sessionId for the underlying session system.
@@ -172,6 +178,16 @@ export declare class StdioServer {
      * `config.update` — Update agent runtime configuration (merges into settings.json).
      */
     private handleConfigUpdate;
+    /**
+     * `config.tunables` — Return all tunable default values with their current overrides.
+     */
+    private handleConfigTunables;
+    /**
+     * `config.updateTunable` — Write a single tunable override into settings.json.tunables.
+     * Params: { key: string, value: number | boolean | string }
+     * Only keys that exist in TunableDefaults are accepted (validation).
+     */
+    private handleConfigUpdateTunable;
     /**
      * `todos.list` — Query current todo items and summary.
      * Invokes the registered todo tool's list action.
@@ -299,4 +315,39 @@ export declare class StdioServer {
     private acpHandleProductResume;
     private acpHandleProductStatus;
     private acpHandleTeamDelegate;
+    private handleProjectCreate;
+    private handleProjectList;
+    private handleProjectDelete;
+    private handleProjectRename;
+    private handleProjectArchive;
+    private handleProjectUnarchive;
+    private handleProjectArchiveByGroup;
+    private handleSessionSwitchProject;
+    private handleSessionGetState;
+    private getProjectInstructionsStore;
+    private handleInstructionsList;
+    private handleInstructionsRead;
+    private handleInstructionsWrite;
+    private handleInstructionsDelete;
+    private handleSkillsList;
+    /** Extract version and description from a SKILL.md frontmatter. */
+    private extractSkillMeta;
+    private handleSkillsActivate;
+    private handleSkillsDeactivate;
+    /**
+     * `skills.delete` — Permanently remove a skill from project or global scope.
+     * Params: { name: string, scope?: "project" | "global" }
+     * Default scope: "project"
+     */
+    private handleSkillsDelete;
+    /**
+     * `skills.promote` — Copy a project-level skill to global (user-level).
+     * Params: { name: string, keepLocal?: boolean }
+     * By default removes the project-level copy after promoting.
+     */
+    private handleSkillsPromote;
+    private handleSkillsStats;
+    private getProjectPlanStore;
+    private handlePlansList;
+    private handlePlansGet;
 }

package/dist/types/cli/tool-bootstrap.d.ts

@@ -1,16 +1,24 @@
 import type { PortableTool } from "../skills/portable-tool.js";
+import { type TaskToolHooks } from "../skills/tools/task-tool.js";
 import { type ExecProgress } from "../skills/tools/exec-tool.js";
 import type { AgentLogger } from "../agent/types.js";
 import { type AskUserQuestion } from "../skills/tools/ask-user-tool.js";
 import type { MediaClient } from "../llm/media-client.js";
 import type { MediaCapability } from "../llm/provider-def.js";
 import type { ProviderToolAPI } from "../llm/provider-tool-api.js";
+/** Enable or disable group security mode (blocks sensitive file access). */
+export declare function setGroupSecurityMode(enabled: boolean): void;
 /**
  * Set the provider's tool API for C-level cascade.
  * When set, web_search tool will try provider-native search first,
  * falling back to SearXNG. Called from stdio-server per session.
  */
 export declare function setProviderToolAPI(api: ProviderToolAPI | undefined): void;
+/**
+ * Set task tool lifecycle hooks. Called from stdio-server when session starts.
+ * Connects planning-task events to the HookRegistry.
+ */
+export declare function setTaskToolHooks(hooks: TaskToolHooks | undefined): void;
 /**
  * Set the ask_user callback. The host (Electron / test harness) provides
  * an implementation that presents questions to the user and returns answers.

package/dist/types/contracts/index.d.ts

@@ -4,6 +4,5 @@
  * These types are only consumed within qlogicagent itself (agent runtime + hub).
  * They were removed from the public npm package to slim the cross-repo API surface.
  */
-export * from "./planner.js";
 export * from "./todo.js";
 export * from "./hooks.js";

package/dist/types/contracts/todo.d.ts

@@ -1,23 +1,10 @@
+import type { TaskItem, TaskListSummary } from "../skills/tools/task-tool.js";
+import { summarizeTaskList } from "../skills/tools/task-tool.js";
 export declare const TODO_ITEM_STATUS_VALUES: readonly ["not-started", "in-progress", "completed"];
 export type TodoItemStatus = (typeof TODO_ITEM_STATUS_VALUES)[number];
-export interface TodoItem {
-    id: number;
-    title: string;
-    status: TodoItemStatus;
-    /** Detailed task description (V2). */
-    description?: string;
-    /** Owner agent/subagent identifier for per-agent isolation (V2). */
-    owner?: string;
-    /** IDs of tasks that must complete before this one can start (V2). */
-    blockedBy?: number[];
-    /** IDs of tasks this one blocks from starting (V2). */
-    blocks?: number[];
-}
-export interface TodoListSummary {
-    total: number;
-    completed: number;
-    inProgress: number;
-    notStarted: number;
-    blocked: number;
-}
-export declare function summarizeTodoList(items: readonly TodoItem[]): TodoListSummary;
+/** @deprecated Use TaskItem from task-tool.ts */
+export type TodoItem = TaskItem;
+/** @deprecated Use TaskListSummary from task-tool.ts */
+export type TodoListSummary = TaskListSummary;
+/** @deprecated Use summarizeTaskList from task-tool.ts */
+export declare const summarizeTodoList: typeof summarizeTaskList;

package/dist/types/llm/adapters/aliyun-oss-file-upload-adapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Aliyun OSS File Upload Adapter — direct upload to Alibaba Cloud OSS.
+ *
+ * Uploads files directly to OSS bucket using V1 signature (HMAC-SHA1).
+ * No external dependencies — uses Node.js crypto + fetch.
+ *
+ * This is the **universal fallback adapter** for providers without a native
+ * File Upload API (e.g. Anthropic). Ensures ALL file handling goes through
+ * upload — never base64 inline.
+ *
+ * Environment variables:
+ *   OSS_ACCESS_KEY_ID       — Aliyun AccessKey ID
+ *   OSS_ACCESS_KEY_SECRET   — Aliyun AccessKey Secret
+ *   OSS_BUCKET              — Bucket name (default: "qlogicagent")
+ *   OSS_REGION              — Region (default: "cn-beijing")
+ *   OSS_ENDPOINT            — Custom endpoint (default: derived from region)
+ */
+import type { FileUploadAdapter, FileUploadResult } from "../file-upload-service.js";
+export interface AliyunOSSFileUploadConfig {
+    /** Aliyun AccessKey ID. Required. */
+    accessKeyId: string;
+    /** Aliyun AccessKey Secret. Required. */
+    accessKeySecret: string;
+    /** OSS Bucket name. Default: "qlogicagent". */
+    bucket?: string;
+    /** OSS Region. Default: "cn-beijing". */
+    region?: string;
+    /** Custom OSS endpoint. Default: "{bucket}.oss-{region}.aliyuncs.com". */
+    endpoint?: string;
+    /** Upload path prefix. Default: "media". */
+    pathPrefix?: string;
+    /** Timeout ms. Default: 120_000. */
+    timeoutMs?: number;
+}
+/**
+ * Create an AliyunOSSFileUploadAdapter from environment variables.
+ * Returns undefined if required env vars (OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET) are missing.
+ */
+export declare function createAliyunOSSAdapterFromEnv(): AliyunOSSFileUploadAdapter | undefined;
+export declare class AliyunOSSFileUploadAdapter implements FileUploadAdapter {
+    private readonly config;
+    constructor(config: AliyunOSSFileUploadConfig);
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, _apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+}

package/dist/types/llm/adapters/gemini-file-upload-adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Gemini File Upload Adapter.
+ *
+ * Implements the Google Gemini 2-step resumable upload protocol
+ * into the unified FileUploadAdapter interface.
+ *
+ * Protocol:
+ *   1. POST /upload/v1beta/files — initiate, get upload URL
+ *   2. PUT {uploadUrl} — send bytes, finalize
+ *
+ * Returns a file URI (e.g. "files/abc123") that can be used in
+ * generateContent requests as a file reference.
+ */
+import type { FileUploadAdapter, FileUploadResult } from "../file-upload-service.js";
+export interface GeminiFileUploadConfig {
+    /** Base URL (e.g. "https://generativelanguage.googleapis.com/v1beta") */
+    baseUrl: string;
+    /** Timeout ms. Default: 180_000. */
+    timeoutMs?: number;
+}
+export declare class GeminiFileUploadAdapter implements FileUploadAdapter {
+    private readonly config;
+    constructor(config: GeminiFileUploadConfig);
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+    private waitForProcessing;
+}

package/dist/types/llm/adapters/hub-oss-file-upload-adapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hub OSS File Upload Adapter — for providers without native File API (e.g. Anthropic).
+ *
+ * Uploads local files to the Hub's OSS relay endpoint, which stores them in
+ * cloud object storage (Aliyun OSS / Tencent COS) and returns a public URL.
+ * The LLM provider can then access the file via this public URL.
+ *
+ * This enables Anthropic (which only supports base64 inline or public URL)
+ * to handle large files that exceed the base64 size limit (20MB).
+ *
+ * Endpoint: POST {hubBaseUrl}/api/v1/files/upload
+ * Returns: { url: "https://oss-bucket.oss-cn-xxx.aliyuncs.com/..." }
+ */
+import type { FileUploadAdapter, FileUploadResult } from "../file-upload-service.js";
+export interface HubOSSFileUploadConfig {
+    /** Hub API base URL (e.g. "https://hub.xiaozhiclaw.com" or from env). */
+    hubBaseUrl: string;
+    /** Hub API key for authentication. */
+    hubApiKey?: string;
+    /** Timeout ms. Default: 120_000. */
+    timeoutMs?: number;
+    /** Provider name for result metadata. Default: "hub-oss". */
+    provider?: string;
+}
+export declare class HubOSSFileUploadAdapter implements FileUploadAdapter {
+    private readonly config;
+    constructor(config: HubOSSFileUploadConfig);
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, _apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+}

package/dist/types/llm/adapters/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * File Upload Adapters — barrel export.
+ *
+ * Provider-specific implementations of the FileUploadAdapter interface.
+ */
+export { OpenAIFileUploadAdapter, type OpenAIFileUploadConfig } from "./openai-file-upload-adapter.js";
+export { VolcengineFileUploadAdapter, type VolcengineFileUploadConfig } from "./volcengine-file-upload-adapter.js";
+export { GeminiFileUploadAdapter, type GeminiFileUploadConfig } from "./gemini-file-upload-adapter.js";
+export { HubOSSFileUploadAdapter, type HubOSSFileUploadConfig } from "./hub-oss-file-upload-adapter.js";
+export { AliyunOSSFileUploadAdapter, type AliyunOSSFileUploadConfig, createAliyunOSSAdapterFromEnv } from "./aliyun-oss-file-upload-adapter.js";

package/dist/types/llm/adapters/openai-file-upload-adapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenAI-compatible File Upload Adapter.
+ *
+ * Implements FileUploadAdapter for providers using the standard
+ * POST /v1/files multipart upload endpoint:
+ *   - OpenAI
+ *   - Kimi (Moonshot)
+ *   - Minimax
+ *   - Qwen (via DashScope compatible endpoint)
+ *   - GLM (Zhipu)
+ *   - Any OpenAI-API-compatible provider
+ *
+ * The uploaded file gets a file_id which can be referenced in messages.
+ * Some providers also return a direct download URL.
+ */
+import type { FileUploadAdapter, FileUploadResult } from "../file-upload-service.js";
+export interface OpenAIFileUploadConfig {
+    /** Base URL (e.g. "https://api.openai.com/v1" or "https://api.moonshot.cn/v1") */
+    baseUrl: string;
+    /** Provider name for result metadata. */
+    provider: string;
+    /** Extra headers to include (e.g. for Minimax group_id). */
+    extraHeaders?: Record<string, string>;
+    /** Upload purpose (default: "file-extract" for document understanding). */
+    defaultPurpose?: string;
+    /**
+     * Whether the provider returns a download URL in the upload response.
+     * If false, constructs URL from file_id (provider-specific).
+     */
+    returnsUrl?: boolean;
+    /** Timeout for upload request (ms). Default: 120_000. */
+    timeoutMs?: number;
+}
+export declare class OpenAIFileUploadAdapter implements FileUploadAdapter {
+    private readonly config;
+    constructor(config: OpenAIFileUploadConfig);
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+}

package/dist/types/llm/adapters/volcengine-file-upload-adapter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Volcengine File Upload Adapter.
+ *
+ * Wraps the Volcengine /v3/files endpoint into the unified
+ * FileUploadAdapter interface.
+ *
+ * Volcengine returns a file_id that can be used in API messages
+ * as a file reference. Files uploaded this way can be referenced in
+ * multimodal inputs via the file_id field.
+ */
+import type { FileUploadAdapter, FileUploadResult } from "../file-upload-service.js";
+export interface VolcengineFileUploadConfig {
+    /** Base URL (e.g. "https://ark.cn-beijing.volces.com/api") */
+    baseUrl: string;
+    /** Upload purpose. Default: "user_data". */
+    defaultPurpose?: string;
+    /** Timeout ms. Default: 120_000. */
+    timeoutMs?: number;
+}
+export declare class VolcengineFileUploadAdapter implements FileUploadAdapter {
+    private readonly config;
+    constructor(config: VolcengineFileUploadConfig);
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+}

package/dist/types/llm/file-upload-service.d.ts

@@ -0,0 +1,68 @@
+/**
+ * FileUploadService — Unified file upload abstraction for all LLM providers.
+ *
+ * Replaces the base64 approach in media-resolve.ts. When a local URL is
+ * encountered, this service uploads the file to the current provider's
+ * File API and returns a public URL or file_id.
+ *
+ * Supported providers:
+ *   - OpenAI-compatible (OpenAI, Kimi, Minimax, Qwen, GLM) — POST /v1/files
+ *   - Volcengine — POST /v3/files
+ *   - Google Gemini — Resumable upload protocol
+ *
+ * Architecture:
+ *   Transport layer calls resolveLocalMedia() before sending messages.
+ *   resolveLocalMedia() fetches local content and uploads to provider,
+ *   returning a public URL the LLM can access.
+ */
+export interface FileUploadResult {
+    /** Public URL accessible by the LLM provider. */
+    url: string;
+    /** Provider-specific file identifier (for reference/deletion). */
+    fileId: string;
+    /** Original filename. */
+    filename: string;
+    /** File size in bytes. */
+    bytes: number;
+    /** MIME type of the uploaded file. */
+    mimeType: string;
+    /** Provider that stored the file. */
+    provider: string;
+}
+/**
+ * Provider-specific upload adapter.
+ * Each transport implements this to upload files to its own File API.
+ */
+export interface FileUploadAdapter {
+    /**
+     * Upload a file buffer and return a publicly accessible URL.
+     * @param buffer - File content
+     * @param filename - Original filename (used for MIME detection)
+     * @param mimeType - MIME type of the file
+     * @param apiKey - Provider API key
+     * @param signal - Abort signal
+     */
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+}
+/** Guess MIME type from filename extension. */
+export declare function guessMimeType(filename: string): string;
+/** Check if a URL points to a local/private address that cloud APIs cannot reach. */
+export declare function isLocalUrl(url: string): boolean;
+/**
+ * Resolve a local URL by uploading its content to the provider's File API.
+ * Public URLs are returned as-is (the LLM API can fetch them directly).
+ *
+ * @param url - The URL to resolve (may be local or public)
+ * @param adapter - Provider-specific upload adapter
+ * @param apiKey - API key for the upload
+ * @param signal - Optional abort signal
+ * @returns Public URL accessible by the LLM
+ */
+export declare function resolveLocalMedia(url: string, adapter: FileUploadAdapter, apiKey: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Batch-resolve multiple URLs concurrently. Returns array in same order.
+ * Local URLs are uploaded; public URLs pass through unchanged.
+ * Supports concurrent uploads (up to `concurrency` limit, default 3).
+ * Failures throw (caller should handle).
+ */
+export declare function resolveLocalMediaBatch(urls: string[], adapter: FileUploadAdapter, apiKey: string, signal?: AbortSignal, concurrency?: number): Promise<string[]>;

package/dist/types/llm/transports/anthropic-messages.d.ts

@@ -13,6 +13,7 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface AnthropicTransportConfig {
     baseUrl: string;
     /** anthropic-version header (default "2023-06-01") */
@@ -29,6 +30,8 @@ export interface AnthropicTransportConfig {
     omitZeroTemperature?: boolean;
     /** Provider-specific quirks for conditional logic (CC/altcode parity) */
     quirks?: ProviderQuirks;
+    /** File upload adapter (Hub OSS relay for Anthropic). */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class AnthropicMessagesTransport implements LLMTransport {
     private baseUrl;
@@ -39,6 +42,7 @@ export declare class AnthropicMessagesTransport implements LLMTransport {
     private maxRetries;
     private omitZeroTemperature;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: AnthropicTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     /**

package/dist/types/llm/transports/gemini-generatecontent.d.ts

@@ -21,6 +21,7 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface GeminiGenerateContentTransportConfig {
     /** Base URL, e.g. "https://generativelanguage.googleapis.com/v1beta" */
     baseUrl: string;
@@ -28,11 +29,14 @@ export interface GeminiGenerateContentTransportConfig {
     timeoutMs?: number;
     /** Provider-specific quirks */
     quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class GeminiGenerateContentTransport implements LLMTransport {
     private baseUrl;
     private timeoutMs;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: GeminiGenerateContentTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     private buildRequestBody;

package/dist/types/llm/transports/media-resolve.d.ts

@@ -1,25 +1,50 @@
 /**
- * Media URL Resolution — converts local/private URLs to inline base64 data URLs.
+ * Media URL Resolution — resolves local/private URLs for cloud LLM APIs.
  *
- * Cloud LLM APIs (OpenAI, Anthropic, DeepSeek) cannot fetch content from
- * localhost or private networks. This utility detects such URLs and resolves
- * them to base64 data URLs that can be sent inline.
+ * Cloud LLM APIs (OpenAI, Anthropic, DeepSeek, etc.) cannot fetch content
+ * from localhost or private networks.
+ *
+ * **Primary approach (upload-based):**
+ *   Local URLs are fetched → uploaded to provider's File API or Aliyun OSS → public URL returned.
+ *   This is the ONLY approach for images, video, and documents.
+ *
+ * **Audio exception (base64):**
+ *   OpenAI's input_audio.data API field mandates base64 encoding.
+ *   resolveMediaUrl() is retained ONLY for this case.
  *
  * URL-first design: the gateway stores media as HTTP URLs; this layer handles
  * the last-mile transformation before sending to provider APIs.
  */
+import type { FileUploadAdapter } from "../file-upload-service.js";
 /** Check if a URL points to a local/private address that cloud APIs cannot reach. */
 export declare function isLocalUrl(url: string): boolean;
+export interface MediaResolveContext {
+    /** Provider-specific upload adapter. */
+    uploadAdapter: FileUploadAdapter;
+    /** API key for the upload. */
+    apiKey: string;
+    /** Abort signal. */
+    signal?: AbortSignal;
+}
 /**
- * Resolve a URL to a base64 data URL if it's a local address.
- * Public URLs are returned as-is (the LLM API can fetch them directly).
+ * Resolve a local URL by uploading to the provider's File API.
+ * This is the **preferred** method for all media types.
  *
- * Returns the original URL for non-local addresses.
- * Returns a `data:<mime>;base64,...` string for local addresses.
+ * Public URLs pass through unchanged.
+ * Local URLs are uploaded → public URL or file_id returned.
  */
-export declare function resolveMediaUrl(url: string, fallbackMime?: string): Promise<string>;
+export declare function resolveMediaUrlViaUpload(url: string, ctx: MediaResolveContext): Promise<string>;
+/**
+ * Batch-resolve URLs via upload. Best-effort: failures return original URL.
+ */
+export declare function resolveMediaUrlsViaUpload(urls: string[], ctx: MediaResolveContext): Promise<string[]>;
 /**
- * Batch-resolve multiple URLs. Returns array in same order.
- * Failures are logged and the original URL is kept (best-effort).
+ * Resolve local audio URL to base64 data URL.
+ *
+ * ONLY for audio — OpenAI's input_audio.data API field mandates base64 encoding.
+ * There is no upload alternative for audio in the OpenAI API.
+ *
+ * For images/video/documents: ALWAYS use resolveMediaUrlViaUpload() instead.
+ * base64 is forbidden for non-audio media per project architecture rules.
  */
-export declare function resolveMediaUrls(urls: string[], fallbackMime?: string): Promise<string[]>;
+export declare function resolveMediaUrl(url: string, fallbackMime?: string): Promise<string>;

package/dist/types/llm/transports/openai-chat.d.ts

@@ -13,6 +13,7 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport, FIMRequest, FIMChunk } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface OpenAIChatTransportConfig {
     baseUrl: string;
     /** Additional headers (e.g. for specific providers) */
@@ -25,6 +26,8 @@ export interface OpenAIChatTransportConfig {
     omitZeroTemperature?: boolean;
     /** Provider-specific quirks (CC/altcode parity) */
     quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class OpenAIChatTransport implements LLMTransport {
     private baseUrl;
@@ -33,6 +36,7 @@ export declare class OpenAIChatTransport implements LLMTransport {
     private supportsStreamOptions;
     private omitZeroTemperature;
     private quirks;
+    private fileUploadAdapter?;
     private cumulativeReasoningLen;
     private cumulativeContentLen;
     constructor(config: OpenAIChatTransportConfig);

package/dist/types/llm/transports/openai-responses.d.ts

@@ -25,17 +25,20 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface OpenAIResponsesTransportConfig {
     baseUrl: string;
     extraHeaders?: Record<string, string>;
     timeoutMs?: number;
     quirks?: ProviderQuirks;
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class OpenAIResponsesTransport implements LLMTransport {
     private baseUrl;
     private extraHeaders;
     private timeoutMs;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: OpenAIResponsesTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     private buildRequestBody;

package/dist/types/llm/transports/volcengine-responses.d.ts

@@ -18,17 +18,21 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface VolcengineResponsesTransportConfig {
     baseUrl: string;
     extraHeaders?: Record<string, string>;
     timeoutMs?: number;
     quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class VolcengineResponsesTransport implements LLMTransport {
     private baseUrl;
     private extraHeaders;
     private timeoutMs;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: VolcengineResponsesTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     /**

package/dist/types/orchestration/skill-improvement.d.ts

@@ -1,7 +1,14 @@
 /**
  * Skill self-learning: decides whether a completed turn should
  * trigger skill creation or improvement instructions.
+ *
+ * Guards against proliferation:
+ * - MAX_SKILLS_PER_PROJECT: hard cap on project-level skills
+ * - Dedup check: compares tool-set signature against existing skills
+ * - Cooldown: prevents rapid-fire creation within a session
  */
+import { MAX_SKILLS_PER_PROJECT, MAX_SKILLS_GLOBAL } from "../agent/tunable-defaults.js";
+export { MAX_SKILLS_PER_PROJECT, MAX_SKILLS_GLOBAL };
 export interface SkillTurnResult {
     ok: boolean;
     /** Number of tool invocations in this turn */
@@ -36,6 +43,32 @@ export interface SkillImproveInstruction {
     reason: string;
 }
 export type SkillInstruction = SkillCreateInstruction | SkillImproveInstruction;
+/**
+ * Reset cooldown state (for testing).
+ */
+export declare function resetSkillCreationCooldown(): void;
+/**
+ * Check if an existing skill in skillsDir already covers the same tool set.
+ * Returns the name of the conflicting skill, or null if none found.
+ */
+export declare function findDuplicateSkill(tools: string[], skillsDir: string): string | null;
+/**
+ * Count active skills in a directory.
+ */
+export declare function countSkillsInDir(skillsDir: string): number;
+/**
+ * Context for proliferation checks.
+ */
+export interface SkillCreationContext {
+    /** Project-level skills directory */
+    projectSkillsDir?: string;
+    /** User-level (global) skills directory */
+    globalSkillsDir?: string;
+    /** Tool names used in this turn */
+    tools: string[];
+    /** Optional suggested name */
+    suggestedName?: string;
+}
 /**
  * Determine whether a completed turn should produce a skill instruction.
  *
@@ -44,16 +77,14 @@ export type SkillInstruction = SkillCreateInstruction | SkillImproveInstruction;
  * - It involved multi-step orchestration
  * - It used ≥3 tool calls across ≥2 distinct tools
  * - No existing skill was already applied
- *
- * An improvement is suggested when:
- * - The turn used an existing skill but got negative feedback
+ * - Cooldown has elapsed since last skill creation
+ * - No duplicate skill exists (same tool signature)
+ * - Project skill count < MAX_SKILLS_PER_PROJECT
  */
-export declare function shouldCreateSkill(result: SkillTurnResult): boolean;
+export declare function shouldCreateSkill(result: SkillTurnResult, context?: SkillCreationContext): boolean;
 export declare function shouldImproveSkill(result: SkillTurnResult): boolean;
 /**
  * Build a skill instruction from a turn result, or null if none is warranted.
+ * Updates cooldown timestamp on success.
  */
-export declare function buildSkillInstruction(result: SkillTurnResult, context: {
-    tools: string[];
-    suggestedName?: string;
-}): SkillInstruction | null;
+export declare function buildSkillInstruction(result: SkillTurnResult, context: SkillCreationContext): SkillInstruction | null;