deepclause-sdk 0.0.59 → 0.0.61

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 (103) hide show
  1. package/README.md +326 -57
  2. package/dist/cli/compile.d.ts +9 -0
  3. package/dist/cli/compile.d.ts.map +1 -1
  4. package/dist/cli/compile.js +106 -138
  5. package/dist/cli/compile.js.map +1 -1
  6. package/dist/cli/config.d.ts +74 -23
  7. package/dist/cli/config.d.ts.map +1 -1
  8. package/dist/cli/config.js +162 -58
  9. package/dist/cli/config.js.map +1 -1
  10. package/dist/cli/default-skills.d.ts +9 -0
  11. package/dist/cli/default-skills.d.ts.map +1 -0
  12. package/dist/cli/default-skills.js +175 -0
  13. package/dist/cli/default-skills.js.map +1 -0
  14. package/dist/cli/index.js +79 -14
  15. package/dist/cli/index.js.map +1 -1
  16. package/dist/cli/interactive.d.ts +2 -0
  17. package/dist/cli/interactive.d.ts.map +1 -0
  18. package/dist/cli/interactive.js +20 -0
  19. package/dist/cli/interactive.js.map +1 -0
  20. package/dist/cli/prompt.d.ts +1 -19
  21. package/dist/cli/prompt.d.ts.map +1 -1
  22. package/dist/cli/prompt.js +1 -869
  23. package/dist/cli/prompt.js.map +1 -1
  24. package/dist/cli/run.d.ts +7 -1
  25. package/dist/cli/run.d.ts.map +1 -1
  26. package/dist/cli/run.js +79 -337
  27. package/dist/cli/run.js.map +1 -1
  28. package/dist/cli/search.d.ts +1 -0
  29. package/dist/cli/search.d.ts.map +1 -1
  30. package/dist/cli/search.js +10 -4
  31. package/dist/cli/search.js.map +1 -1
  32. package/dist/cli/tools.d.ts +2 -2
  33. package/dist/cli/tools.d.ts.map +1 -1
  34. package/dist/cli/tools.js +30 -5
  35. package/dist/cli/tools.js.map +1 -1
  36. package/dist/cli/tui.d.ts +83 -0
  37. package/dist/cli/tui.d.ts.map +1 -0
  38. package/dist/cli/tui.js +3552 -0
  39. package/dist/cli/tui.js.map +1 -0
  40. package/dist/compiler_prompt.d.ts +1 -1
  41. package/dist/compiler_prompt.d.ts.map +1 -1
  42. package/dist/compiler_prompt.js +8 -10
  43. package/dist/compiler_prompt.js.map +1 -1
  44. package/dist/prolog/bridge.js +1 -1
  45. package/dist/prolog/bridge.js.map +1 -1
  46. package/dist/runner.d.ts.map +1 -1
  47. package/dist/runner.js +5 -0
  48. package/dist/runner.js.map +1 -1
  49. package/dist/system/assets/docs/CONDUCTOR_PROMPT.md +46 -0
  50. package/dist/system/assets/docs/DML_COMPILER_PROMPT.md +664 -0
  51. package/dist/system/assets/index.d.ts +9 -0
  52. package/dist/system/assets/index.d.ts.map +1 -0
  53. package/dist/system/assets/index.js +47 -0
  54. package/dist/system/assets/index.js.map +1 -0
  55. package/dist/system/assets/skills/conductor.dml +70 -0
  56. package/dist/system/assets/skills/skill-creator.dml +186 -0
  57. package/dist/system/config/model-slots.d.ts +34 -0
  58. package/dist/system/config/model-slots.d.ts.map +1 -0
  59. package/dist/system/config/model-slots.js +121 -0
  60. package/dist/system/config/model-slots.js.map +1 -0
  61. package/dist/system/runtime/agentvm-manager.d.ts +18 -0
  62. package/dist/system/runtime/agentvm-manager.d.ts.map +1 -0
  63. package/dist/system/runtime/agentvm-manager.js +98 -0
  64. package/dist/system/runtime/agentvm-manager.js.map +1 -0
  65. package/dist/system/runtime/catalog-skills.d.ts +45 -0
  66. package/dist/system/runtime/catalog-skills.d.ts.map +1 -0
  67. package/dist/system/runtime/catalog-skills.js +110 -0
  68. package/dist/system/runtime/catalog-skills.js.map +1 -0
  69. package/dist/system/runtime/conductor.d.ts +68 -0
  70. package/dist/system/runtime/conductor.d.ts.map +1 -0
  71. package/dist/system/runtime/conductor.js +407 -0
  72. package/dist/system/runtime/conductor.js.map +1 -0
  73. package/dist/system/runtime/console-capture.d.ts +9 -0
  74. package/dist/system/runtime/console-capture.d.ts.map +1 -0
  75. package/dist/system/runtime/console-capture.js +67 -0
  76. package/dist/system/runtime/console-capture.js.map +1 -0
  77. package/dist/system/runtime/dml-executor.d.ts +49 -0
  78. package/dist/system/runtime/dml-executor.d.ts.map +1 -0
  79. package/dist/system/runtime/dml-executor.js +185 -0
  80. package/dist/system/runtime/dml-executor.js.map +1 -0
  81. package/dist/system/runtime/dml-params.d.ts +11 -0
  82. package/dist/system/runtime/dml-params.d.ts.map +1 -0
  83. package/dist/system/runtime/dml-params.js +45 -0
  84. package/dist/system/runtime/dml-params.js.map +1 -0
  85. package/dist/system/runtime/runtime-tools.d.ts +20 -0
  86. package/dist/system/runtime/runtime-tools.d.ts.map +1 -0
  87. package/dist/system/runtime/runtime-tools.js +170 -0
  88. package/dist/system/runtime/runtime-tools.js.map +1 -0
  89. package/dist/system/runtime/shell-manager.d.ts +20 -0
  90. package/dist/system/runtime/shell-manager.d.ts.map +1 -0
  91. package/dist/system/runtime/shell-manager.js +133 -0
  92. package/dist/system/runtime/shell-manager.js.map +1 -0
  93. package/dist/system/runtime/skill-creator.d.ts +33 -0
  94. package/dist/system/runtime/skill-creator.d.ts.map +1 -0
  95. package/dist/system/runtime/skill-creator.js +529 -0
  96. package/dist/system/runtime/skill-creator.js.map +1 -0
  97. package/dist/system/runtime/token-usage.d.ts +16 -0
  98. package/dist/system/runtime/token-usage.d.ts.map +1 -0
  99. package/dist/system/runtime/token-usage.js +45 -0
  100. package/dist/system/runtime/token-usage.js.map +1 -0
  101. package/dist/tools.js +1 -1
  102. package/dist/tools.js.map +1 -1
  103. package/package.json +4 -3
package/README.md CHANGED
@@ -1,8 +1,9 @@
1
- # DeepClause CLI and SDK
1
+ # DeepClause TUI Agent, CLI and SDK
2
2
 
3
- Compile markdown specs into executable logic programs. Guaranteed execution semantics for agentic workflows.
3
+ Compile markdown specs into executable logic programs. Guaranteed execution semantics for agentic workflows. Comes with a minimal coding agent incl. a nostalgic Borland-style TUI.
4
4
 
5
5
  ![docs/overview.png](docs/overview.png)
6
+ ![docs/tui.png](docs/tui.png)
6
7
 
7
8
 
8
9
  ## What This Is
@@ -16,14 +17,282 @@ DeepClause takes a different approach: **compile task descriptions into DML prog
16
17
  Markdown description → compile → Logic program → run → Output
17
18
  ```
18
19
 
19
- ## Sandboxed by Default
20
+ ## Install and Run
20
21
 
21
- Everything runs in WebAssembly—no native code execution, no container setup required:
22
+ DeepClause requires Node.js 18+.
22
23
 
23
- - **[AgentVM](https://github.com/deepclause/agentvm)**: A lightweight WASM-based Linux environment for shell commands, file operations, and Python/Node execution
24
- - **Prolog runtime**: The logic engine itself runs in WASM (SWI-Prolog compiled to WebAssembly)
24
+ ### Global install
25
25
 
26
- This means that DML tools and agents can execute arbitrary shell commands with minimal chance of escaping to your host system.
26
+ ```bash
27
+ npm install -g deepclause-sdk
28
+
29
+ # Pick one provider and export its API key
30
+ export OPENAI_API_KEY="sk-..."
31
+ # or: export ANTHROPIC_API_KEY="..."
32
+ # or: export GOOGLE_GENERATIVE_AI_API_KEY="..."
33
+ # or: export OPENROUTER_API_KEY="..."
34
+
35
+ # Initialize the current workspace
36
+ deepclause init --model openai:gpt-4o
37
+
38
+ # Inspect the configured slots
39
+ deepclause show-model
40
+
41
+ # Start the fullscreen conductor TUI
42
+ deepclause
43
+
44
+ # Or run one headless conductor turn
45
+ deepclause -p "Summarize the repository architecture"
46
+ ```
47
+
48
+ ### One-off usage with npx
49
+
50
+ ```bash
51
+ npx deepclause-sdk@latest init --model openai:gpt-4o
52
+ npx deepclause-sdk@latest show-model
53
+ npx deepclause-sdk@latest
54
+ ```
55
+
56
+ All commands except `init`, `help`, `--help`, `--version`, and `-V` expect a `.deepclause/` directory in the current workspace.
57
+
58
+ `deepclause init` creates:
59
+
60
+ - `.deepclause/config.json`
61
+ - `.deepclause/tools/`
62
+ - `.deepclause/.gitignore`
63
+ - seeded local skills: `deep-research` and `research-search-reader`
64
+
65
+ ## TUI Agent
66
+
67
+ Running `deepclause` with no subcommand starts the fullscreen TUI.
68
+
69
+ - Session list on the left
70
+ - Messages in the center
71
+ - Execution log and context summary on the right
72
+ - Slash commands such as `/new`, `/sessions`, `/compile <spec>`, `/skill-creator <spec>`, `/cancel`, and `/<skill> [args]`
73
+
74
+ For non-interactive use, `deepclause -p "..."` runs a single headless conductor turn with a fresh session.
75
+
76
+ ### Basic Structure
77
+
78
+ The TUI is the interface around a single built-in agent: the conductor.
79
+
80
+ - The TUI itself is just the UI shell: session browser, messages pane, execution log, and context view.
81
+ - The conductor is the actual agent that receives your prompt each turn and decides what to do.
82
+ - The conductor is implemented as a system DML skill plus a system prompt.
83
+ - The conductor can answer directly, call an existing local skill, invoke the skill creator to make a new skill, use shell tools, or do web research.
84
+
85
+ Conceptually, a TUI turn works like this:
86
+
87
+ 1. Load the current session from `.deepclause/sessions/<session-id>/`.
88
+ 2. Build the conductor prompt from the packaged conductor prompt template, the current skill catalog, assistant memory, task memory, and session transcript.
89
+ 3. Run the conductor DML with the `gateway` model slot.
90
+ 4. Stream the conductor's own activity and any child-skill events into the execution log on the right.
91
+ 5. Persist the final user/assistant messages and updated usage counters back into the session directory.
92
+
93
+ The conductor is the router and orchestrator for the CLI runtime. Normal compiled skills are the workers it delegates to. When the conductor launches a normal skill, that skill runs with the `run` model slot. When it launches the skill creator, that child run uses the `compile` model slot instead.
94
+
95
+ ### Memory Tools
96
+
97
+ The memory tools are there so the conductor can keep durable technical notes across turns instead of re-deriving everything from scratch every time.
98
+
99
+ - `messages.jsonl` is the conversation transcript. This is the raw history of user and assistant messages.
100
+ - `assistant-memory.md` is long-lived assistant context that gets injected into the conductor prompt each turn.
101
+ - `task-memory.md` is technical working memory: commands that worked, failure modes, local architecture notes, repair strategies, and other distilled learnings.
102
+
103
+ In the conductor DML, the LLM-facing tool is `save_memory`. That tool does not write arbitrary files directly. Instead, it calls the runtime tool `update_memory`, which replaces `task-memory.md` with the complete updated memory contents.
104
+
105
+ That distinction matters:
106
+
107
+ - use the transcript for exact conversation history
108
+ - use task memory for compressed technical learnings that should help future turns
109
+ - use assistant memory for stable higher-level context, tone, or persistent instructions
110
+
111
+ In the current CLI runtime, task memory is the main writable memory channel exposed to the conductor. Assistant memory is loaded and shown in the TUI, but it is not automatically updated by a built-in conductor tool in the same way.
112
+
113
+ ### Session and Memory Files
114
+
115
+ Each TUI session lives under `.deepclause/sessions/<session-id>/`:
116
+
117
+ ```text
118
+ .deepclause/
119
+ sessions/
120
+ <session-id>/
121
+ session.json
122
+ messages.jsonl
123
+ assistant-memory.md
124
+ task-memory.md
125
+ usage.json
126
+ specs/
127
+ ```
128
+
129
+ - `session.json` stores the session title and timestamps.
130
+ - `messages.jsonl` is the append-only user/assistant transcript that gets replayed into future conductor turns.
131
+ - `assistant-memory.md` is loaded into the conductor prompt as stable assistant context.
132
+ - `task-memory.md` is loaded into the conductor prompt as technical working memory.
133
+ - `usage.json` stores token usage summaries by model.
134
+ - `specs/` is used when the conductor invokes the skill creator and saves generated spec drafts for that session.
135
+
136
+ In the CLI runtime today, task memory is the actively updated memory channel: the conductor can call `save_memory`, which persists through `update_memory` into `task-memory.md`. `assistant-memory.md` is still loaded every turn, but it is primarily something you inspect or edit manually unless you build additional tooling around it.
137
+
138
+ ### Hacking the Conductor and Skill Creator
139
+
140
+ There are two levels of customization.
141
+
142
+ #### 1. Workspace-local system overrides
143
+
144
+ If you want to customize behavior for one workspace without modifying the package, place override DML files here:
145
+
146
+ - `.deepclause/system/conductor.dml`
147
+ - `.deepclause/system/skill-creator.dml`
148
+
149
+ When present, the CLI runtime prefers those files over the packaged system DML.
150
+
151
+ #### 2. Source-level hacking in this repository
152
+
153
+ If you are developing DeepClause itself, these are the main files to edit:
154
+
155
+ - `src/system/assets/skills/conductor.dml` - the conductor's DML logic
156
+ - `src/system/assets/skills/skill-creator.dml` - the skill creator's DML logic
157
+ - `src/system/assets/docs/CONDUCTOR_PROMPT.md` - the conductor system prompt template
158
+ - `src/system/assets/docs/DML_COMPILER_PROMPT.md` - the skill creator/compiler system prompt template
159
+ - `src/system/runtime/conductor.ts` - session loading, memory injection, tool registration, child-skill routing
160
+ - `src/system/runtime/skill-creator.ts` - compile-slot execution, skill-creator tool registration, validation/testing/deploy flow
161
+
162
+ Notes:
163
+
164
+ - The conductor uses the `gateway` model slot.
165
+ - Normal compiled skills use the `run` model slot.
166
+ - The skill creator uses the `compile` model slot.
167
+ - Prompt markdown files are packaged source assets. Unlike the DML files above, they are not currently loaded from `.deepclause/system/` workspace overrides.
168
+
169
+ After source-level changes, rebuild the package:
170
+
171
+ ```bash
172
+ npm install
173
+ npm run build
174
+ ```
175
+
176
+ If you want to run the CLI from a source checkout while hacking on it:
177
+
178
+ ```bash
179
+ npm install
180
+ npm run build
181
+ npm run cli -- init
182
+ npm run cli --
183
+ ```
184
+
185
+ ## Model and Provider Configuration
186
+
187
+ DeepClause separates model choice into three slots:
188
+
189
+ - `gateway` - conductor and orchestration turns
190
+ - `run` - compiled skill execution
191
+ - `compile` - skill compilation and `_skill-creator`
192
+
193
+ The canonical model id format is `provider:model`, but the CLI also accepts `provider/model` and, for common built-ins, bare model names that it can infer.
194
+
195
+ Example `.deepclause/config.json`:
196
+
197
+ ```json
198
+ {
199
+ "models": {
200
+ "gateway": "openai:gpt-4o",
201
+ "run": "openrouter:google/gemini-2.5-flash",
202
+ "compile": "anthropic:claude-sonnet-4-20250514"
203
+ },
204
+ "temperatures": {
205
+ "gateway": 0.7,
206
+ "run": 0.7,
207
+ "compile": 0.4
208
+ },
209
+ "providers": {
210
+ "openai": {
211
+ "apiKey": "${OPENAI_API_KEY}"
212
+ },
213
+ "anthropic": {
214
+ "apiKey": "${ANTHROPIC_API_KEY}"
215
+ },
216
+ "google": {
217
+ "apiKey": "${GOOGLE_GENERATIVE_AI_API_KEY}"
218
+ },
219
+ "openrouter": {
220
+ "apiKey": "${OPENROUTER_API_KEY}",
221
+ "baseUrl": "https://openrouter.ai/api/v1"
222
+ }
223
+ },
224
+ "agentvm": {
225
+ "network": false
226
+ },
227
+ "workspace": "./workspace",
228
+ "dmlBase": ".deepclause/tools"
229
+ }
230
+ ```
231
+
232
+ Configuration values support `${ENV_VAR}` and `$ENV_VAR` interpolation.
233
+
234
+ ### Setting Models from the CLI
235
+
236
+ ```bash
237
+ # Update all three slots
238
+ deepclause set-model openai:gpt-4o
239
+
240
+ # Only change the compile slot
241
+ deepclause set-model anthropic:claude-sonnet-4-20250514 --slot compile
242
+
243
+ # Use OpenRouter for the conductor only
244
+ deepclause set-model openrouter:google/gemini-2.5-flash --slot gateway
245
+
246
+ # Inspect the resolved slot values
247
+ deepclause show-model
248
+ ```
249
+
250
+ ### Provider Notes
251
+
252
+ | Provider | Canonical example | API key env var | Notes |
253
+ |----------|-------------------|-----------------|-------|
254
+ | OpenAI | `openai:gpt-4o` | `OPENAI_API_KEY` | You can also set `providers.openai.baseUrl` for an OpenAI-compatible endpoint. |
255
+ | Anthropic | `anthropic:claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` | Native Anthropic adapter. |
256
+ | Google | `google:gemini-2.5-flash` | `GOOGLE_GENERATIVE_AI_API_KEY` | Native Google Generative AI adapter. |
257
+ | OpenRouter | `openrouter:anthropic/claude-sonnet-4` | `OPENROUTER_API_KEY` | Use any OpenRouter model path. |
258
+ | Custom | `custom:local:qwen3-32b` | `LLM_PROVIDER_LOCAL_API_KEY` | Uses the OpenAI-compatible transport with a custom base URL. |
259
+
260
+ ### Custom Provider
261
+
262
+ `custom:` is for OpenAI-compatible endpoints that you want to name explicitly instead of pretending they are one of the built-in providers.
263
+
264
+ Format:
265
+
266
+ ```text
267
+ custom:<provider-name>:<model-name>
268
+ ```
269
+
270
+ Example:
271
+
272
+ ```bash
273
+ export LLM_PROVIDER_LOCAL_BASE_URL="http://localhost:11434/v1"
274
+ export LLM_PROVIDER_LOCAL_API_KEY="dummy"
275
+
276
+ deepclause set-model custom:local:qwen3-32b --slot run
277
+ deepclause show-model
278
+ ```
279
+
280
+ Notes:
281
+
282
+ - `custom:local:qwen3-32b` reads `LLM_PROVIDER_LOCAL_BASE_URL` and `LLM_PROVIDER_LOCAL_API_KEY`.
283
+ - The provider name is uppercased and normalized when constructing env vars, so `custom:my-lab:model-x` becomes `LLM_PROVIDER_MY_LAB_BASE_URL` and `LLM_PROVIDER_MY_LAB_API_KEY`.
284
+ - `custom:` providers are not configured under the `providers` object in `config.json`; they are resolved from env vars.
285
+ - Internally, `custom:` uses the OpenAI-compatible transport, so your endpoint must speak an OpenAI-style chat/completions API.
286
+
287
+ ## Runtime Model
288
+
289
+ DeepClause executes DML in a local CLI runtime:
290
+
291
+ - **Prolog runtime in WASM**: The DML logic engine runs in SWI-Prolog compiled to WebAssembly.
292
+ - **Host shell by default**: Shell tools run in the active local workspace shell.
293
+ - **AgentVM on demand**: Pass `--sandbox` when you want shell tools to run inside [AgentVM](https://github.com/deepclause/agentvm) instead.
294
+
295
+ This keeps the default workflow simple for local development while still supporting an isolated shell backend when needed.
27
296
 
28
297
  ## Beyond Markdown: Why Logic Programming?
29
298
 
@@ -87,21 +356,9 @@ agent_main(SpecUrl) :-
87
356
 
88
357
  Unlike traditional SDD where specs guide but don't control, DeepClause specs **become** the executable. The spec *is* the code—just at a higher abstraction level.
89
358
 
90
- ## Quick Start
359
+ ## Compile and Run a Skill
91
360
 
92
361
  ```bash
93
- # Install
94
- npm install -g deepclause-sdk
95
-
96
- # Set API key (or ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc.)
97
- export OPENAI_API_KEY="sk-..."
98
-
99
- # Initialize in your project
100
- deepclause init
101
-
102
- # Configure the model for compilation
103
- deepclause set-model openai/gpt-4o
104
-
105
362
  # Create a task description
106
363
  cat > .deepclause/tools/explain.md << 'EOF'
107
364
  # Code Explainer
@@ -122,6 +379,10 @@ deepclause compile .deepclause/tools/explain.md
122
379
 
123
380
  # Run it
124
381
  deepclause run .deepclause/tools/explain.dml "function fib(n) { return n < 2 ? n : fib(n-1) + fib(n-2) }"
382
+
383
+ # Or trigger skill creation directly from the TUI with:
384
+ # /compile <spec>
385
+ # /skill-creator <spec>
125
386
  ```
126
387
 
127
388
  ## Use Cases
@@ -227,18 +488,22 @@ Analyze a CSV file and describe its contents.
227
488
 
228
489
  ## Available Tools
229
490
 
230
- Skills can use these built-in tools:
491
+ Common built-in runtime tools:
231
492
 
232
493
  | Tool | Description |
233
494
  |------|-------------|
234
- | `web_search` | Search the web (requires `BRAVE_API_KEY`) |
495
+ | `web_search` | Search the web using Brave Search (requires `BRAVE_API_KEY`) |
235
496
  | `news_search` | Search recent news |
236
- | `vm_exec` | Run shell commands in a sandbox |
237
- | `ask_user` | Prompt the user for input |
497
+ | `url_fetch` | Fetch a URL or save it into the workspace |
498
+ | `bash` | Run shell commands in the active workspace shell |
499
+ | `vm_exec` | Alias of `bash`; with `--sandbox`, runs in AgentVM |
500
+
501
+ Some tools are runtime-role specific rather than globally available to every skill. For example:
238
502
 
239
- Configure tools in `.deepclause/config.json`.
503
+ - the conductor adds tools such as `run_skill`, `create_skill`, and `update_memory`
504
+ - the skill creator adds tools such as `list_skills`, `write_file`, `validate_dml`, `test_dml`, and `deploy_skill`
240
505
 
241
- MCP support is on the roadmap.
506
+ Additional tools can come from configured MCP servers. Use `deepclause list-tools` to see the built-ins plus anything exposed by your configured MCP servers.
242
507
 
243
508
  ## CLI Reference
244
509
 
@@ -247,55 +512,59 @@ deepclause init # Set up .deepclause/ folder
247
512
  deepclause compile <file.md> # Compile Markdown to DML
248
513
  deepclause compile-all <dir> # Compile all .md files in directory
249
514
  deepclause run <file.dml> [args] # Execute a compiled skill
515
+ deepclause # Start the interactive conductor TUI
516
+ deepclause -p <text> # Run one headless conductor turn
250
517
  deepclause list-commands # List available compiled skills
251
518
  deepclause list-tools # Show available tools
252
- deepclause set-model <model> # Change default model
519
+ deepclause show-model # Show gateway/run/compile slots
520
+ deepclause set-model <model> # Change all slots or one slot with --slot
253
521
  ```
254
522
 
255
523
  ### Run Options
256
524
 
257
525
  ```bash
258
526
  deepclause run skill.dml "input" \
259
- --model google/gemini-2.5-flash \ # Override model (e.g. use cheaper model for execution, SOTA model for planning/compilation)
260
- --stream \ # Stream output
261
- --verbose \ # Show tool calls
262
- --workspace ./data # Set working directory
527
+ --model google:gemini-2.5-flash \ # Override the run model for this execution
528
+ --stream \ # Stream output
529
+ --verbose \ # Show tool calls
530
+ --workspace ./data \ # Set working directory
531
+ --sandbox # Use AgentVM instead of the local shell
263
532
  ```
264
533
 
265
534
  ## Configuration
266
535
 
267
- `.deepclause/config.json`:
268
- ```json
269
- {
270
- "model": "gpt-4o",
271
- "provider": "openai",
272
- "agentvm": { "network": true }
273
- }
274
- ```
536
+ The main configuration surface is `.deepclause/config.json`.
275
537
 
276
- ### Model at Compile Time vs Run Time
538
+ The most important fields are covered above in:
277
539
 
278
- The model specified in `config.json` (or via `--model`) is used during **compilation** to generate the DML program. At **run time**, you can use a different model:
540
+ - [Install and Run](#install-and-run)
541
+ - [TUI Conductor](#tui-conductor)
542
+ - [Model and Provider Configuration](#model-and-provider-configuration)
279
543
 
280
- ```bash
281
- # Compile with GPT-4o (better at understanding intent)
282
- deepclause set-model openai/gpt-4o
283
- deepclause compile research.md
544
+ Other useful config fields:
284
545
 
285
- # Run with a faster/cheaper model
286
- deepclause run research.dml "quantum computing" --model google/gemini-2.5-flash
546
+ ```json
547
+ {
548
+ "agentvm": {
549
+ "network": false
550
+ },
551
+ "workspace": "./workspace",
552
+ "dmlBase": ".deepclause/tools",
553
+ "mcp": {
554
+ "servers": {
555
+ "filesystem": {
556
+ "command": "npx",
557
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
558
+ }
559
+ }
560
+ }
561
+ }
287
562
  ```
288
563
 
289
- This lets you use a more capable model for the one-time compilation step, then execute with a faster or cheaper model for repeated runs.
290
-
291
- ### Supported Models
292
-
293
- | Provider | Models |
294
- |----------|--------|
295
- | OpenAI | `gpt-4o`, `gpt-4o-mini`, `o1`, `o3-mini` |
296
- | Anthropic | `claude-sonnet-4-20250514`, `claude-3-5-sonnet-20241022` |
297
- | Google | `gemini-2.5-pro`, `gemini-2.5-flash` |
298
- | OpenRouter | Any model via `openrouter/provider/model` |
564
+ - `agentvm.network` controls whether shell commands in `--sandbox` mode get outbound network access.
565
+ - `workspace` sets the default working directory used by shell/file tools.
566
+ - `dmlBase` changes where compiled local skills are written.
567
+ - `mcp.servers` registers MCP servers that then appear in `deepclause list-tools`.
299
568
 
300
569
  ## Understanding DML
301
570
 
@@ -5,9 +5,11 @@
5
5
  * with LLM generation and Prolog validation.
6
6
  */
7
7
  import { type Provider } from './config.js';
8
+ import { extractDescription as extractDescriptionFromCompiler, extractParameters as extractParametersFromCompiler, extractToolDependencies as extractToolDependenciesFromCompiler } from '../compiler.js';
8
9
  export interface CompileOptions {
9
10
  force?: boolean;
10
11
  validateOnly?: boolean;
12
+ sandbox?: boolean;
11
13
  model?: string;
12
14
  provider?: Provider;
13
15
  temperature?: number;
@@ -74,4 +76,11 @@ export declare function compilePrompt(prompt: string, options?: CompileOptions):
74
76
  dml: string;
75
77
  tools: string[];
76
78
  }>;
79
+ export declare const extractToolDependencies: typeof extractToolDependenciesFromCompiler;
80
+ export declare const extractParameters: typeof extractParametersFromCompiler;
81
+ export declare const extractDescription: typeof extractDescriptionFromCompiler;
82
+ export declare function validateDMLSyntax(dml: string): {
83
+ valid: boolean;
84
+ errors: string[];
85
+ };
77
86
  //# sourceMappingURL=compile.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAYrE,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CACJ;AA+DD;;GAEG;AACH,wBAAsB,OAAO,CAC3B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA2LxB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CA8C3B;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwB3C"}
1
+ {"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"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"}