@kodax-ai/kodax 0.7.58 → 0.7.60

package/dist/types-chunks/{sdk-session-21Tt3N_x.d.ts → sdk-session-CtwN7iBO.d.ts}

@@ -1,7 +1,7 @@
-import { b as PermissionMode, F as FileSessionStorage, S as SessionData } from './storage.d-BsZrBPYu.js';
-import { E as KodaXReasoningMode, j as KodaXMessage, c as KodaXContentBlock } from './types.d-Ci5YPFEh.js';
-import { m as KodaXAgentMode } from './bash-prefix-extractor.d-D3cddmyV.js';
-import { ai as KodaXSessionUiHistoryItem, am as KodaXSessionUiToolCall } from './process.d-DHow2y2G.js';
+import { b as PermissionMode, F as FileSessionStorage, S as SessionData } from './storage.d-DlZS0g8w.js';
+import { E as KodaXReasoningMode, j as KodaXMessage, c as KodaXContentBlock, R as KodaXTaskResultMetadata } from './types.d-Bp4Lm1jv.js';
+import { m as KodaXAgentMode } from './bash-prefix-extractor.d-Ds1THKeH.js';
+import { aj as KodaXSessionUiHistoryItem, an as KodaXSessionUiToolCall, a0 as KodaXJsonValue } from './process.d-C93UMgPK.js';
 
 /**
  * TextBuffer - Text buffer management class - 文本缓冲区管理类
@@ -738,6 +738,13 @@ type RestoredHistorySeed = {
 } | {
     type: "thinking";
     text: string;
+} | {
+    type: "sidecar";
+    text: string;
+    verdict?: "revise" | "blocked";
+} | {
+    type: "task_completed";
+    text: string;
 } | {
     type: "tool_summary";
     text: string;
@@ -745,7 +752,7 @@ type RestoredHistorySeed = {
     type: "tool_group";
     tools: KodaXSessionUiToolCall[];
 };
-/** Convert a RestoredHistorySeed to a CreatableHistoryItem. tool_summary → event with icon. */
+/** Convert a RestoredHistorySeed to a CreatableHistoryItem. tool_summary / task_completed → event with icon. */
 declare function seedToHistoryItem(seed: RestoredHistorySeed): CreatableHistoryItem;
 declare function toolCallSeedToHistoryToolCall(tool: KodaXSessionUiToolCall): ToolCall;
 /**
@@ -755,6 +762,15 @@ interface HistorySeedSourceMessage {
     role: KodaXMessage["role"];
     content: string | KodaXContentBlock[];
     _synthetic?: boolean;
+    /**
+     * Provenance marker persisted on host-injected messages. `'sidecar-verifier'`
+     * tags the synthetic user message the Sidecar Verifier injects on a `revise`
+     * verdict; `'task-completed'` tags the synthetic user message carrying a
+     * dispatch_child_task / run_workflow `<task-completed>` result banner. Both are
+     * rendered under their own identity on restore instead of being swallowed by
+     * the generic `_synthetic` skip.
+     */
+    _source?: string;
 }
 declare function extractHistorySeedsFromMessage(message: HistorySeedSourceMessage): RestoredHistorySeed[];
 declare function extractHistorySeedsFromMessages(messages: readonly HistorySeedSourceMessage[]): RestoredHistorySeed[];
@@ -849,21 +865,44 @@ interface SessionSummary {
      * surfaced when `includeArchived` is set). */
     readonly archived?: boolean;
 }
-type SessionTranscriptEntryType = 'message' | 'compaction' | 'branch_summary';
+type SessionTranscriptEntryType = 'message' | 'compaction' | 'branch_summary' | 'client_notice'
+/**
+ * Synthetic task/workflow completion entry derived from `_taskResult`,
+ * `_taskResults`, or legacy `<task-completed>` banners. The original
+ * `KodaXMessage` is still exposed on `message`, but consumers that want a
+ * complete transcript should not filter only `type === 'message'`.
+ */
+ | 'task_result';
+type SessionTranscriptEntrySource = 'user' | 'assistant' | 'workflow' | 'child_task' | 'system' | 'client';
 interface SessionTranscriptEntry {
     readonly entryId: string;
     readonly parentId: string | null;
+    /** Stable logical identity shared by cloned/forked copies of the same entry. */
+    readonly logicalId: string;
+    /** Root source physical entry id when this transcript entry was cloned/forked. */
+    readonly sourceEntryId?: string;
     readonly timestamp: string;
     readonly type: SessionTranscriptEntryType;
+    readonly source?: SessionTranscriptEntrySource;
+    readonly turnId?: string;
     readonly message: KodaXMessage;
     readonly active: boolean;
     readonly summary?: string;
+    readonly payload?: unknown;
+    readonly taskResults?: readonly KodaXTaskResultMetadata[];
 }
 interface FullTranscriptSessionData extends Omit<SessionData, 'messages'> {
     readonly messages: KodaXMessage[];
     readonly activeMessages: KodaXMessage[];
     readonly transcriptEntries: SessionTranscriptEntry[];
 }
+interface AppendClientNoticeOptions {
+    readonly source?: string;
+    readonly content: string;
+    readonly timestamp?: string;
+    readonly turnId?: string;
+    readonly payload?: KodaXJsonValue;
+}
 interface ListSessionsOptions {
     /**
      * Alias for gitRoot; backwards-compat with KodaX Space terminology.
@@ -901,6 +940,7 @@ interface SessionManager {
     listSessions: typeof listSessions;
     loadSession: typeof loadSession;
     loadFullTranscript: typeof loadFullTranscript;
+    appendClientNotice: typeof appendClientNotice;
     forkSession: typeof forkSession;
     rewindSession: typeof rewindSession;
     setActiveEntry: typeof setActiveEntry;
@@ -941,6 +981,14 @@ declare function loadSession(id: string): Promise<SessionData | null>;
  * append order and keeps the active branch in `activeMessages`.
  */
 declare function loadFullTranscript(id: string): Promise<FullTranscriptSessionData | null>;
+/**
+ * Append a host-owned transcript notice that never enters model context.
+ *
+ * Use this for local slash-command output such as `/doctor`, `/mcp status`,
+ * or host-side status panes. It is visible through `loadFullTranscript()` but
+ * `loadSession()` keeps returning only the active model messages.
+ */
+declare function appendClientNotice(id: string, options: AppendClientNoticeOptions): Promise<SessionTranscriptEntry | null>;
 /**
  * Fork a session at an optional selector.
  * Returns null for a missing session. NEVER throws.
@@ -1038,5 +1086,5 @@ declare function createSessionManager(opts?: {
     sessionsDir?: string;
 }): SessionManager;
 
-export { DEFAULT_UI_STATE as D, StreamingState as O, TOOL_STATUS_ICONS as T, TextBuffer as U, ToolCallStatus as _, archiveSession as a5, createSessionManager as a6, deleteSession as a7, extractHistorySeedsFromMessage as a8, extractHistorySeedsFromMessages as a9, extractTextContent as aa, extractTitle as ab, forkSession as ac, formatMessagePreview as ad, listRunningSessions as ae, listSessions as af, loadFullTranscript as ag, loadSession as ah, restoreHistoryItemsFromSession as ai, rewindSession as aj, seedToHistoryItem as ak, setActiveEntry as al, toolCallSeedToHistoryToolCall as am, trimPersistedUiHistorySnapshot as an, unarchiveSession as ao, watchSessions as ap, KeypressHandlerPriority as v };
-export type { UIActions as $, AppProps as A, RunningSessionInfo as B, Completer as C, SessionSummary as E, FullTranscriptSessionData as F, SessionTranscriptEntry as G, HistoryEntry as H, InputPromptProps as I, SessionTranscriptEntryType as J, KeyInfo as K, LegacyMessageListProps as L, Message as M, StatusBarProps as N, PastedContent as P, Suggestion as Q, RestoreHistoryItemsFromSessionInput as R, SessionManager as S, TextBufferOptions as V, Theme as W, ThemeColors as X, ThemeSymbols as Y, ToolCall as Z, AppState as a, UIState as a0, UseTextBufferReturn as a1, VisualCursor as a2, VisualLayout as a3, WatchSessionsCallback as a4, Completion as b, CreatableHistoryItem as c, CursorPosition as d, DeleteSessionResult as e, HistoryItem as f, HistoryItemAssistant as g, HistoryItemBase as h, HistoryItemError as i, HistoryItemEvent as j, HistoryItemHint as k, HistoryItemInfo as l, HistoryItemSidecar as m, HistoryItemSystem as n, HistoryItemThinking as o, HistoryItemToolGroup as p, HistoryItemType as q, HistoryItemUser as r, HistorySeedSourceMessage as s, KeypressEvent as t, KeypressHandler as u, ListSessionsOptions as w, PromptEditingMode as x, PromptSubmitPayload as y, RestoredHistorySeed as z };
+export { ToolCallStatus as $, DEFAULT_UI_STATE as D, StreamingState as Q, TOOL_STATUS_ICONS as U, TextBuffer as V, appendClientNotice as a6, archiveSession as a7, createSessionManager as a8, deleteSession as a9, extractHistorySeedsFromMessage as aa, extractHistorySeedsFromMessages as ab, extractTextContent as ac, extractTitle as ad, forkSession as ae, formatMessagePreview as af, listRunningSessions as ag, listSessions as ah, loadFullTranscript as ai, loadSession as aj, restoreHistoryItemsFromSession as ak, rewindSession as al, seedToHistoryItem as am, setActiveEntry as an, toolCallSeedToHistoryToolCall as ao, trimPersistedUiHistorySnapshot as ap, unarchiveSession as aq, watchSessions as ar, KeypressHandlerPriority as w };
+export type { AppProps as A, RestoredHistorySeed as B, Completer as C, RunningSessionInfo as E, FullTranscriptSessionData as F, SessionSummary as G, HistoryEntry as H, InputPromptProps as I, SessionTranscriptEntry as J, KeyInfo as K, LegacyMessageListProps as L, Message as M, SessionTranscriptEntryType as N, StatusBarProps as O, PastedContent as P, RestoreHistoryItemsFromSessionInput as R, SessionManager as S, Suggestion as T, TextBufferOptions as W, Theme as X, ThemeColors as Y, ThemeSymbols as Z, ToolCall as _, AppState as a, UIActions as a0, UIState as a1, UseTextBufferReturn as a2, VisualCursor as a3, VisualLayout as a4, WatchSessionsCallback as a5, AppendClientNoticeOptions as b, Completion as c, CreatableHistoryItem as d, CursorPosition as e, DeleteSessionResult as f, HistoryItem as g, HistoryItemAssistant as h, HistoryItemBase as i, HistoryItemError as j, HistoryItemEvent as k, HistoryItemHint as l, HistoryItemInfo as m, HistoryItemSidecar as n, HistoryItemSystem as o, HistoryItemThinking as p, HistoryItemToolGroup as q, HistoryItemType as r, HistoryItemUser as s, HistorySeedSourceMessage as t, KeypressEvent as u, KeypressHandler as v, ListSessionsOptions as x, PromptEditingMode as y, PromptSubmitPayload as z };

package/dist/types-chunks/{storage.d-BsZrBPYu.d.ts → storage.d-DlZS0g8w.d.ts}

@@ -1,5 +1,5 @@
-import { a as BashPrefixExtractor } from './bash-prefix-extractor.d-D3cddmyV.js';
-import { a5 as KodaXSessionData, aa as KodaXSessionLineage, ad as KodaXSessionNavigationOptions, ae as KodaXSessionRuntimeInfo, ag as KodaXSessionStorage } from './process.d-DHow2y2G.js';
+import { a as BashPrefixExtractor } from './bash-prefix-extractor.d-Ds1THKeH.js';
+import { a6 as KodaXSessionData, ab as KodaXSessionLineage, ae as KodaXSessionNavigationOptions, af as KodaXSessionRuntimeInfo, ah as KodaXSessionStorage } from './process.d-C93UMgPK.js';
 
 /**
  * Permission Types

package/dist/types-chunks/{types.d-Ci5YPFEh.d.ts → types.d-Bp4Lm1jv.d.ts}

@@ -113,6 +113,17 @@ interface KodaXCacheBoundary {
     hint?: 'system' | 'tools' | 'role-prompt';
 }
 type KodaXContentBlock = KodaXTextBlock | KodaXToolUseBlock | KodaXToolResultBlock | KodaXImageBlock | KodaXThinkingBlock | KodaXRedactedThinkingBlock | KodaXCacheBoundary;
+type KodaXTaskResultSource = 'workflow' | 'child_task';
+interface KodaXTaskResultMetadata {
+    type: 'task_result';
+    source: KodaXTaskResultSource;
+    taskId: string;
+    runId?: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    title?: string;
+    summary?: string;
+    artifactRefs?: string[];
+}
 interface KodaXMessage {
     role: 'user' | 'assistant' | 'system';
     content: string | KodaXContentBlock[];
@@ -122,10 +133,33 @@ interface KodaXMessage {
      * Identifies which subsystem injected a synthetic message so consumers can
      * render/attribute it distinctly instead of treating it like a user query.
      * Absent on genuine user/assistant/system messages. Known values include
-     * `'sidecar-verifier'` (Sidecar Verifier revise feedback). Exposed verbatim
-     * through `KodaXResult.messages` and session-load APIs for SDK consumers.
+     * `'sidecar-verifier'` (Sidecar Verifier revise feedback) and `'task-completed'`
+     * (a dispatch_child_task / run_workflow `<task-completed>` result banner spliced
+     * into the transcript; a rare same-wake mix with a system-reminder shares this
+     * one label, content preserved). Exposed verbatim through `KodaXResult.messages`
+     * and session-load APIs for SDK consumers.
      */
     _source?: string;
+    /** Structured task/workflow result metadata for synthetic task-completed messages. */
+    _taskResult?: KodaXTaskResultMetadata;
+    /** Multiple task results when one synthetic wake message contains several banners. */
+    _taskResults?: KodaXTaskResultMetadata[];
+    /**
+     * Stable SDK turn id that owns this transcript message. Optional for older
+     * sessions and provider-internal synthetic messages.
+     */
+    turnId?: string;
+    /**
+     * ISO-8601 timestamp of when this message was finalized (assistant: when the
+     * LLM stream completed; user: when submitted/injected). Optional and
+     * best-effort: messages persisted before this field existed, or produced by a
+     * path not yet updated to stamp it, will not carry it. `createSessionLineage`
+     * prefers this value for the session entry's timestamp and falls back to the
+     * accounting-time clock when absent, so a whole managed task no longer
+     * collapses to a single save-time millisecond. Not authoritative for ordering
+     * (array order is) — treat as display metadata (e.g. per-message "N ago").
+     */
+    timestamp?: string;
 }
 interface KodaXTokenUsage {
     inputTokens: number;
@@ -595,4 +629,4 @@ interface KodaXProviderStreamOptions {
     signal?: AbortSignal;
 }
 
-export type { KodaXToolResultBlock as $, KodaXReasoningCapability as A, KodaXReasoningEffortPreset as B, KodaXReasoningEffortRequest as C, KodaXReasoningEffortWireStrategy as D, KodaXReasoningMode as E, KodaXReasoningProfile as F, KodaXReasoningRequest as G, KodaXRedactedThinkingBlock as H, KodaXReviewScale as I, KodaXRiskLevel as J, KodaXAssuranceIntent as K, KodaXStableEffortIntent as L, KodaXStreamResult as M, KodaXTaskActionability as N, KodaXTaskBudgetOverrides as O, KodaXTaskComplexity as P, KodaXTaskFamily as Q, KodaXTaskRoutingDecision as R, KodaXTaskType as S, KodaXTaskWorkIntent as T, KodaXTextBlock as U, KodaXThinkingBlock as V, KodaXThinkingBudgetMap as W, KodaXThinkingDepth as X, KodaXThinkingWireStrategy as Y, KodaXTokenUsage as Z, KodaXToolDefinition as _, KodaXCacheBoundary as a, KodaXToolResultContentItem as a0, KodaXToolResultImageItem as a1, KodaXToolResultTextItem as a2, KodaXToolUseBlock as a3, KodaXVerifyCredentialResult as a4, KodaXVerifyStrategy as a5, KodaXWireReasoningEffort as a6, KodaXChildFanoutClass as b, KodaXContentBlock as c, KodaXCustomProviderConfig as d, KodaXExecutionMode as e, KodaXExecutionPattern as f, KodaXHarnessProfile as g, KodaXImageBlock as h, KodaXListModelsResult as i, KodaXMessage as j, KodaXModelDescriptor as k, KodaXMutationSurface as l, KodaXNormalizedReasoningRequest as m, KodaXProtocolFamily as n, KodaXProviderCapabilityProfile as o, KodaXProviderConfig as p, KodaXProviderContextFidelity as q, KodaXProviderConversationSemantics as r, KodaXProviderEvidenceSupport as s, KodaXProviderLongRunningSupport as t, KodaXProviderMcpSupport as u, KodaXProviderMultimodalSupport as v, KodaXProviderSessionSupport as w, KodaXProviderStreamOptions as x, KodaXProviderToolCallingFidelity as y, KodaXProviderTransport as z };
+export type { KodaXTokenUsage as $, KodaXReasoningCapability as A, KodaXReasoningEffortPreset as B, KodaXReasoningEffortRequest as C, KodaXReasoningEffortWireStrategy as D, KodaXReasoningMode as E, KodaXReasoningProfile as F, KodaXReasoningRequest as G, KodaXRedactedThinkingBlock as H, KodaXReviewScale as I, KodaXRiskLevel as J, KodaXAssuranceIntent as K, KodaXStableEffortIntent as L, KodaXStreamResult as M, KodaXTaskActionability as N, KodaXTaskBudgetOverrides as O, KodaXTaskComplexity as P, KodaXTaskFamily as Q, KodaXTaskResultMetadata as R, KodaXTaskResultSource as S, KodaXTaskRoutingDecision as T, KodaXTaskType as U, KodaXTaskWorkIntent as V, KodaXTextBlock as W, KodaXThinkingBlock as X, KodaXThinkingBudgetMap as Y, KodaXThinkingDepth as Z, KodaXThinkingWireStrategy as _, KodaXCacheBoundary as a, KodaXToolDefinition as a0, KodaXToolResultBlock as a1, KodaXToolResultContentItem as a2, KodaXToolResultImageItem as a3, KodaXToolResultTextItem as a4, KodaXToolUseBlock as a5, KodaXVerifyCredentialResult as a6, KodaXVerifyStrategy as a7, KodaXWireReasoningEffort as a8, KodaXChildFanoutClass as b, KodaXContentBlock as c, KodaXCustomProviderConfig as d, KodaXExecutionMode as e, KodaXExecutionPattern as f, KodaXHarnessProfile as g, KodaXImageBlock as h, KodaXListModelsResult as i, KodaXMessage as j, KodaXModelDescriptor as k, KodaXMutationSurface as l, KodaXNormalizedReasoningRequest as m, KodaXProtocolFamily as n, KodaXProviderCapabilityProfile as o, KodaXProviderConfig as p, KodaXProviderContextFidelity as q, KodaXProviderConversationSemantics as r, KodaXProviderEvidenceSupport as s, KodaXProviderLongRunningSupport as t, KodaXProviderMcpSupport as u, KodaXProviderMultimodalSupport as v, KodaXProviderSessionSupport as w, KodaXProviderStreamOptions as x, KodaXProviderToolCallingFidelity as y, KodaXProviderTransport as z };

package/dist/types-chunks/{types.d-D4ZA8LJV.d.ts → types.d-CSZAMmU-.d.ts}

@@ -1,4 +1,5 @@
-import { z as Guardrail, aO as RunnerToolCall, e as Agent, g as AgentMessage, aR as RunnerToolResult, a_ as Span, _ as KodaXInputArtifact } from './process.d-DHow2y2G.js';
+import { z as Guardrail, aP as RunnerToolCall, e as Agent, g as AgentMessage, aS as RunnerToolResult, a$ as Span, _ as KodaXInputArtifact } from './process.d-C93UMgPK.js';
+import { R as KodaXTaskResultMetadata } from './types.d-Bp4Lm1jv.js';
 
 /**
  * Guardrail Runtime — FEATURE_085 (v0.7.26).
@@ -185,6 +186,7 @@ interface QueuedMessage {
     readonly mode: MessageMode;
     readonly content: string;
     readonly inputArtifacts?: readonly QueuedInputArtifact[];
+    readonly taskResult?: KodaXTaskResultMetadata;
     /** Wall-clock timestamp (`Date.now()`) for tracing only — not used for ordering. */
     readonly enqueuedAt: number;
 }
@@ -271,6 +273,7 @@ interface EnqueueInput {
     readonly content: string;
     readonly agentId?: string;
     readonly inputArtifacts?: readonly QueuedInputArtifact[];
+    readonly taskResult?: KodaXTaskResultMetadata;
 }
 
 export { GuardrailBlockedError as G, GuardrailEscalateError as b, collectGuardrails as h, runOutputGuardrails as i, runToolAfterGuardrails as j, runToolBeforeGuardrails as k, runInputGuardrails as r };

package/dist/types-chunks/types.d-vJExiRje.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Agent Skills Standard Type Definitions
+ * Compliant with https://agentskills.io/ specification
+ *
+ * Also supports Claude Code extension fields for compatibility
+ */
+/**
+ * Skill frontmatter as defined in SKILL.md YAML header
+ */
+interface SkillFrontmatter {
+    /** Skill name in kebab-case, max 64 characters */
+    name: string;
+    /** Skill description, max 1024 characters, should include trigger conditions */
+    description: string;
+    /** Whether to disable automatic model invocation (default: false) */
+    disableModelInvocation?: boolean;
+    /** Whether skill appears in / menu (default: true) */
+    userInvocable?: boolean;
+    /** Tool restrictions, e.g., "Read, Grep, Bash(python:*)" */
+    allowedTools?: string;
+    /** Execution context - 'fork' for sub-agent execution */
+    context?: 'fork';
+    /** Sub-agent type: Explore, Plan, general-purpose, etc. */
+    agent?: string;
+    /** Argument hint for UI, e.g., "[file] [format]" */
+    argumentHint?: string;
+    /** Model preference: haiku, sonnet, opus, or a provider-specific model id */
+    model?: string;
+    /** Hooks scoped to this skill's lifecycle */
+    hooks?: SkillHooks;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SkillHook {
+    matcher?: string;
+    command: string;
+}
+interface SkillHooks {
+    SessionStart?: SkillHook[];
+    UserPromptSubmit?: SkillHook[];
+    PreToolUse?: SkillHook[];
+    PostToolUse?: SkillHook[];
+    Stop?: SkillHook[];
+    SubagentStop?: SkillHook[];
+    Notification?: SkillHook[];
+}
+/**
+ * Lightweight skill metadata for system prompt injection
+ * Loaded at startup for progressive disclosure
+ */
+interface SkillMetadata {
+    name: string;
+    description: string;
+    userInvocable: boolean;
+    argumentHint?: string;
+    path: string;
+    source: SkillSource;
+    /** If true, exclude from system prompt; still invokable by explicit slash forms. */
+    disableModelInvocation: boolean;
+}
+/**
+ * Complete skill definition with all content loaded
+ */
+interface Skill extends SkillFrontmatter {
+    /** Skill directory absolute path */
+    path: string;
+    /** SKILL.md absolute path */
+    skillFilePath: string;
+    /** Markdown content (with variables resolved) */
+    content: string;
+    /** Raw markdown content (before variable resolution) */
+    rawContent: string;
+    /** Support files */
+    scripts?: SkillFile[];
+    references?: SkillFile[];
+    assets?: SkillFile[];
+    templates?: SkillFile[];
+    resources?: SkillFile[];
+    /** Runtime state */
+    loaded: boolean;
+    source: SkillSource;
+}
+/**
+ * File within a skill directory
+ */
+interface SkillFile {
+    name: string;
+    path: string;
+    relativePath: string;
+    content?: string;
+}
+type SkillSource = 'project' | 'user' | 'plugin' | 'builtin';
+/**
+ * Skill registry interface for managing discovered skills
+ */
+interface ISkillRegistry {
+    /** Read-only view of discovered skill metadata */
+    readonly skills: ReadonlyMap<string, SkillMetadata>;
+    /** Discover skills from all configured paths */
+    discover(): Promise<void>;
+    /** Get skill metadata by name */
+    get(name: string): SkillMetadata | undefined;
+    /** Load full skill content */
+    loadFull(name: string): Promise<Skill>;
+    /** Invoke a skill with arguments */
+    invoke(name: string, args: string, context: SkillContext): Promise<SkillResult>;
+    /** Reload skills from disk */
+    reload(): Promise<void>;
+    /** List all discovered skills */
+    list(): ReadonlyArray<SkillMetadata>;
+    /** List skills that can be invoked directly by users */
+    listUserInvocable(): ReadonlyArray<SkillMetadata>;
+    /** Check whether a skill exists */
+    has(name: string): boolean;
+    /** Number of discovered skills */
+    readonly size: number;
+}
+/**
+ * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic context resolution.
+ *
+ * Receives the literal command string and the working directory the resolver
+ * would have used. Must return the command's text output (which the resolver
+ * splices into the skill markdown in place of the `!`cmd`` token), or throw
+ * to deny.
+ *
+ * **Trust boundary**: when the KodaX SDK is embedded inside a host app
+ * (e.g. KodaX Space, IDE extensions), the host typically mediates shell
+ * execution through a permission broker so the end user can approve / deny
+ * each command. Without this hook, `VariableResolver` directly `execSync`s
+ * commands using its own built-in whitelist — bypassing the host's broker
+ * and producing OS side-effects the user never saw.
+ *
+ * Embedders should route here to:
+ *   - prompt the user via their own UI,
+ *   - log execution to their audit trail,
+ *   - apply policy (e.g. block network commands),
+ *   - or refuse outright (throw).
+ *
+ * @example
+ * ```ts
+ * const context: SkillContext = {
+ *   workingDirectory: '/repo',
+ *   executeDynamicContext: async (cmd, cwd) => {
+ *     const approved = await brokerAskUser({ kind: 'skill-cmd', command: cmd, cwd });
+ *     if (!approved) throw new Error('user denied');
+ *     return await brokerExecute(cmd, cwd);
+ *   },
+ * };
+ * ```
+ */
+type SkillDynamicContextExecutor = (command: string, cwd: string) => Promise<string>;
+interface SkillContext {
+    workingDirectory: string;
+    projectRoot?: string;
+    /**
+     * Optional. Used to substitute `${CLAUDE_SESSION_ID}` / `${KODAX_SESSION_ID}`
+     * template variables in skill markdown. Tool-invocation callers (e.g. the
+     * `skill` tool) may not have a session bound — in that case the resolver
+     * falls back to an empty replacement so the substitution doesn't leak the
+     * literal `${...}` to the LLM.
+     */
+    sessionId?: string;
+    environment?: Record<string, string>;
+    messages?: unknown[];
+    /**
+     * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic-context resolution.
+     * See {@link SkillDynamicContextExecutor} for the trust-boundary rationale.
+     * When present, completely replaces the built-in `execSync`-based path
+     * (whitelist + 5s timeout). When absent, the legacy whitelist path runs.
+     */
+    executeDynamicContext?: SkillDynamicContextExecutor;
+    /**
+     * v0.7.42 — hard-disable `!`cmd`` resolution.
+     * When `true`, encountering a `!`cmd`` token throws
+     * `[Dynamic context disabled by host]` regardless of any hook. Useful for
+     * embedders that want a single-flag kill switch without writing a hook.
+     * `executeDynamicContext` is ignored when this is `true`.
+     */
+    disableDynamicContext?: boolean;
+}
+interface SkillResult {
+    success: boolean;
+    /** Processed prompt content */
+    content: string;
+    /** Generated artifacts */
+    artifacts?: SkillArtifact[];
+    error?: string;
+}
+interface SkillArtifact {
+    type: 'file' | 'code' | 'text';
+    name: string;
+    content: string;
+    path?: string;
+}
+interface IVariableResolver {
+    /** Resolve all variables in content */
+    resolve(content: string, args: string, context: SkillContext): Promise<string>;
+}
+interface SkillPathsConfig {
+    projectPaths: string[];
+    userPaths: string[];
+    pluginPaths: string[];
+    builtinPath: string;
+}
+/**
+ * Get default skill discovery paths
+ *
+ * Priority order (highest first):
+ * 1. Project - <projectRoot>/.kodax/skills/
+ * 2. User - ~/.kodax/skills/
+ * 3. User - ~/.agents/skills/ (AgentSkills standard)
+ * 4. Plugin - (dynamic)
+ * 5. Builtin - packages/skills/src/builtin/
+ */
+declare function getDefaultSkillPaths(projectRoot?: string): SkillPathsConfig;
+/**
+ * All skill paths in priority order (highest to lowest)
+ *
+ * Priority: Project > User > Plugin > Builtin
+ * - Project: Project-specific skills override everything else
+ * - User: User preferences (~/.kodax/ and ~/.agents/)
+ * - Plugin: Third-party plugins
+ * - Builtin: Default skills shipped with KodaX
+ */
+declare function getSkillPathsFlat(config: SkillPathsConfig): Array<{
+    path: string;
+    source: SkillSource;
+}>;
+
+export { getDefaultSkillPaths as m, getSkillPathsFlat as n };
+export type { ISkillRegistry as I, Skill as S, IVariableResolver as a, SkillArtifact as b, SkillContext as c, SkillDynamicContextExecutor as d, SkillFile as e, SkillFrontmatter as f, SkillHook as g, SkillHooks as h, SkillMetadata as i, SkillPathsConfig as j, SkillResult as k, SkillSource as l };

package/dist/types-chunks/{utils.d-BURxOxFd.d.ts → utils.d-Boz9k2HB.d.ts}

@@ -1,8 +1,8 @@
-import { P as KodaXOptions, v as KodaXContextTokenSnapshot, m as KodaXAgentMode, U as KodaXRepoIntelligenceMode, a5 as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-D3cddmyV.js';
-import { c as SessionStorage$1, b as PermissionMode } from './storage.d-BsZrBPYu.js';
-import { ai as KodaXSessionUiHistoryItem, aa as KodaXSessionLineage, a2 as KodaXSessionArtifactLedgerEntry, R as KodaXExtensionSessionState, Q as KodaXExtensionSessionRecord, ae as KodaXSessionRuntimeInfo, ag as KodaXSessionStorage, a5 as KodaXSessionData, bL as WorkflowProcessSource } from './process.d-DHow2y2G.js';
-import { j as KodaXMessage, E as KodaXReasoningMode, o as KodaXProviderCapabilityProfile, d as KodaXCustomProviderConfig } from './types.d-Ci5YPFEh.js';
-import { A as AgentsFile, f as AutoModeStats, l as KodaXMcpServersConfig } from './guardrail.d-iK7FwMdW.js';
+import { Q as KodaXOptions, v as KodaXContextTokenSnapshot, a6 as KodaXSkillDynamicContextPolicy, m as KodaXAgentMode, V as KodaXRepoIntelligenceMode, a7 as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-Ds1THKeH.js';
+import { c as SessionStorage$1, b as PermissionMode } from './storage.d-DlZS0g8w.js';
+import { aj as KodaXSessionUiHistoryItem, ab as KodaXSessionLineage, a2 as KodaXSessionArtifactLedgerEntry, R as KodaXExtensionSessionState, Q as KodaXExtensionSessionRecord, af as KodaXSessionRuntimeInfo, ah as KodaXSessionStorage, a6 as KodaXSessionData, bN as WorkflowProcessSource } from './process.d-C93UMgPK.js';
+import { j as KodaXMessage, E as KodaXReasoningMode, o as KodaXProviderCapabilityProfile, d as KodaXCustomProviderConfig } from './types.d-Bp4Lm1jv.js';
+import { A as AgentsFile, f as AutoModeStats, l as KodaXMcpServersConfig } from './guardrail.d-CdqJwwN7.js';
 import * as readline from 'readline';
 import { SpawnSyncReturns } from 'child_process';
 
@@ -48,6 +48,7 @@ interface InteractiveContext {
     runtimeInfo?: KodaXSessionRuntimeInfo;
     createdAt: string;
     lastAccessed: string;
+    skillDynamicContext?: KodaXSkillDynamicContextPolicy;
 }
 declare function createInteractiveContext(options: {
     sessionId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodax-ai/kodax",
-  "version": "0.7.58",
+  "version": "0.7.60",
   "description": "KodaX lightweight coding agent - TypeScript implementation with 15 built-in LLM provider aliases, published as a Node-free single-file CLI and SDK",
   "type": "module",
   "private": false,

package/dist/chunks/argument-completer-QGBNXTYJ.js

@@ -1,2 +0,0 @@
-// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Aa as b,za as a}from"./chunk-QHWXPJEG.js";import"./chunk-6AU6EPO6.js";import"./chunk-XXEIFNBE.js";import"./chunk-NKHXRN7G.js";import"./chunk-73Z7BK5H.js";import"./chunk-PIQWODWN.js";import"./chunk-CQ6EQG7E.js";import"./chunk-D6QVXQNI.js";import"./chunk-526OILYL.js";import"./chunk-7QB55SYG.js";import"./chunk-HS2K74I4.js";import"./chunk-ZZDC75H4.js";import"./chunk-P4VF3JEP.js";import"./chunk-V4WSBIXB.js";export{a as ArgumentCompleter,b as createArgumentCompleter};

package/dist/chunks/chunk-73Z7BK5H.js

@@ -1,15 +0,0 @@
-// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{t as W,z as $}from"./chunk-PIQWODWN.js";import{Da as _,Ea as I}from"./chunk-7QB55SYG.js";import{Ja as b,_a as v,j as k,k as x}from"./chunk-HS2K74I4.js";import{$d as A,Qc as S,Rc as E,Wc as T,ae as w,ce as R,de as O,ee as g}from"./chunk-ZZDC75H4.js";import{a as i}from"./chunk-V4WSBIXB.js";import{join as Re}from"node:path";var L=["You generate KodaX Dynamic Workflow scripts.","Return JSON only. Do not wrap the answer in prose.","For simple tasks that do not benefit from multiple agents, return:",'{"action":"decline","reason":"..."}',"For complex tasks, return:",'{"action":"generate","manifest":{...},"source":"async function run(wf, args) { ... }","approvalSummary":"..."}',"Generated source may only coordinate agents through wf and args.","Generated source must return displayable final text for the user.","Never use import, require, process, fs, child_process, network APIs, shell commands, or direct file access."].join(`
-`),M=12e4,B="KODAX_WORKFLOW_GENERATION_TIMEOUT_SEC",U="KODAX_WORKFLOW_GENERATION_TIMEOUT_MS",J=64,H=2,V=2e3,X=[{name:"default"},{name:"variant-results",finalText:i((e,t)=>`Variant smoke child report from ${e} (${t}).`,"finalText"),synthesizeText:"Variant smoke synthesis report."},{name:"unverified-success",status:i(()=>"completed_unverified","status"),finalText:i(e=>`Smoke result for ${e}: completed with verification warnings.`,"finalText"),synthesizeText:"Smoke synthesis: completed with verification warnings."},{name:"empty-args-rerun",args:i(()=>({}),"args")}],Q=["- classify-and-act: first classify a mixed request, then route to the right worker behavior.","- fan-out-and-synthesize: split independent areas, files, hypotheses, reviewers, or perspectives; run them with wf.parallel, then wf.synthesize.","- adversarial-verification: produce or inspect a candidate, then have an independent verifier attack assumptions, evidence, and edge cases.","- generate-and-filter: ask several generators for distinct candidates, then filter/dedupe/rank before synthesis.","- tournament: compare competing approaches or answers and use synthesis as the judge.","- loop-until-done: run bounded follow-up rounds when findings should drive the next prompt.","- review or audit combines fan-out-and-synthesize with adversarial-verification: fan independent reviewers out across the dimensions, then pipe each finding straight into a verifier that tries to refute it before synthesis. A review with no verification stage ships findings a single reviewer's blind spot would have hidden."],Y=[{id:"import",pattern:/\bimport\s*(?:\(|['"*{]|\w+\s+from\b)/},{id:"require",pattern:/\brequire\s*\(/},{id:"process",pattern:/\bprocess\s*(?:\.|\[)/},{id:"fs",pattern:/\b(?:node:)?fs\b/},{id:"child_process",pattern:/\bchild_process\b/},{id:"shell",pattern:/\b(?:exec|spawn|execFile)\s*\(/},{id:"fetch",pattern:/\bfetch\s*\(/},{id:"Deno",pattern:/\bDeno\s*(?:\.|\[)/},{id:"Bun",pattern:/\bBun\s*(?:\.|\[)/}];function Z(e=process.env,t){let n=k(t?.workflow?.generationTimeoutSec,"timeouts.workflow.generationTimeoutSec");if(n!==void 0)return n;let r=x(e[B]);if(r!==void 0)return r;let s=e[U];if(s===void 0||s.trim().length===0)return M;let o=Number(s);return!Number.isFinite(o)||o<=0?M:Math.floor(o)}i(Z,"resolveWorkflowGenerationTimeoutMs");function ee(e,t){if(typeof e!="object"||e===null)throw new Error(`${t} must be an object`);return e}i(ee,"readRecord");function q(e,t){let n=e[t];if(typeof n!="string"||n.trim().length===0)throw new Error(`workflow generation ${t} must be a non-empty string`);return n}i(q,"readNonEmptyString");function te(e){let t=e.trim(),n=/^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(t);if(n?.[1])return n[1].trim();let r=t.indexOf("{"),s=t.lastIndexOf("}");if(r>=0&&s>r)return t.slice(r,s+1);throw new Error("workflow generation output did not contain a JSON object")}i(te,"extractJsonText");function ne(e){let t=te(e);return ee(JSON.parse(t),"workflow generation output")}i(ne,"parseGenerationJson");function re(e){if(typeof e=="string"){let n=e.trim();return n.length>0?n:void 0}if(typeof e!="object"||e===null)return;let t=e;for(let n of["name","id","title","phase"]){let r=t[n];if(typeof r=="string"&&r.trim().length>0)return r.trim()}}i(re,"normalizePhaseEntry");function se(e){return e.split(/(?:->|\u2192|,|\n)/).map(t=>t.trim()).filter(t=>t.length>0)}i(se,"splitPhaseString");function oe(e){if(typeof e!="object"||e===null)return e;let t=e,n=t.phases,r;if(Array.isArray(n)){let s=n.map(re);s.every(o=>o!==void 0)&&(r=s)}else if(typeof n=="string"){let s=se(n);s.length>0&&(r=s)}return r?{...t,phases:r}:e}i(oe,"normalizeGeneratedManifestCandidate");function ie(e){return e.match(/\bwf\.(?:runAgent|spawnAgent|synthesize)\s*\(/g)?.length??0}i(ie,"estimateDirectAgentCalls");function ae(e,t){let n=e.maxConcurrency*Math.max(1,e.phases.length)+2,r=ie(t)+2,s=Math.min(J,Math.max(e.maxAgents,n,r));return s>e.maxAgents?{...e,maxAgents:s}:e}i(ae,"reserveGeneratedWorkflowAgentCapacity");function m(e){let t="",n=0;for(;n<e.length;){let r=e[n],s=e[n+1];if(r==="/"&&s==="/"){for(t+="  ",n+=2;n<e.length&&e[n]!==`
-`;)t+=" ",n+=1;continue}if(r==="/"&&s==="*"){for(t+="  ",n+=2;n<e.length;){if(e[n]==="*"&&e[n+1]==="/"){t+="  ",n+=2;break}t+=e[n]===`
-`?`
-`:" ",n+=1}continue}if(r==='"'||r==="'"||r==="`"){let o=r;for(t+=" ",n+=1;n<e.length;){let l=e[n];if(t+=l===`
-`?`
-`:" ",n+=1,l==="\\"){n<e.length&&(t+=e[n]===`
-`?`
-`:" ",n+=1);continue}if(l===o)break}continue}t+=r??"",n+=1}return t}i(m,"stripGeneratedSourceLiterals");function le(e,t){for(let n=t+1;n<e.length;n+=1){let r=e[n];if(r==="\\"){n+=1;continue}if(r==="`")return!1;if(r==="$"&&e[n+1]==="{")return!0}return!1}i(le,"templateLiteralHasExpression");function ce(e){let t=m(e),n=/\bwf\s*\.\s*(wait|snapshot|send|stop)\s*\(/g,r;for(;(r=n.exec(t))!==null;){let s=r[1];if(!s)continue;let o=t.indexOf("(",r.index);if(o<0)continue;let l=o+1;for(;/\s/.test(e[l]??"");)l+=1;let f=e[l];if(!(f==="`"&&le(e,l))&&(f==='"'||f==="'"||f==="`"))return{method:s}}}i(ce,"findLiteralWorkflowTaskTarget");function N(e){return e!==void 0&&/[A-Za-z0-9_$]/.test(e)}i(N,"isIdentifierPart");function j(e){let t=m(e),n=/\basync\s+function\s+run\s*\([^)]*\)\s*\{/.exec(t);if(!n)return;let r=t.indexOf("{",n.index);if(r<0)return;let s=0;for(let o=r;o<t.length;o+=1){let l=t[o];if(l==="{"&&(s+=1),l==="}"&&(s-=1,s===0))return{start:r+1,end:o}}}i(j,"findRunBodyRange");function D(e,t){let n=m(e),r=1;for(let s=t.start;s<t.end;s+=1){let o=n[s];if(o==="{"){r+=1;continue}if(o==="}"){r-=1;continue}if(r===1&&n.startsWith("return",s)&&!N(n[s-1])&&!N(n[s+6])){let l=s+6,f=0;for(let u=l;u<t.end;u+=1){let p=n[u];if((p==="("||p==="["||p==="{")&&(f+=1),(p===")"||p==="]"||p==="}")&&(f-=1),f===0&&(p===";"||p===`
-`||p==="\r"))return e.slice(l,u).trim()}return e.slice(l,t.end).trim()}}}i(D,"findTopLevelReturnExpression");function F(e){let t=j(e);if(t)return D(e,t)}i(F,"findOuterRunReturnExpression");function fe(e){let t=j(e);if(!t)return[];let n=m(e),r=[],s=t.start,o=1;for(let f=t.start;f<t.end;f+=1){let u=n[f];if(u==="{"||u==="("||u==="["){o+=1;continue}if(u==="}"||u===")"||u==="]"){o-=1;continue}if(u===";"&&o===1){let p=e.slice(s,f+1).trim();p&&r.push(p),s=f+1}}let l=e.slice(s,t.end).trim();return l&&r.push(l),r}i(fe,"findOuterRunStatements");function ue(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}i(ue,"escapeRegExp");function de(e,t){let n=/^[A-Za-z_$][A-Za-z0-9_$]*$/.exec(t.trim())?.[0];if(!n)return!1;let r=ue(n),s=new RegExp(`^\\s*(?:const|let|var)\\s+${r}\\s*=\\s*(?:await\\s+)?wf\\s*\\.\\s*artifact\\b`),o=new RegExp(`^\\s*${r}\\s*=\\s*(?:await\\s+)?wf\\s*\\.\\s*artifact\\b`);return fe(e).some(l=>s.test(l)||o.test(l))}i(de,"isReturnedArtifactHandle");function C(e,t,n,r){let s=0;for(let o=t;o<e.length;o+=1){let l=e[o];if(l===n&&(s+=1),l===r&&(s-=1,s===0))return o}}i(C,"findMatchingDelimiter");function pe(e,t,n){let r=0;for(let s=t;s<n;s+=1){let o=e[s];if(o==="("||o==="["||o==="{"){r+=1;continue}if(o===")"||o==="]"||o==="}"){r-=1;continue}if(o===","&&r===0)return s}}i(pe,"findTopLevelComma");function he(e){let t=m(e),n=/^\s*(?:await\s+)?wf\s*\.\s*phase\s*\(/.exec(t);if(!n)return;let r=t.indexOf("(",n.index);if(r<0)return;let s=C(t,r,"(",")");if(s===void 0)return;let o=pe(t,r+1,s);if(o===void 0)return;let l=e.slice(o+1,s).trim(),f=m(l),u=f.indexOf("=>");if(u<0)return;let p=u+2,a=f.slice(p).search(/\S/);if(a<0)return;let c=p+a;if(f[c]!=="{")return l.slice(c).trim();let d=C(f,c,"{","}");if(d!==void 0)return D(l,{start:c+1,end:d})}i(he,"findPhaseCallbackReturnExpression");function P(e,t){return new RegExp(`^(?:await\\s+)?wf\\s*\\.\\s*${t}\\b`).test(e.trim())}i(P,"isDirectWorkflowCall");function G(e,t){let n=t.trim();if(/^(?:undefined|null|void\s+0|\{\s*\}|\[\s*\]|''|""|``)$/.test(n)||P(n,"artifact")||de(e,n))return!1;if(P(n,"phase")){let r=he(n);return r!==void 0&&G(n,r)}return!0}i(G,"isDisplayableReturnExpression");function me(e){let t=F(e);return t?G(e,t):!1}i(me,"hasDisplayableRunReturn");function we(e){try{R(e,{filename:"generated-workflow.js",requireAsyncRun:!0,checkSourcePolicy:!1})}catch(t){let n=t instanceof Error?t.message:String(t),s=/Unexpected (identifier|string|token|end of input)|Invalid or unexpected token/i.test(n)?" \u2014 a prompt string likely has an unescaped quote or apostrophe; wrap that string in double quotes or backticks, or escape the quote, then retry":"";throw new Error(`workflow generation source has invalid JavaScript syntax: ${n}${s}`)}}i(we,"assertGeneratedWorkflowSyntax");function ge(e){let t=0,n=new Map,r=[],s=i(a=>{t+=1;let c=`smoke-task-${t}-${Math.random().toString(36).slice(2,8)}`;return n.set(c,a),{taskId:c,name:a}},"nextHandle"),o=i((a,c)=>{if(n.has(c))return;throw[...n.entries()].find(h=>h[1]===c)?new Error(`wf.${a}("${c}") used an agent name, but workflow task APIs require the taskId returned by spawnAgent/runAgent. Store the handle/result and pass handle.taskId or result.taskId. wf.runAgent already returns the completed result; wf.parallel returns the array of results.`):new Error(`wf.${a}("${c}") references an unknown workflow task id`)},"assertKnownTaskId"),l=i(a=>{for(let c of a.evidenceRefs??[]){if(c.startsWith("file:")||c.startsWith("diff:")||c.startsWith("finding:"))continue;if(c.startsWith("task_id:")){let h=c.slice(8).trim();if(h.length===0)throw new Error(`wf.runAgent("${a.name}") evidenceRefs contains empty task_id: reference`);o("evidenceRefs",h);continue}throw[...n.entries()].find(h=>h[1]===c)?new Error(`wf.runAgent("${a.name}") evidenceRefs contains agent name "${c}". Use "task_id:" + result.taskId from the child result.`):new Error(`wf.runAgent("${a.name}") evidenceRefs contains unsupported ref "${c}". Use file:, diff:, finding:, or task_id:<id>.`)}},"assertEvidenceRefs"),f=i((a,c)=>{o("wait",a);let d=n.get(a)??c??a,h=e.status?.(d,a)??"completed";return{taskId:a,name:d,status:h,finalText:e.finalText?.(d,a)??`Smoke result for ${d}: completed, done, verified.`}},"resultFor"),u=i((a,c)=>{o(a,c);let d=n.get(c)??c;return{taskId:c,name:d,status:"completed",lastText:`Smoke snapshot for ${d}`}},"snapshotFor");return{api:{runId:"run-smoke",args:void 0,budget:{total:null,spent:i(()=>0,"spent"),remaining:i(()=>1/0,"remaining")},phase:i(async(a,c)=>c(),"phase"),spawnAgent:i(async a=>(l(a),s(a.name)),"spawnAgent"),runAgent:i(async a=>{l(a);let c=s(a.name),d=f(c.taskId,a.name);if(d.status==="failed"||d.status==="stopped")throw new Error(`workflow task ${d.name} (${d.taskId}) ${d.status}`);return d},"runAgent"),wait:i(async a=>f(a),"wait"),snapshot:i(async a=>u("snapshot",a),"snapshot"),output:i(async a=>u("output",a),"output"),send:i(async a=>{o("send",a)},"send"),stop:i(async a=>{o("stop",a)},"stop"),parallel:i(async a=>Promise.all(a.map(c=>c())),"parallel"),synthesize:i(async()=>({text:e.synthesizeText??"Smoke synthesis: completed, done, verified."}),"synthesize"),artifact:i(async a=>(r.push(a),{name:a}),"artifact"),log:i(()=>{},"log")},artifactCount:i(()=>r.length,"artifactCount")}}i(ge,"createSmokeWorkflowApi");function ke(e,t){if(t>0)return!0;if(typeof e=="string")return e.trim().length>0;if(e==null)return!1;if(typeof e!="object")return!0;if(Array.isArray(e))return e.length>0;let n=e,r=!1,s=n.synthesis;if(typeof s=="string"&&(r=!0,s.trim().length>0))return!0;if(s&&typeof s=="object"){r=!0;let o=s.text;if(typeof o=="string"&&o.trim().length>0)return!0}for(let o of["summary","report","text","result"]){let l=n[o];if(l!==void 0&&(r=!0),typeof l=="string"&&l.trim().length>0)return!0}return r&&Object.keys(n).every(o=>o==="synthesis"||o==="summary"||o==="report"||o==="text"||o==="result")?!1:Object.keys(n).length>0}i(ke,"isSmokeResultDisplayable");async function ye(e){for(let t of X)try{let n=ge(t),r=await O({source:e.source,wf:n.api,args:t.args?.(e.request)??{request:e.request},filename:"generated-workflow-smoke.js",timeoutMs:V});if(!ke(r,n.artifactCount()))throw new Error("run() returned no displayable result or artifact")}catch(n){let r=n instanceof Error?n.message:String(n);throw new Error(`workflow generation source failed safe smoke validation (${t.name}): ${r}`)}}i(ye,"assertGeneratedWorkflowSmoke");function y(e){if(e.trim().length===0)throw new Error("workflow generation source must be non-empty");if(!/\basync\s+function\s+run\s*\(/.test(e))throw new Error("workflow generation source must define async function run(wf, args)");we(e);let t=m(e);for(let r of Y)if(r.pattern.test(t))throw new Error(`forbidden generated workflow token: ${r.id}`);if(/\.\s*output\b/.test(t))throw/\bwf\s*\.\s*output\s*\(/.test(t)?new Error("workflow generation source must use wf.snapshot(taskId) instead of legacy wf.output(taskId)"):new Error("workflow generation source must use finalText/text instead of non-existent .output");let n=ce(e);if(n)throw new Error(`workflow generation source must pass taskId variables to wf.${n.method}(...) instead of string literals; use handle.taskId from wf.spawnAgent(...) or result.taskId from wf.runAgent(...).`);for(let r of t.split(/\r?\n/)){let s=r.search(/\bwf\.artifact\s*\(/);if(s>=0&&!/\b(?:await|return)\b/.test(r.slice(0,s)))throw new Error("workflow generation source must await wf.artifact(...)")}if(!me(e)){let r=F(e),s=r===void 0?"no top-level `return` was found in run() \u2014 a return inside a wf.phase(...) callback does not count":`the top-level return \`${r.slice(0,80)}\` is not displayable \u2014 do not return undefined/null/{}, a bare wf.artifact(...) write, or a wf.phase(...) without a displayable callback return`;throw new Error(`workflow generation source outer run function must return displayable final text (${s})`)}return e}i(y,"validateGeneratedWorkflowSource");function xe(e){let t=e?.trim();return t?["","Referenced skill instructions (authoritative):",t,"","Skill handling requirements:","- Treat the referenced skill instructions above as binding requirements for this workflow generation.","- Preserve skill-specific file layout, naming, and process requirements in child-agent prompts that do the work.",'- Do not replace concrete skill requirements with vague paths such as "or similar"; choose paths from the skill or instruct the child to invoke the skill before acting.']:[]}i(xe,"buildReferencedSkillPromptSection");function z(e,t){return["Task request:",e,...xe(t),"","Available WorkflowApi calls:","- wf.phase(name, async () => ...)","- wf.spawnAgent({ name, prompt, readOnly, modelHint, isolation, evidenceRefs, verification })","- wf.runAgent({ name, prompt, readOnly, modelHint, isolation, evidenceRefs, verification })","- wf.wait(taskId), wf.snapshot(taskId), wf.send(taskId, content), wf.stop(taskId, reason)","- wf.parallel([() => promise], { concurrency })","- wf.synthesize({ inputs, rubric }); inputs may be an array of materials, one already-formatted string, or a named object of materials","- wf.artifact(name, value), wf.log({ message, data })","- Return shapes: wf.runAgent/wf.wait return { taskId, name, status, finalText, digest?, verification?, usage }; wf.snapshot returns { taskId, name, status, lastText? }; wf.synthesize returns { text }; wf.artifact returns { name, path? }.","- Task identity rule: taskId is the opaque result.taskId/handle.taskId value, never the agent name string. Do not hardcode task IDs or pass string literals to wf.wait/wf.snapshot/wf.send/wf.stop; pass handle.taskId or result.taskId variables.","- Important naming trap: never use anyVariable.output in generated source. Agent results use finalText; synthesis results use text; task snapshots use lastText.","- Always await asynchronous workflow calls, especially wf.artifact(...), before returning.",'- Treat args as optional rerun input. Read request text with a fallback such as String(args.request || "the original request") or bake stable request context into child prompts.',"- For fan-out, prefer wf.parallel with thunks that call wf.runAgent; if using wf.spawnAgent, always wait or stop each handle so maxConcurrency capacity can release.","- Correct fan-out result pattern: const results = await wf.parallel([...].map((item) => () => wf.runAgent({...})), { concurrency }); then use results[n].finalText or results.map((r) => r.finalText). Do not call wf.wait after wf.runAgent.","- Keep intermediate findings in local variables and pass their finalText/text values forward; artifacts are durable outputs, not mutable args.","- File-writing/implementation requests are not report-only workflows. If the user asks to create, update, land, implement, or write project files, set manifest.readOnly=false, use readOnly:false child agents for the writing phases, give exact target paths in the prompt, and include verification:{ requiresMutation:true, requiredChangedPaths:[...], rejectPreparatoryFinalText:true } whenever target paths are knowable.","- Never put placeholder paths such as vNEXT.md or TODO.md in requiredChangedPaths. If the exact path is not knowable, omit requiredChangedPaths and keep requiresMutation:true.","- A write child must not ask the user to confirm routine filenames or version numbers already inferable from the request/context; it should choose the minimal project-consistent target paths, write them, and report what changed.",'- Prefer shared-cwd for write children. Do not set isolation:"worktree" for writing phases unless the workflow has an explicit merge-back strategy; isolated write evidence is not a delivered project change.',"- The outer run function must return displayable final text, preferably { synthesis: finalText }. Returning only inside a wf.phase callback is invalid. Artifact-only or empty returns are invalid.",'- Also await wf.artifact("final-report", { summary/report/text: finalText }) for durable inspection when a final report is produced.','- For multi-line prompts, rubrics, or report templates inside source, use JavaScript template literals (`...`) or arrays joined with "\\n"; never place raw newlines inside single-quoted or double-quoted strings.',"- Do not ask child agents to emit special transcript marker blocks. KodaX derives child-agent transcript digests after each child finishes; child prompts should focus on the actual work product and final report.","","Minimal source field-usage example; use it for result fields/syntax, not as the default workflow shape:","async function run(wf, args) {",'  const first = await wf.runAgent({ name: "first-pass", prompt: String(args.request || ""), readOnly: true });','  const second = await wf.runAgent({ name: "second-pass", prompt: first.finalText, readOnly: true });','  const synthesis = await wf.synthesize({ inputs: [first.finalText, second.finalText], rubric: "Synthesize a final answer." });',"  const finalText = synthesis.text;",'  await wf.artifact("final-report", { report: finalText });',"  return { synthesis: finalText };","}","","Canonical write-and-verify pattern for requests that must land project files:","async function run(wf, args) {",'  const request = String(args.request || "Implement the requested project change.");',"  const targetPaths = Array.isArray(args.targetPaths) ? args.targetPaths.map(String).filter(Boolean) : [];","  const writer = await wf.runAgent({",'    name: "implementation-writer",',"    prompt: [",'      "Implement the requested project change in the real workspace.",','      "Use project conventions, write the files, and do not stop at a plan.",','      targetPaths.length ? "Target paths: " + targetPaths.join(", ") : "Choose the minimal project-consistent target paths.",',"      request",'    ].join("\\n"),',"    readOnly: false,","    verification: {","      requiresMutation: true,","      ...(targetPaths.length ? { requiredChangedPaths: targetPaths } : {}),","      rejectPreparatoryFinalText: true","    }","  });","  const finalText = writer.finalText;",'  await wf.artifact("final-report", { report: finalText, verification: writer.verification });',"  return { synthesis: finalText, verification: writer.verification };","}","",`Supported pattern ids: ${A.join(", ")}`,"","Pattern selection guidance:",...Q,"- Complex multi-part work should normally include at least two work phases plus a final wf.synthesize barrier.","- Do not collapse independent investigation, verification, ranking, generation/filtering, or iteration into one child agent.","- A generated workflow with only one child agent is appropriate only when the request has one indivisible work product; otherwise decline simple tasks or generate a richer pattern.",'- Use evidenceRefs when one child reviews another child result; reference child results as "task_id:" + result.taskId, never as bare agent names. Use modelHint:"deep" for verifiers, judges, and synthesis-critical workers.',"","Manifest requirements:","- name, description, phases, readOnly, maxAgents, maxConcurrency, optional plannedAgents, optional tokenBudget",'- phases must be a JSON array of non-empty string literals, for example ["investigate","verify","synthesize"]; never return phase objects or a single string',"- maxAgents and maxConcurrency must be positive JSON integers","- plannedAgents is the best estimate of how many child agents this script will normally launch; it is for progress display and must be no larger than maxAgents","- maxAgents is a lifetime total cap for every wf.runAgent, wf.spawnAgent, and wf.synthesize call in the whole run, not the parallel lane count; reserve enough for all phases plus synthesis","- Do not set tokenBudget unless the user explicitly asks for a token/resource budget; omit it for normal complex work","- readOnly must be a JSON boolean","- optional mayUseWorktree when child prompts need isolated worktrees","- patterns must use only supported ids","- Use the same natural language as the task request for manifest description, approvalSummary, child agent prompts, synthesis rubric, and artifact text unless the user explicitly asks otherwise","","Return JSON only."].join(`
-`)}i(z,"buildWorkflowGenerationUserPrompt");async function be(e,t){let n=_(e),r=I(e);if(n.length===0&&r.length===0)return;let s=t.context?.gitRoot??t.context?.executionCwd??process.cwd(),o=t.context?.executionCwd??s,l=S(s);l.size===0&&await E(s);let f={workingDirectory:o,projectRoot:s,environment:{}},u=[...n,...r.filter(a=>!n.includes(a)&&l.has(a))];if(u.length===0)return;let p=[];for(let a of n)if(!l.has(a)){let c=l.list().map(d=>d.name).sort().join(", ");throw new Error(`workflow generation referenced unknown skill "${a}". Available skills: ${c||"(none)"}`)}for(let a of u){let c=await l.loadFull(a),d=await T(c,"",f);if(d.disableModelInvocation)throw new Error(`workflow generation referenced disabled skill "${a}"`);p.push(d.content)}return p.join(`
-
-`)}i(be,"buildWorkflowGenerationSkillContext");function ve(e){let t=["- Replace result.output from wf.runAgent(...) or wf.wait(...) with result.finalText.","- Replace result.output from wf.synthesize(...) with result.text.",'- Replace hardcoded wf.wait("...")/wf.snapshot("...")/wf.send("...", ...)/wf.stop("...", ...) calls with handle.taskId/result.taskId variables.','- Replace wf.wait("agent-name") after wf.runAgent(...) with captured runAgent/parallel results; wf.wait only accepts taskId values from spawnAgent handles.',"- Preserve the existing phase, fan-out, cross-review, and synthesis topology unless that topology itself is invalid; fix API usage instead of collapsing the workflow.","- Keep the outer run() return displayable, such as { synthesis: finalText }.",'- Fix generated JavaScript harness errors, including ReferenceError, wrong wf.* argument shapes, and multi-line prompts/rubrics that need template literals or "\\n".'];return(/\bwf\s*\.\s*output\s*\(/.test(e.previousOutput)||e.error.includes("wf.snapshot(taskId)"))&&t.splice(2,0,"- Replace wf.output(taskId) with wf.snapshot(taskId) for in-flight task snapshots."),[z(e.request,e.skillContext),"","Your previous output failed KodaX workflow validation.",`Repair attempt: ${e.attempt} of ${e.maxAttempts}.`,`Validation error: ${e.error}`,"","Common contract fixes:",...t,"","Previous output:",e.previousOutput,"","Return corrected JSON only. Keep the same task intent, but make the manifest and source valid."].join(`
-`)}i(ve,"buildWorkflowGenerationRepairPrompt");function Se(e){return/(?:token\s*(?:budget|limit|cap)|budget\s*(?:for|of)?\s*tokens?|\b\d+(?:\.\d+)?\s*(?:k|m)?\s*tokens?\b|\d+(?:\.\d+)?\s*(?:k|m)?\s*令牌|(?:tokens?|令牌).{0,12}(?:预算|上限|限制)|(?:预算|上限|限制).{0,12}(?:tokens?|令牌))/i.test(e)}i(Se,"requestExplicitlyMentionsTokenBudget");function Ee(e,t){if(e.tokenBudget===void 0||t===void 0||Se(t))return e;let{tokenBudget:n,...r}=e;return r}i(Ee,"stripImplicitTokenBudget");function Te(e,t={}){let n=ne(e),r=n.action;if(r==="decline")return{kind:"declined",reason:q(n,"reason"),rawText:e};if(r!=="generate")throw new Error('workflow generation action must be "generate" or "decline"');let s=y(q(n,"source")),o=Ee(ae(w(oe(n.manifest)),s),t.request),l=typeof n.approvalSummary=="string"&&n.approvalSummary.trim().length>0?n.approvalSummary:o.description;return{kind:"generated",manifest:o,source:s,module:g({manifest:o,source:s}),scriptSnapshot:{manifest:o,source:s},approvalSummary:l,rawText:e}}i(Te,"parseWorkflowGeneration");async function Ae(e){let t=e.request.trim();if(!t)return{kind:"declined",reason:"Workflow request is empty.",rawText:""};let n=H+1,r=z(t,e.skillContext),s="";for(let o=1;o<=n;o+=1){let l=await e.generateText({system:L,prompt:r,...e.signal?{signal:e.signal}:{}});try{let f=Te(l,{request:t});return f.kind==="generated"&&await ye({source:f.source,request:t}),f}catch(f){if(s=f instanceof Error?f.message:String(f),o>=n)break;r=ve({request:t,...e.skillContext?{skillContext:e.skillContext}:{},previousOutput:l,error:s,attempt:o+1,maxAttempts:n})}}throw new Error(`workflow generation did not produce a valid workflow after ${n} attempts. Last validation error: ${s}`)}i(Ae,"generateWorkflow");async function K(e){let t=b(e.options.provider),n=e.options.modelOverride??e.options.model??t.getModel(),r=e.options.effort?.trim();if(e.timeoutMs!==void 0&&e.timeoutSec!==void 0)throw new Error("workflow generation timeoutSec and timeoutMs cannot both be set");let s=e.timeoutMs??k(e.timeoutSec,"workflow generation timeoutSec")??Z(process.env,e.options.timeouts),o=e.skillContext??await be(e.request,e.options);return Ae({request:e.request,...o?{skillContext:o}:{},...e.signal?{signal:e.signal}:{},generateText:i(async l=>{let f=[{role:"user",content:l.prompt}],u=await v({provider:t,model:n,system:l.system,messages:f,querySource:"workflow-generation",timeoutMs:s,...r?{reasoning:{effort:r}}:{},...l.signal?{abortSignal:l.signal}:{}});if(!u.text.trim()){let p=u.error?`: ${u.error.message}`:"",a=u.stopReason==="timeout"?` after ${s}ms`:"";throw new Error(`workflow generation failed (${u.stopReason}${a})${p}`)}return u.text},"generateText")})}i(K,"generateWorkflowFromOptions");async function Oe(e){let t=e.source;if(t.kind==="saved")return{module:t.module};if(t.kind==="inline"){let s=w(t.manifest);return y(t.source),{module:g({manifest:s,source:t.source}),scriptSnapshot:{manifest:s,source:t.source}}}let r=await(e.generateWorkflow??K)({request:t.request,options:e.options});return r.kind==="declined"?{declined:r.reason}:{module:r.module,scriptSnapshot:r.scriptSnapshot}}i(Oe,"resolveModule");async function Fe(e){let t=await Oe(e);if("declined"in t)return{kind:"declined",reason:t.declined};let{module:n,scriptSnapshot:r}=t,s=e.now??(()=>Date.now()),o=e.runId??`run-${s().toString(36)}`,l=Re(e.runsBaseDir,o),f=e.manager??$(),u=W(n,e.options.workflowHostPolicy),p=f.startFromOptions({module:n,args:e.args,options:e.options,runId:o,runDir:l,...r?{scriptSnapshot:r}:{},...e.resumeFromRunDir?{resumeFromRunDir:e.resumeFromRunDir}:{},...e.processMetadata?{processMetadata:e.processMetadata}:{},...e.approval?{approval:e.approval}:{},...e.onEvent?{onEvent:e.onEvent}:{},...e.signal?{signal:e.signal}:{}});return{kind:"started",runId:o,runDir:l,module:n,managed:p,approvalSummary:u,...r?{scriptSnapshot:r}:{}}}i(Fe,"startManagedWorkflow");export{L as a,M as b,Z as c,y as d,z as e,be as f,Te as g,Ae as h,K as i,Fe as j};