deepclause-sdk 0.0.89 → 0.1.0

package/dist/system/assets/docs/TUI.md

@@ -1,150 +0,0 @@
-# DeepClause TUI Guide
-
-## Overview
-
-Running `deepclause` with no subcommand starts the fullscreen CLI TUI.
-
-The TUI is the operator interface around a single built-in agent: the conductor.
-
-- The left pane shows sessions.
-- The center pane shows the conversation transcript.
-- The upper-right pane shows live execution activity.
-- The lower-right pane shows context, token usage, system asset sources, and shell execution details.
-
-The local `.deepclause/docs/` folder contains editable workspace docs such as `TUI.md` and `DML_REFERENCE.md`. The system `plan` skill reads `DML_REFERENCE.md` and `.deepclause/system/DML_COMPILER_PROMPT.md` before generating new plan files.
-
-## Command Bar
-
-The command bar accepts three main input styles plus direct skill execution:
-
-- Plain text sends a normal request to the conductor.
-- `/...` runs a built-in slash command.
-- `/<skill> [args]` runs a compiled local skill directly.
-- `/plan <request>` runs the system `plan` skill from `.deepclause/system/plan.dml`.
-- `/<plan> [args]` runs `plans/<plan>.dml` when no compiled local skill matches that name.
-- `/run <file> [args]` runs a workspace DML file directly.
-- `!<command>` runs a shell command directly in the configured workspace shell.
-
-Examples:
-
-```text
-summarize the latest test failures
-/sessions
-/set-model openai:gpt-4.1 --slot run
-/plan create a simple repo cleanup workflow
-/run plans/repo_cleanup.dml
-/compile create a skill that reviews changelogs
-/deep-research transformers scaling laws
-!git status
-!npm test
-```
-
-Use `\!text` if you need to send a normal conductor prompt that starts with a literal `!`.
-
-## Slash Commands
-
-Common built-in slash commands:
-
-- `/new [title]` creates a new conductor session.
-- `/sessions` refreshes or switches sessions.
-- `/set-model <model> [--slot <slot>]` updates the configured model for all slots or one slot.
-- `/plan <request>` runs the system plan skill and writes a simple standalone plan under `plans/`.
-- `/run <file> [args]` runs a workspace DML file directly.
-- `/compile <spec>` runs the skill creator.
-- `/skill-creator <spec>` is an alias for `/compile`.
-- `/cancel` aborts the current running task, skill, or shell command.
-- `/help` prints command help into the execution pane.
-- `/quit` or `/exit` closes the TUI.
-
-Any other `/name` is treated as a compiled skill invocation if that skill exists in the local catalog.
-If no compiled skill matches, the TUI looks for `plans/<name>.dml` and runs that file directly.
-
-## Direct Shell Mode
-
-`!<command>` is a TUI-local execution mode. It does not go through the conductor.
-
-- The shell command runs immediately.
-- Output streams live into the execution pane.
-- The process pane shows running state, PID when available, and host vs sandbox backend.
-- `/cancel` and `Ctrl+C` stop the running shell command.
-- The skill catalog refreshes after the shell command finishes, so newly created skills can appear without restarting the TUI.
-
-If the TUI is running with sandbox mode enabled, shell commands use the AgentVM sandbox instead of the host shell.
-
-## Menus and Palette
-
-The TUI includes a Borland-style menu bar and an action palette.
-
-- `F10` or `Ctrl+G` opens the menu bar.
-- `Ctrl+P` opens the action palette.
-- The Run menu includes prompt execution, shell command entry, repeat last command, cancellation, and skill catalog refresh.
-- The View menu can move focus between panes.
-- The Files and Skills menus open searchable pickers.
-
-## Navigation and Keys
-
-Important keys:
-
-- `Left` and `Right` switch the focused pane when the command bar is empty.
-- `Up` and `Down` select sessions or scroll the focused pane.
-- `PgUp` and `PgDn` page-scroll the focused pane.
-- `End` jumps back to the newest visible content.
-- `Tab` autocompletes slash commands and skill names.
-- `Ctrl+W` cycles focus across panes.
-
-## Execution Pane
-
-The execution pane is the main observability surface.
-
-It can show:
-
-- conductor streaming output
-- child-skill activity
-- tool lifecycle events
-- live shell stdout and stderr
-- active tool status, including PID when available
-
-This is where to look when a task seems stuck, is waiting for clarification, or is running shell or tool-heavy work.
-
-## Context Pane
-
-The context pane shows session and runtime state, including:
-
-- approximate context and token usage
-- resolved source paths for conductor and skill-creator DML/prompt assets
-- the active shell backend and shell working directory
-
-Changes to `.deepclause/system/` overrides are picked up on the next conductor turn or skill-creator run. A dedicated reload action is not required.
-
-## Sessions and Storage
-
-Each session lives under `.deepclause/sessions/<session-id>/`.
-
-Typical files include:
-
-- `metadata.json`
-- `messages.jsonl`
-- `assistant-memory.md`
-- `task-memory.md`
-- `usage.json`
-
-The TUI loads these sessions into the session list and shows their messages in the transcript pane.
-
-## Relationship to Skills
-
-The conductor is not the same thing as a compiled skill.
-
-- The conductor handles freeform user requests and orchestration.
-- Compiled skills are reusable DML workers in `.deepclause/tools/`.
-- The `plan` system skill lives at `.deepclause/system/plan.dml` and follows the same override model as the other system DML assets.
-- `/set-model` updates the configured gateway, run, and compile model selection for future turns, or only one slot when `--slot` is provided.
-- `/compile` and `/skill-creator` use the skill creator to turn a spec into a validated local skill.
-
-If a user asks how to automate something repeatedly, the right TUI workflow is usually to use `/compile <spec>` rather than repeating the same one-off prompt manually.
-
-## Troubleshooting
-
-- If a command appears to be stuck, check the execution pane for active tool status or a clarification request.
-- If shell commands do not behave as expected, check the context pane for the current shell backend and working directory.
-- If a newly created skill does not appear, refresh the skill catalog or run a new turn after the command completes.
-- If a system prompt or system DML change does not seem active, verify the source paths shown in the context pane.

package/dist/system/assets/recipes/deepclause-coding-workflow/SKILL.md

@@ -1,100 +0,0 @@
----
-name: DeepClause Coding Workflow
-description: Guidance for implementing and validating local repository changes in a DeepClause workspace.
-tags: [coding, repository, tests, docs, deepclause]
-when_to_use:
-  - tasks that require making specific changes to repository files with clear validation steps
-  - debugging and fixing a local behavior with focused edits and tests
-  - updating documentation to reflect code changes in the same commit
-  - work that is not intended to become a reusable DML skill but is still important to track and execute in a controlled way
-  - making focused code changes with clear validation steps
-  - implementing a feature or bug fix in the current repository
-  - updating tests and documentation alongside code changes
-  - debugging a local behavior before editing files
-when_not_to_use:
-  - purely informational web research
-  - work that should become a reusable executable skill instead of a one-off repo change
-globs: [src/**, tests/**, README.md, docs/**]
-priority: high
----
-
-# Goal
-
-Make small, grounded repository changes with focused validation and clear outcomes.
-
-# Workflow
-
-1. Start from a concrete anchor such as a failing test, a named file, a command, or the nearest implementation surface.
-2. Read only enough nearby code to form one falsifiable local hypothesis about what should change.
-3. Prefer the smallest edit that tests that hypothesis.
-4. Run the narrowest validation that can falsify the change before widening scope.
-5. If the validation fails, repair the same slice first instead of opening new work.
-6. Update documentation when behavior, workflow, or user-visible commands changed.
-
-# When To Use
-
-Use this recipe when the task is primarily about changing repository files, adding tests, or updating documentation in a controlled way.
-
-# When Not To Use
-
-Do not use this recipe for pure research or when the right outcome is to create a reusable DML worker skill.
-
-# Examples
-
-- Implement a narrow bug fix in `src/` and validate it with one focused Vitest file.
-- Update a CLI workflow and document the changed behavior in `README.md`.
-- Add a new config seed and verify it with the corresponding init tests.
-
-# Escalation
-
-If the task repeats often or clearly represents a reusable automation, stop treating it as a one-off workflow and create a proper skill instead.
-
-
-# Editing Protocol
-
-As a coding agent, you will navigate and modify files strictly using non-interactive Unix command-line utilities. You must execute edits precisely and safely, treating the filesystem as fragile. Never attempt to use interactive text editors like vim or nano.
-
-1. Core Editing Directives
-Context is Mandatory: Always read the target file or specific lines (using cat, head, tail, or sed -n) before applying changes. You must know exactly what you are modifying.
-
-Precision over Broadness: Never use loose regex that might accidentally match unintended parts of a file. Target specific line numbers or highly unique strings.
-
-Immediate Verification: Immediately verify your changes after an edit using git diff (if in a repository) or by re-reading the modified section to ensure the code didn't break.
-
-Quote Appropriately: Always escape special characters appropriately in your bash commands to prevent syntax errors or unintended variable expansions.
-
-2. Locating Context (grep & sed)
-Before editing, find the exact line numbers and context.
-
-Find line numbers: grep -n "target string" filename
-
-View surrounding context: grep -C 3 "target string" filename (Shows 3 lines before and after).
-
-View a specific line range: sed -n '10,25p' filename (Prints lines 10 through 25).
-
-3. Modifying Code (sed)
-Use sed for targeted in-place text replacement, deletion, or insertion. Always use the -i flag for in-place editing (Note: if the environment is macOS/BSD, you must use sed -i '').
-
-Targeted substitution (by line number): sed -i '42s/old_variable/new_variable/' filename
-
-Global substitution (with extreme caution): sed -i 's/old_string/new_string/g' filename
-
-Delete specific lines: sed -i '42,45d' filename (Deletes lines 42 through 45).
-
-Insert text after a specific line: sed -i '42a\    new_code_line();' filename
-
-4. Writing and Appending (bash & Heredocs)
-For generating new files, replacing entire files, or appending large multi-line blocks of code, avoid complex sed commands and use Bash redirects.
-
-Append a single line: echo "export DEBUG=true" >> filename
-
-Overwrite a file completely: echo "new content" > filename
-
-Write multi-line blocks (Heredocs): Use quoted heredocs ('EOF') to prevent the shell from accidentally evaluating variables like $1 or $VAR inside the code block you are writing.
-
-# Project Structure
-
-The workspace is the current PWD. All commands must be relative to this path. You have access to all files in the workspace, but you should only read and modify files relevant to the current task. Use git commands to check the status of the repository and ensure you are not making unintended changes.
-
-# Temporary files
-Do not use /tmp. Instead, create temporary files in a new .deepclause.tmp folder in the current workspace with unique names to avoid conflicts.

package/dist/system/assets/skills/conductor.dml

@@ -1,76 +0,0 @@
-% ============================================================================
-% Conductor (full tool set)
-% ============================================================================
-%
-% Has all tools: skills, bash, web, skill creation, etc.
-% Runs autonomously to complete the task described in its instructions.
-%
-% ============================================================================
-
-% --- Tool predicates (full tool set) ---
-
-tool(run_skill(Slug, Args, Result), "Run an existing skill. Slug is the skill slug (e.g. 'deep-research'). Args is a JSON array of string arguments. Returns the skill result.") :-
-
-    exec(run_skill(slug: Slug, args: Args), Result).
-
-tool(consult_recipes(Query, Result), "Search the recipe library for workflow guidance and conventions. Query is a natural-language description. Returns matching recipe metadata and content.") :-
-
-    exec(consult_recipes(query: Query, max_results: 3), Result).
-
-tool(search_web(Query, Results), "Search the web for current information. Returns search results.") :-
-    exec(web_search(query: Query), Results).
-
-tool(search_news(Query, Results), "Search recent news articles. Returns news results.") :-
-    exec(news_search(query: Query), Results).
-
-tool(fetch_url(Url, Content), "Fetch the content of a web page by URL. Returns the page body as text.") :-
-    exec(url_fetch(url: Url), Result),
-    get_dict(body, Result, Content).
-
-tool(download_file(Url, FilePath, Size), "Download a file from a URL and save it to disk. Returns the file path and size.") :-
-    exec(url_fetch(url: Url, save_to: FilePath), Result),
-    get_dict(file_path, Result, FilePath),
-    get_dict(size, Result, Size).
-
-tool(run_bash(Command, Output), "Run a shell command in the workspace.") :-
-    exec(bash(command: Command), Output).
-
-tool(create_new_skill(Spec, Result), "Create and deploy a new reusable skill from a natural language spec.") :-
-    exec(create_skill(spec: Spec), Result).
-
-tool(ask_user(Prompt, Response), "Ask the user a clarifying question and get their response.") :-
-    exec(ask_user(prompt: Prompt), Result),
-    get_dict(user_response, Result, Response).
-
-tool(inform_user(Message, Result), "Send a status update or progress report to the user.") :-
-    output(Message),
-    Result = "ok".
-
-% --- Main entry point ---
-
-agent_main(UserMessage) :-
-    param(system_prompt, "Conductor system prompt", SysPrompt),
-    system(SysPrompt),
-    system("When using bash or similar tools, avoid dumping large outputs directly into the conversation context. Write large or uncertain outputs to temporary files first, then inspect them with focused commands such as wc, grep, head, tail, sed, or similar narrow follow-up commands so the context stays small and relevant."),
-    format(string(TaskPrompt), "Task instructions: ~w\n\nComplete this task autonomously using your tools.\n\nIf you can complete the task, do so and report the result.\nIf you are blocked by a task-specific, tool-specific, external-service, environment, permission, dependency, or data issue that is not an LLM/provider/API/transport failure, do not go silent. Diagnose the blocker and explain clearly to the user why the task could not be completed.\nIf the problem appears to be an LLM/provider/API/transport failure, do not invent a speculative diagnosis.\n\nStore the user-facing response in FinalAnswer.\nStore the COMPLETE updated task memory markdown in MemoryUpdate only if this execution produced useful technical insights such as what worked, what failed, useful commands, error resolutions, or reusable lessons from a non-LLM task failure.\nIf nothing technically noteworthy should be recorded, store exactly NONE in MemoryUpdate.\nDo not call update_memory or any separate memory tool from this main task.\n\nReturn a good final answer in all non-LLM cases, including when the task is blocked.", [UserMessage]),
-    task(TaskPrompt, string(FinalAnswer), string(MemoryUpdate)),
-    maybe_update_session_memory(MemoryUpdate),
-    answer(FinalAnswer).
-
-% Fallback for technical failures where the main task itself cannot run to completion
-agent_main(_) :-
-    answer("Task failed. Please try again.").
-
-% Memory update is best-effort and uses the already-produced MemoryUpdate output.
-maybe_update_session_memory("NONE") :-
-    !.
-maybe_update_session_memory("none") :-
-    !.
-maybe_update_session_memory("ok") :-
-    !.
-maybe_update_session_memory("") :-
-    !.
-maybe_update_session_memory(Content) :-
-    catch(exec(update_memory(content: Content), _), _, true),
-    !.
-maybe_update_session_memory(_).