qlogicagent 0.5.2 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. package/README.md +402 -402
  2. package/dist/agent.js +18 -0
  3. package/dist/cli.js +360 -0
  4. package/dist/contracts.js +1 -0
  5. package/dist/index.js +22 -0
  6. package/dist/orchestration.js +125 -0
  7. package/dist/types/agent/agent.d.ts +43 -0
  8. package/dist/types/agent/constants.d.ts +47 -0
  9. package/dist/types/agent/tool-loop.d.ts +96 -0
  10. package/dist/types/agent/types.d.ts +250 -0
  11. package/dist/types/cli/main.d.ts +11 -0
  12. package/dist/types/cli/stdio-server.d.ts +56 -0
  13. package/dist/types/cli/tool-bootstrap.d.ts +21 -0
  14. package/dist/types/config/config.d.ts +17 -0
  15. package/dist/types/contracts/hooks.d.ts +175 -0
  16. package/dist/types/contracts/index.d.ts +10 -0
  17. package/dist/types/contracts/planner.d.ts +35 -0
  18. package/dist/types/contracts/skill-candidate.d.ts +63 -0
  19. package/dist/types/contracts/todo.d.ts +14 -0
  20. package/dist/types/index.d.ts +13 -0
  21. package/dist/types/llm/builtin-providers.d.ts +10 -0
  22. package/dist/types/llm/debug-transport.d.ts +12 -0
  23. package/dist/types/llm/index.d.ts +16 -0
  24. package/dist/types/llm/llm-client.d.ts +43 -0
  25. package/dist/types/llm/model-catalog.d.ts +53 -0
  26. package/dist/types/llm/provider-def.d.ts +59 -0
  27. package/dist/types/llm/provider-registry.d.ts +54 -0
  28. package/dist/types/llm/transport.d.ts +62 -0
  29. package/dist/types/llm/transports/anthropic-messages.d.ts +31 -0
  30. package/dist/types/llm/transports/openai-chat.d.ts +36 -0
  31. package/dist/types/orchestration/agent-registry.d.ts +46 -0
  32. package/dist/types/orchestration/context-collapse.d.ts +58 -0
  33. package/dist/types/orchestration/context-compression.d.ts +301 -0
  34. package/dist/types/orchestration/conversation-repair.d.ts +61 -0
  35. package/dist/types/orchestration/curator-scheduler.d.ts +119 -0
  36. package/dist/types/orchestration/error-classification.d.ts +12 -0
  37. package/dist/types/orchestration/failover-classification.d.ts +8 -0
  38. package/dist/types/orchestration/failover-error.d.ts +33 -0
  39. package/dist/types/orchestration/fork-subagent.d.ts +100 -0
  40. package/dist/types/orchestration/index.d.ts +113 -0
  41. package/dist/types/orchestration/memory-provider.d.ts +14 -0
  42. package/dist/types/orchestration/reactive-compact.d.ts +73 -0
  43. package/dist/types/orchestration/retry-loop.d.ts +69 -0
  44. package/dist/types/orchestration/skill-candidate.d.ts +52 -0
  45. package/dist/types/orchestration/skill-consolidation.d.ts +123 -0
  46. package/dist/types/orchestration/skill-improvement.d.ts +59 -0
  47. package/dist/types/orchestration/skill-similarity.d.ts +98 -0
  48. package/dist/types/orchestration/task-types.d.ts +142 -0
  49. package/dist/types/orchestration/team-orchestration.d.ts +195 -0
  50. package/dist/types/orchestration/team-tool-loop-wiring.d.ts +92 -0
  51. package/dist/types/orchestration/tool-choice-policy.d.ts +54 -0
  52. package/dist/types/orchestration/tool-loop-state.d.ts +50 -0
  53. package/dist/types/orchestration/tool-schema.d.ts +39 -0
  54. package/dist/types/orchestration/turn-loop-guard.d.ts +86 -0
  55. package/dist/types/runtime/execution/dream-agent.d.ts +199 -0
  56. package/dist/types/runtime/execution/forked-agent.d.ts +111 -0
  57. package/dist/types/runtime/execution/index.d.ts +6 -0
  58. package/dist/types/runtime/execution/progress-tracker.d.ts +78 -0
  59. package/dist/types/runtime/execution/remote-agent.d.ts +63 -0
  60. package/dist/types/runtime/execution/streaming-tool-executor.d.ts +100 -0
  61. package/dist/types/runtime/execution/tool-eligibility.d.ts +59 -0
  62. package/dist/types/runtime/execution/tool-result-storage.d.ts +87 -0
  63. package/dist/types/runtime/hooks/context-compression.d.ts +61 -0
  64. package/dist/types/runtime/hooks/hook-registry.d.ts +12 -0
  65. package/dist/types/runtime/hooks/index.d.ts +3 -0
  66. package/dist/types/runtime/hooks/memory-hooks.d.ts +49 -0
  67. package/dist/types/runtime/index.d.ts +5 -0
  68. package/dist/types/runtime/infra/cleanup-registry.d.ts +23 -0
  69. package/dist/types/runtime/infra/file-watcher.d.ts +72 -0
  70. package/dist/types/runtime/infra/index.d.ts +6 -0
  71. package/dist/types/runtime/infra/secure-storage.d.ts +81 -0
  72. package/dist/types/runtime/infra/task-runtime.d.ts +108 -0
  73. package/dist/types/runtime/infra/token-budget.d.ts +92 -0
  74. package/dist/types/runtime/infra/worktree-backend.d.ts +85 -0
  75. package/dist/types/runtime/prompt/environment-context.d.ts +23 -0
  76. package/dist/types/runtime/prompt/index.d.ts +3 -0
  77. package/dist/types/runtime/prompt/instruction-loader.d.ts +64 -0
  78. package/dist/types/runtime/prompt/system-prompt-sections.d.ts +63 -0
  79. package/dist/types/runtime/session/index.d.ts +2 -0
  80. package/dist/types/runtime/session/session-memory.d.ts +91 -0
  81. package/dist/types/runtime/session/session-persistence.d.ts +94 -0
  82. package/dist/types/runtime/session/session-state.d.ts +117 -0
  83. package/dist/types/skills/index.d.ts +125 -0
  84. package/dist/types/skills/mcp/index.d.ts +3 -0
  85. package/dist/types/skills/mcp/mcp-http-client.d.ts +66 -0
  86. package/dist/types/skills/mcp/mcp-manager.d.ts +84 -0
  87. package/dist/types/skills/mcp/mcp-stdio-client.d.ts +84 -0
  88. package/dist/types/skills/memory-extractor.d.ts +64 -0
  89. package/dist/types/skills/memory-query-tool.d.ts +43 -0
  90. package/dist/types/skills/memory-store.d.ts +66 -0
  91. package/dist/types/skills/memory-tool.d.ts +67 -0
  92. package/dist/types/skills/permissions/bash-classifier.d.ts +30 -0
  93. package/dist/types/skills/permissions/classifier-cache.d.ts +51 -0
  94. package/dist/types/skills/permissions/denial-tracking.d.ts +42 -0
  95. package/dist/types/skills/permissions/hook-runner.d.ts +85 -0
  96. package/dist/types/skills/permissions/index.d.ts +12 -0
  97. package/dist/types/skills/permissions/permission-classifier.d.ts +41 -0
  98. package/dist/types/skills/permissions/rule-engine.d.ts +41 -0
  99. package/dist/types/skills/permissions/settings-watcher.d.ts +46 -0
  100. package/dist/types/skills/permissions/types.d.ts +113 -0
  101. package/dist/types/skills/plugins/index.d.ts +2 -0
  102. package/dist/types/skills/plugins/plugin-api.d.ts +38 -0
  103. package/dist/types/skills/plugins/plugin-loader.d.ts +45 -0
  104. package/dist/types/skills/plugins/plugin-marketplace.d.ts +61 -0
  105. package/dist/types/skills/portable-tool.d.ts +71 -0
  106. package/dist/types/skills/qmemory-adapter.d.ts +42 -0
  107. package/dist/types/skills/skill-frontmatter.d.ts +19 -0
  108. package/dist/types/skills/skill-guard.d.ts +23 -0
  109. package/dist/types/skills/skill-loader.d.ts +16 -0
  110. package/dist/types/skills/skill-source.d.ts +119 -0
  111. package/dist/types/skills/skill-types.d.ts +199 -0
  112. package/dist/types/skills/think-tool.d.ts +16 -0
  113. package/dist/types/skills/todo-tool.d.ts +63 -0
  114. package/dist/types/skills/tool-registry.d.ts +29 -0
  115. package/dist/types/skills/tools/agent-tool.d.ts +91 -0
  116. package/dist/types/skills/tools/apply-patch-tool.d.ts +29 -0
  117. package/dist/types/skills/tools/ask-user-tool.d.ts +80 -0
  118. package/dist/types/skills/tools/brief-tool.d.ts +74 -0
  119. package/dist/types/skills/tools/browser-tool.d.ts +114 -0
  120. package/dist/types/skills/tools/checkpoint-tool.d.ts +66 -0
  121. package/dist/types/skills/tools/config-tool.d.ts +63 -0
  122. package/dist/types/skills/tools/cron-tool.d.ts +116 -0
  123. package/dist/types/skills/tools/edit-tool.d.ts +43 -0
  124. package/dist/types/skills/tools/exec-tool.d.ts +97 -0
  125. package/dist/types/skills/tools/image-generate-tool.d.ts +62 -0
  126. package/dist/types/skills/tools/instructions-tool.d.ts +103 -0
  127. package/dist/types/skills/tools/lsp-tool.d.ts +153 -0
  128. package/dist/types/skills/tools/mcp-client-types.d.ts +269 -0
  129. package/dist/types/skills/tools/mcp-resource-tools.d.ts +14 -0
  130. package/dist/types/skills/tools/mcp-tool.d.ts +249 -0
  131. package/dist/types/skills/tools/memory-tool.d.ts +74 -0
  132. package/dist/types/skills/tools/monitor-tool.d.ts +113 -0
  133. package/dist/types/skills/tools/music-generate-tool.d.ts +55 -0
  134. package/dist/types/skills/tools/notebook-edit-tool.d.ts +15 -0
  135. package/dist/types/skills/tools/notify-tool.d.ts +53 -0
  136. package/dist/types/skills/tools/patch-tool.d.ts +45 -0
  137. package/dist/types/skills/tools/pdf-tool.d.ts +66 -0
  138. package/dist/types/skills/tools/plan-mode-tool.d.ts +98 -0
  139. package/dist/types/skills/tools/read-tool.d.ts +51 -0
  140. package/dist/types/skills/tools/repl-tool.d.ts +70 -0
  141. package/dist/types/skills/tools/search-tool.d.ts +112 -0
  142. package/dist/types/skills/tools/send-message-tool.d.ts +51 -0
  143. package/dist/types/skills/tools/shell/bash-provider.d.ts +26 -0
  144. package/dist/types/skills/tools/shell/command-classification.d.ts +44 -0
  145. package/dist/types/skills/tools/shell/command-semantics.d.ts +14 -0
  146. package/dist/types/skills/tools/shell/destructive-command-warning.d.ts +10 -0
  147. package/dist/types/skills/tools/shell/exec-permissions.d.ts +52 -0
  148. package/dist/types/skills/tools/shell/index.d.ts +17 -0
  149. package/dist/types/skills/tools/shell/powershell-provider.d.ts +15 -0
  150. package/dist/types/skills/tools/shell/shell-command.d.ts +54 -0
  151. package/dist/types/skills/tools/shell/shell-exec.d.ts +33 -0
  152. package/dist/types/skills/tools/shell/shell-provider.d.ts +85 -0
  153. package/dist/types/skills/tools/shell/task-output.d.ts +45 -0
  154. package/dist/types/skills/tools/skill-invoke-tool.d.ts +46 -0
  155. package/dist/types/skills/tools/skill-list-tool.d.ts +33 -0
  156. package/dist/types/skills/tools/skill-manage-tool.d.ts +73 -0
  157. package/dist/types/skills/tools/skill-view-tool.d.ts +37 -0
  158. package/dist/types/skills/tools/sleep-tool.d.ts +49 -0
  159. package/dist/types/skills/tools/structured-output-tool.d.ts +116 -0
  160. package/dist/types/skills/tools/task-tool.d.ts +104 -0
  161. package/dist/types/skills/tools/team-tool.d.ts +89 -0
  162. package/dist/types/skills/tools/tool-search-tool.d.ts +51 -0
  163. package/dist/types/skills/tools/tts-tool.d.ts +38 -0
  164. package/dist/types/skills/tools/video-edit-tool.d.ts +69 -0
  165. package/dist/types/skills/tools/video-generate-tool.d.ts +62 -0
  166. package/dist/types/skills/tools/video-merge-tool.d.ts +105 -0
  167. package/dist/types/skills/tools/video-upscale-tool.d.ts +45 -0
  168. package/dist/types/skills/tools/web-fetch-tool.d.ts +78 -0
  169. package/dist/types/skills/tools/web-search-tool.d.ts +57 -0
  170. package/dist/types/skills/tools/workflow-tool.d.ts +44 -0
  171. package/dist/types/skills/tools/worktree-tool.d.ts +69 -0
  172. package/dist/types/skills/tools/write-tool.d.ts +45 -0
  173. package/package.json +3 -2
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Discriminated shell type identifier.
3
+ */
4
+ export type ShellType = "bash" | "powershell";
5
+ /**
6
+ * Options passed to `buildExecCommand`.
7
+ */
8
+ export interface BuildCommandOpts {
9
+ /** Unique command invocation ID (for CWD temp-file naming). */
10
+ id: string;
11
+ /** If set, sandbox TMPDIR root. */
12
+ sandboxTmpDir?: string;
13
+ /** Whether sandbox mode is active. */
14
+ useSandbox: boolean;
15
+ }
16
+ /**
17
+ * Result of `buildExecCommand` — the final command string
18
+ * and the path where the shell will write its post-command CWD.
19
+ */
20
+ export interface BuiltCommand {
21
+ /** Fully-wrapped command string ready for spawn. */
22
+ commandString: string;
23
+ /**
24
+ * Temp file path where the shell writes its post-command CWD.
25
+ * Used by the host to track `cd` across invocations.
26
+ * undefined if CWD tracking is not supported / not needed.
27
+ */
28
+ cwdFilePath?: string;
29
+ }
30
+ /**
31
+ * Runtime-agnostic shell provider.
32
+ *
33
+ * Hosts (Gateway / Desktop / Hub) create a provider once, then
34
+ * use it for every `exec()` call. The tool itself never
35
+ * `spawn()`s — the host does, using args from this provider.
36
+ */
37
+ export interface ShellProvider {
38
+ /** Shell type discriminator. */
39
+ readonly type: ShellType;
40
+ /** Absolute path to the shell binary. */
41
+ readonly shellPath: string;
42
+ /**
43
+ * Whether `spawn()` should use `detached: true`.
44
+ * Bash: true (allows job control / cleanup).
45
+ * PowerShell: false (no POSIX process groups on Windows).
46
+ */
47
+ readonly detached: boolean;
48
+ /**
49
+ * Wrap a raw user command into a full shell command string.
50
+ * Handles:
51
+ * - Environment snapshots / session env sourcing (bash)
52
+ * - UTF-16LE EncodedCommand wrapping (PowerShell)
53
+ * - CWD tracking (`pwd -P > file` / `Get-Location | Out-File`)
54
+ * - stdin redirect for interactive commands (bash)
55
+ */
56
+ buildExecCommand(command: string, opts: BuildCommandOpts): Promise<BuiltCommand>;
57
+ /**
58
+ * Return the argv array for `child_process.spawn()`.
59
+ * E.g. bash → `['-c', commandString]`
60
+ * PS → `['-NoProfile', '-NonInteractive', '-Command', cmd]`
61
+ */
62
+ getSpawnArgs(commandString: string): string[];
63
+ /**
64
+ * Return extra environment variables to merge into spawn env.
65
+ * E.g. `{ SHELL: '/bin/bash', GIT_EDITOR: 'true', CLAUDECODE: '1' }`
66
+ */
67
+ getEnvironmentOverrides(command: string): Promise<Record<string, string>>;
68
+ }
69
+ /**
70
+ * Check if PowerShell tool mode should be enabled.
71
+ * Mirrors cc's `isPowerShellToolEnabled()`.
72
+ *
73
+ * On Windows: enabled when `QLOGICAGENT_USE_POWERSHELL` is truthy.
74
+ * On non-Windows: always false.
75
+ */
76
+ export declare function isPowerShellToolEnabled(): boolean;
77
+ /**
78
+ * Default shell type for the current platform.
79
+ */
80
+ export declare function getDefaultShellType(): ShellType;
81
+ /**
82
+ * Generate a short random hex ID for CWD temp file naming.
83
+ * Matches cc's `Math.floor(Math.random() * 0x10000).toString(16)`.
84
+ */
85
+ export declare function generateCommandId(): string;
@@ -0,0 +1,45 @@
1
+ /** Progress callback — matches cc's signature. */
2
+ export type ProgressCallback = (lastLines: string, allLines: string, totalLines: number, totalBytes: number, isIncomplete: boolean) => void;
3
+ /** Max output file on disk (background tasks). */
4
+ export declare const MAX_TASK_OUTPUT_BYTES: number;
5
+ export declare const MAX_TASK_OUTPUT_BYTES_DISPLAY = "5GB";
6
+ /** Lazily generate session-scoped task output directory. */
7
+ export declare function getTaskOutputDir(): string;
8
+ /** Set the task output directory (for embedding hosts to override). */
9
+ export declare function setTaskOutputDir(dir: string): void;
10
+ export declare function getTaskOutputPath(taskId: string): string;
11
+ export declare function generateTaskId(prefix?: string): string;
12
+ /**
13
+ * Single source of truth for a shell command's output.
14
+ * Ported from cc's TaskOutput.
15
+ *
16
+ * For bash commands (file mode): both stdout/stderr go to file fd.
17
+ * For hooks (pipe mode): data flows through writeStdout/writeStderr.
18
+ */
19
+ export declare class TaskOutput {
20
+ #private;
21
+ readonly taskId: string;
22
+ readonly path: string;
23
+ readonly stdoutToFile: boolean;
24
+ constructor(taskId: string, onProgress: ProgressCallback | null, stdoutToFile?: boolean, maxMemory?: number);
25
+ /** Write stdout data (pipe mode). */
26
+ writeStdout(data: string): void;
27
+ /** Write stderr data (pipe mode). */
28
+ writeStderr(data: string): void;
29
+ /** Get captured stdout. For file mode, reads from disk. */
30
+ getStdout(): Promise<string>;
31
+ /** Get captured stderr. In file mode stderr is interleaved with stdout. */
32
+ getStderr(): string;
33
+ get outputFileSize(): number;
34
+ /**
35
+ * Whether the output file content is fully contained in getStdout().
36
+ * If true, the file can be deleted.
37
+ */
38
+ get outputFileRedundant(): boolean;
39
+ /** Write in-memory buffer to disk file. */
40
+ spillToDisk(): void;
41
+ /** Delete the output file on disk. */
42
+ deleteOutputFile(): Promise<void>;
43
+ /** Clean up all resources. */
44
+ clear(): void;
45
+ }
@@ -0,0 +1,46 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ import type { WorkspaceSkill } from "../skill-types.js";
3
+ export declare const SKILL_TOOL_NAME: "skill_invoke";
4
+ export interface SkillInvokeParams {
5
+ skill: string;
6
+ args?: string;
7
+ }
8
+ export declare const SKILL_INVOKE_SCHEMA: {
9
+ readonly type: "object";
10
+ readonly properties: {
11
+ readonly skill: {
12
+ readonly type: "string";
13
+ readonly description: "Name of the skill to invoke. Use skill_list to see available skills.";
14
+ };
15
+ readonly args: {
16
+ readonly type: "string";
17
+ readonly description: string;
18
+ };
19
+ };
20
+ readonly required: readonly ["skill"];
21
+ };
22
+ export interface SkillToolDeps {
23
+ /**
24
+ * Get all available skills (Layer 0 metadata).
25
+ * Returns name + description pairs for tool manifest enrichment.
26
+ */
27
+ listSkills(): WorkspaceSkill[];
28
+ /**
29
+ * Read skill content (Layer 1 instructions).
30
+ * Returns the full SKILL.md content for the named skill.
31
+ * Returns null if skill not found.
32
+ */
33
+ readSkillContent(name: string): Promise<string | null>;
34
+ /**
35
+ * Execute the skill instructions as a sub-turn.
36
+ * The implementation should:
37
+ * 1. Build system prompt from SKILL.md content
38
+ * 2. Run a sub-turn (sidechain) with skill instructions
39
+ * 3. Return the sub-turn's final response
40
+ *
41
+ * If not provided, the skill content is returned directly
42
+ * (the LLM can then follow the instructions in context).
43
+ */
44
+ executeSkillSubturn?(skillName: string, skillContent: string, userArgs: string | undefined, signal?: AbortSignal): Promise<string>;
45
+ }
46
+ export declare function createSkillTool(deps: SkillToolDeps): PortableTool<SkillInvokeParams>;
@@ -0,0 +1,33 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const SKILL_LIST_TOOL_NAME: "skill_list";
3
+ export interface SkillListToolParams {
4
+ category?: string;
5
+ }
6
+ export declare const SKILL_LIST_TOOL_SCHEMA: {
7
+ readonly type: "object";
8
+ readonly properties: {
9
+ readonly category: {
10
+ readonly type: "string";
11
+ readonly description: "Filter skills by category (e.g. 'devops', 'mlops'). Omit to list all.";
12
+ };
13
+ };
14
+ readonly required: readonly [];
15
+ };
16
+ export interface SkillListItem {
17
+ name: string;
18
+ description: string;
19
+ version?: string;
20
+ category?: string;
21
+ }
22
+ export interface SkillListOutput {
23
+ skills: SkillListItem[];
24
+ categories: string[];
25
+ }
26
+ /**
27
+ * Host-provided skill registry for listing.
28
+ */
29
+ export interface SkillListToolDeps {
30
+ /** List all available skills, optionally filtered by category. */
31
+ listSkills(category?: string): Promise<SkillListOutput>;
32
+ }
33
+ export declare function createSkillListTool(deps: SkillListToolDeps): PortableTool<SkillListToolParams>;
@@ -0,0 +1,73 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const SKILL_MANAGE_TOOL_NAME: "skill_manage";
3
+ export type SkillManageAction = "create" | "edit" | "patch" | "delete" | "write_file" | "remove_file";
4
+ export interface SkillManageToolParams {
5
+ action: SkillManageAction;
6
+ name: string;
7
+ content?: string;
8
+ category?: string;
9
+ filePath?: string;
10
+ fileContent?: string;
11
+ oldString?: string;
12
+ newString?: string;
13
+ }
14
+ export declare const SKILL_MANAGE_TOOL_SCHEMA: {
15
+ readonly type: "object";
16
+ readonly properties: {
17
+ readonly action: {
18
+ readonly type: "string";
19
+ readonly enum: readonly ["create", "edit", "patch", "delete", "write_file", "remove_file"];
20
+ readonly description: string;
21
+ };
22
+ readonly name: {
23
+ readonly type: "string";
24
+ readonly description: "Skill name (lowercase, max 64 chars, kebab-case: letters, digits, hyphens).";
25
+ };
26
+ readonly content: {
27
+ readonly type: "string";
28
+ readonly description: string;
29
+ };
30
+ readonly category: {
31
+ readonly type: "string";
32
+ readonly description: "Category/domain (e.g. 'devops', 'mlops'). Used by create to organize skills.";
33
+ };
34
+ readonly filePath: {
35
+ readonly type: "string";
36
+ readonly description: string;
37
+ };
38
+ readonly fileContent: {
39
+ readonly type: "string";
40
+ readonly description: "Content for write_file action. Max 1 MiB.";
41
+ };
42
+ readonly oldString: {
43
+ readonly type: "string";
44
+ readonly description: "Text to find for patch action (must match uniquely in SKILL.md).";
45
+ };
46
+ readonly newString: {
47
+ readonly type: "string";
48
+ readonly description: "Replacement text for patch action (can be empty to delete).";
49
+ };
50
+ };
51
+ readonly required: readonly ["action", "name"];
52
+ };
53
+ export interface SkillManageResult {
54
+ success: boolean;
55
+ message: string;
56
+ path?: string;
57
+ }
58
+ /**
59
+ * Host-provided skill management backend.
60
+ */
61
+ export interface SkillManageToolDeps {
62
+ /**
63
+ * Execute a skill management action.
64
+ * The host handles file system operations, validation, and security scanning.
65
+ */
66
+ manageSkill(params: SkillManageToolParams): Promise<SkillManageResult>;
67
+ /**
68
+ * Validate skill name format.
69
+ * If not provided, tool uses built-in validation.
70
+ */
71
+ validateName?(name: string): string | null;
72
+ }
73
+ export declare function createSkillManageTool(deps: SkillManageToolDeps): PortableTool<SkillManageToolParams>;
@@ -0,0 +1,37 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const SKILL_VIEW_TOOL_NAME: "skill_view";
3
+ export interface SkillViewToolParams {
4
+ name: string;
5
+ filePath?: string;
6
+ }
7
+ export declare const SKILL_VIEW_TOOL_SCHEMA: {
8
+ readonly type: "object";
9
+ readonly properties: {
10
+ readonly name: {
11
+ readonly type: "string";
12
+ readonly description: "Skill name to view (e.g. 'code-review', 'deploy-ecs').";
13
+ };
14
+ readonly filePath: {
15
+ readonly type: "string";
16
+ readonly description: string;
17
+ };
18
+ };
19
+ readonly required: readonly ["name"];
20
+ };
21
+ export interface SkillViewOutput {
22
+ name: string;
23
+ content: string;
24
+ referenceFiles?: string[];
25
+ tags?: string[];
26
+ }
27
+ /**
28
+ * Host-provided skill viewer.
29
+ */
30
+ export interface SkillViewToolDeps {
31
+ /**
32
+ * Read skill content. Returns the main SKILL.md or a specific file.
33
+ * Returns null if skill not found.
34
+ */
35
+ viewSkill(name: string, filePath?: string): Promise<SkillViewOutput | null>;
36
+ }
37
+ export declare function createSkillViewTool(deps: SkillViewToolDeps): PortableTool<SkillViewToolParams>;
@@ -0,0 +1,49 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const SLEEP_TOOL_NAME: "sleep";
3
+ export interface SleepToolParams {
4
+ /** Duration to sleep in seconds (1–3600). */
5
+ duration: number;
6
+ /** Reason for sleeping — helps the runtime decide whether to interrupt. */
7
+ reason?: string;
8
+ }
9
+ export declare const SLEEP_TOOL_SCHEMA: {
10
+ readonly type: "object";
11
+ readonly properties: {
12
+ readonly duration: {
13
+ readonly type: "number";
14
+ readonly description: "Duration to sleep in seconds (1–3600). Prefer short sleeps (10–60s) to stay responsive.";
15
+ readonly minimum: 1;
16
+ readonly maximum: 3600;
17
+ };
18
+ readonly reason: {
19
+ readonly type: "string";
20
+ readonly description: string;
21
+ };
22
+ };
23
+ readonly required: readonly ["duration"];
24
+ };
25
+ /** The result returned after a sleep completes or is interrupted. */
26
+ export interface SleepResult {
27
+ /** Actual time slept in seconds (may be less if interrupted). */
28
+ sleptSeconds: number;
29
+ /** Whether the sleep was interrupted before completing. */
30
+ interrupted: boolean;
31
+ /** The event that caused the interruption (undefined if not interrupted). */
32
+ interruptReason?: string;
33
+ }
34
+ /**
35
+ * Runtime dependencies injected by the host.
36
+ *
37
+ * The sleep mechanism is host-provided — the tool itself does NOT call
38
+ * setTimeout. The host decides how to implement the wait (timer, event loop
39
+ * integration, tick prompt scheduling, etc.).
40
+ */
41
+ export interface SleepToolDeps {
42
+ /**
43
+ * Perform the actual sleep. Must resolve after `durationMs` or when
44
+ * interrupted (whichever is first). The AbortSignal fires if the user
45
+ * or the system requests an interrupt.
46
+ */
47
+ sleep(durationMs: number, signal: AbortSignal): Promise<SleepResult>;
48
+ }
49
+ export declare function createSleepTool(deps: SleepToolDeps): PortableTool<SleepToolParams>;
@@ -0,0 +1,116 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const STRUCTURED_OUTPUT_TOOL_NAME: "structured_output";
3
+ /** Maximum content size for structured output results. */
4
+ export declare const STRUCTURED_OUTPUT_MAX_CHARS = 100000;
5
+ export interface StructuredOutputToolParams {
6
+ /** The structured data to return. Must conform to the session's output schema. */
7
+ data: Record<string, unknown>;
8
+ }
9
+ /**
10
+ * Base schema — accepts any object.
11
+ * When used with createConfiguredStructuredOutputTool, the host overrides
12
+ * this with the actual JSON Schema from `response_format.json_schema`.
13
+ */
14
+ export declare const STRUCTURED_OUTPUT_TOOL_SCHEMA: {
15
+ readonly type: "object";
16
+ readonly properties: {
17
+ readonly data: {
18
+ readonly type: "object";
19
+ readonly description: string;
20
+ readonly additionalProperties: true;
21
+ };
22
+ };
23
+ readonly required: readonly ["data"];
24
+ };
25
+ /** Schema validation error detail. */
26
+ export interface SchemaValidationError {
27
+ path: string;
28
+ message: string;
29
+ keyword?: string;
30
+ }
31
+ /** Result of structured output validation. */
32
+ export interface StructuredOutputResult {
33
+ valid: boolean;
34
+ errors?: SchemaValidationError[];
35
+ }
36
+ /**
37
+ * Whether the structured output tool should be enabled for this session.
38
+ * CC equivalent: `isSyntheticOutputToolEnabled`.
39
+ */
40
+ export declare function isStructuredOutputEnabled(opts: {
41
+ isNonInteractiveSession: boolean;
42
+ }): boolean;
43
+ /**
44
+ * Runtime dependencies injected by the host.
45
+ *
46
+ * The host provides:
47
+ * 1. The JSON Schema to validate against (from session config)
48
+ * 2. A validator function (host may use Ajv, Zod, or any validator)
49
+ * 3. An output sink to deliver the validated data
50
+ *
51
+ * The tool is only available in non-interactive (SDK/API) sessions
52
+ * where a `response_format.json_schema` has been specified.
53
+ */
54
+ export interface StructuredOutputToolDeps {
55
+ /**
56
+ * Get the JSON Schema that the output must conform to.
57
+ * Returns undefined if no schema is configured (tool should not be registered).
58
+ */
59
+ getOutputSchema(): Record<string, unknown> | undefined;
60
+ /**
61
+ * Validate data against the output schema.
62
+ * Returns { valid: true } or { valid: false, errors: [...] }.
63
+ */
64
+ validateOutput(data: Record<string, unknown>): StructuredOutputResult;
65
+ /**
66
+ * Deliver the validated output to the caller.
67
+ * Called only after successful validation.
68
+ */
69
+ deliverOutput(data: Record<string, unknown>): Promise<void>;
70
+ }
71
+ /**
72
+ * Create the base structured output tool with DI-based validation.
73
+ * This is the standard factory for runtime integration.
74
+ */
75
+ export declare function createStructuredOutputTool(deps: StructuredOutputToolDeps): PortableTool<StructuredOutputToolParams>;
76
+ /**
77
+ * Result of creating a configured structured output tool.
78
+ * Success: { tool } — ready-to-use tool with compiled schema.
79
+ * Failure: { error } — schema was invalid.
80
+ */
81
+ export type ConfiguredToolResult = {
82
+ tool: PortableTool<StructuredOutputToolParams>;
83
+ } | {
84
+ error: string;
85
+ };
86
+ /**
87
+ * Host-provided schema compilation interface.
88
+ * Allows the host to use any validator (Ajv, Zod, custom).
89
+ */
90
+ export interface SchemaCompiler {
91
+ /**
92
+ * Validate that the schema itself is a valid JSON Schema.
93
+ * Returns null if valid, or an error message string if invalid.
94
+ */
95
+ validateSchema(schema: Record<string, unknown>): string | null;
96
+ /**
97
+ * Compile the schema into a reusable validator function.
98
+ * Returns a function that validates data and returns StructuredOutputResult.
99
+ */
100
+ compile(schema: Record<string, unknown>): (data: Record<string, unknown>) => StructuredOutputResult;
101
+ }
102
+ /**
103
+ * Create a StructuredOutputTool configured with a specific JSON Schema.
104
+ * Mirrors CC's `createSyntheticOutputTool(jsonSchema)`.
105
+ *
106
+ * Features:
107
+ * - Validates the schema itself at creation time
108
+ * - Compiles the validator for reuse (cached via WeakMap)
109
+ * - Overrides the tool's `parameters` with the provided schema (dynamic input)
110
+ * - Returns { tool } on success or { error } if schema is invalid
111
+ *
112
+ * @param jsonSchema The JSON Schema to validate output against.
113
+ * @param compiler Schema compiler/validator provided by the host.
114
+ * @param deliver Output delivery function (called after successful validation).
115
+ */
116
+ export declare function createConfiguredStructuredOutputTool(jsonSchema: Record<string, unknown>, compiler: SchemaCompiler, deliver: (data: Record<string, unknown>) => Promise<void>): ConfiguredToolResult;
@@ -0,0 +1,104 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const TASK_TOOL_NAME: "task";
3
+ export type TaskAction = "create" | "get" | "list" | "output" | "stop";
4
+ export type TaskStatus = "pending" | "running" | "completed" | "failed" | "stopped";
5
+ export interface TaskToolParams {
6
+ action: TaskAction;
7
+ /** Task ID (required for get/output/stop) */
8
+ taskId?: string;
9
+ /** Task prompt (required for create) */
10
+ prompt?: string;
11
+ /** Short description (3-7 words, for create) */
12
+ description?: string;
13
+ /** Allowed tools for the background agent */
14
+ allowedTools?: string[];
15
+ /** Working directory for the task */
16
+ cwd?: string;
17
+ /** Model override for the task agent */
18
+ model?: string;
19
+ /** Max output lines to return (for output action, default 100) */
20
+ maxLines?: number;
21
+ }
22
+ export declare const TASK_TOOL_SCHEMA: {
23
+ readonly type: "object";
24
+ readonly properties: {
25
+ readonly action: {
26
+ readonly type: "string";
27
+ readonly enum: readonly ["create", "get", "list", "output", "stop"];
28
+ readonly description: string;
29
+ };
30
+ readonly taskId: {
31
+ readonly type: "string";
32
+ readonly description: "Task ID. Required for get/output/stop.";
33
+ };
34
+ readonly prompt: {
35
+ readonly type: "string";
36
+ readonly description: string;
37
+ };
38
+ readonly description: {
39
+ readonly type: "string";
40
+ readonly description: "Short (3-7 word) description of the task. Used for tracking and display.";
41
+ };
42
+ readonly allowedTools: {
43
+ readonly type: "array";
44
+ readonly items: {
45
+ readonly type: "string";
46
+ };
47
+ readonly description: "Restrict background agent to only these tools. If omitted, inherits parent's tools.";
48
+ };
49
+ readonly cwd: {
50
+ readonly type: "string";
51
+ readonly description: "Working directory for the background task (absolute path).";
52
+ };
53
+ readonly model: {
54
+ readonly type: "string";
55
+ readonly description: "Model override for the task agent (e.g. 'sonnet', 'opus').";
56
+ };
57
+ readonly maxLines: {
58
+ readonly type: "number";
59
+ readonly description: "Max output lines to return for the 'output' action (default: 100).";
60
+ readonly minimum: 1;
61
+ readonly maximum: 2000;
62
+ };
63
+ };
64
+ readonly required: readonly ["action"];
65
+ };
66
+ export interface TaskInfo {
67
+ taskId: string;
68
+ status: TaskStatus;
69
+ description?: string;
70
+ prompt?: string;
71
+ createdAt: number;
72
+ completedAt?: number;
73
+ result?: string;
74
+ error?: string;
75
+ }
76
+ export interface TaskResult {
77
+ success: boolean;
78
+ task?: TaskInfo;
79
+ tasks?: TaskInfo[];
80
+ output?: string;
81
+ error?: string;
82
+ }
83
+ /** Host-provided task management backend. */
84
+ export interface TaskToolDeps {
85
+ /** Create a new background agent task. Returns the created task info. */
86
+ createTask(params: {
87
+ prompt: string;
88
+ description?: string;
89
+ allowedTools?: string[];
90
+ cwd?: string;
91
+ model?: string;
92
+ }): Promise<TaskInfo>;
93
+ /** Get a task by ID. Returns null if not found. */
94
+ getTask(taskId: string): Promise<TaskInfo | null>;
95
+ /** List all tasks (optionally filtered by status). */
96
+ listTasks(filter?: {
97
+ status?: TaskStatus;
98
+ }): Promise<TaskInfo[]>;
99
+ /** Get output/logs from a task. */
100
+ getTaskOutput(taskId: string, maxLines?: number): Promise<string>;
101
+ /** Stop a running task. Returns true if stopped successfully. */
102
+ stopTask(taskId: string): Promise<boolean>;
103
+ }
104
+ export declare function createTaskTool(deps: TaskToolDeps): PortableTool<TaskToolParams>;
@@ -0,0 +1,89 @@
1
+ import type { PortableTool } from "../portable-tool.js";
2
+ export declare const TEAM_TOOL_NAME: "team";
3
+ export type TeamAction = "create" | "delete" | "list" | "status";
4
+ export interface TeamMember {
5
+ name: string;
6
+ role: string;
7
+ tools?: string[];
8
+ }
9
+ export interface TeamToolParams {
10
+ action: TeamAction;
11
+ /** Team name (required for create/delete) */
12
+ teamName?: string;
13
+ /** Team description */
14
+ description?: string;
15
+ /** Members to include (for create) */
16
+ members?: TeamMember[];
17
+ }
18
+ export declare const TEAM_TOOL_SCHEMA: {
19
+ readonly type: "object";
20
+ readonly properties: {
21
+ readonly action: {
22
+ readonly type: "string";
23
+ readonly enum: readonly ["create", "delete", "list", "status"];
24
+ readonly description: "Team action: create (new team), delete (disband), list (all teams), status (team details).";
25
+ };
26
+ readonly teamName: {
27
+ readonly type: "string";
28
+ readonly description: "Team name. Required for create/delete/status.";
29
+ };
30
+ readonly description: {
31
+ readonly type: "string";
32
+ readonly description: "Team description/objective. Used for create.";
33
+ };
34
+ readonly members: {
35
+ readonly type: "array";
36
+ readonly description: "Team members with roles and tool restrictions.";
37
+ readonly items: {
38
+ readonly type: "object";
39
+ readonly properties: {
40
+ readonly name: {
41
+ readonly type: "string";
42
+ readonly description: "Agent name/role identifier.";
43
+ };
44
+ readonly role: {
45
+ readonly type: "string";
46
+ readonly description: "Role description (e.g. 'frontend developer').";
47
+ };
48
+ readonly tools: {
49
+ readonly type: "array";
50
+ readonly items: {
51
+ readonly type: "string";
52
+ };
53
+ readonly description: "Allowed tools for this member.";
54
+ };
55
+ };
56
+ readonly required: readonly ["name", "role"];
57
+ };
58
+ };
59
+ };
60
+ readonly required: readonly ["action"];
61
+ };
62
+ export interface Team {
63
+ name: string;
64
+ description?: string;
65
+ leadId: string;
66
+ members: TeamMember[];
67
+ createdAt: string;
68
+ }
69
+ export interface TeamResult {
70
+ success: boolean;
71
+ team?: Team;
72
+ teams?: Team[];
73
+ error?: string;
74
+ }
75
+ /**
76
+ * Host-provided team management backend.
77
+ * Creates agent teams where members coordinate via send_message.
78
+ */
79
+ export interface TeamToolDeps {
80
+ createTeam(params: {
81
+ teamName: string;
82
+ description?: string;
83
+ members?: TeamMember[];
84
+ }): Promise<TeamResult>;
85
+ deleteTeam(teamName: string): Promise<TeamResult>;
86
+ listTeams(): Promise<TeamResult>;
87
+ getTeamStatus(teamName: string): Promise<TeamResult>;
88
+ }
89
+ export declare function createTeamTool(deps: TeamToolDeps): PortableTool<TeamToolParams>;