deepclause-pi 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepClause
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# DeepClause for pi
+
+Run [DeepClause](https://github.com/deepclause/deepclause-sdk) DML programs inside [pi](https://github.com/badlogic/pi-mono).
+
+DeepClause for pi is a runtime-only integration. Pi supplies the selected model, existing credentials, active session context, terminal UI, cancellation, and usage accounting. DeepClause supplies deterministic DML execution, Prolog constraints, task orchestration, backtracking, and a deliberately small runtime-tool boundary.
+
+## Requirements
+
+- Node.js 22 or newer
+- pi 0.84 or newer
+- A model configured and selected in pi
+- `curl` for the bundled deep-research example
+
+The extension does not request API keys or modify provider environment variables.
+
+## Install
+
+Install directly from GitHub:
+
+```sh
+pi install git:github.com/deepclause/deepclause-pi
+```
+
+For a project-local installation:
+
+```sh
+pi install git:github.com/deepclause/deepclause-pi -l
+```
+
+Restart pi after installation. Run `/dc` to initialize the current workspace and verify the active model and runtime status.
+
+For a project-local (`-l`) installation, start pi from the directory containing `.pi/settings.json`. Pi does not discover a project package from a parent directory when launched inside a nested subdirectory. The startup screen should list DeepClause under **Extensions** and `/dc-run` should appear in slash-command completion. If the extension is absent, an input beginning with `/dc-run` is forwarded to the model as ordinary text instead of executing the command.
+
+To try an unpublished checkout during development:
+
+```sh
+pi -e ./deepclause-pi/src/index.ts
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/dc` | Initialize the workspace non-destructively and show help, model, paths, and status. |
+| `/dc-list` | List authored skills and generated plans. |
+| `/dc-plan <request> [--name=slug]` | Create a validated executable DML plan using pi's current context, skills, and active tools. |
+| `/dc-run <skill> [args]` | Run a named skill such as `example` or `deep_research`. |
+| `/dc-run <path> [args]` | Run a DML file below `.pi/deepclause/`. |
+| `/dc-tool enable\|disable\|status` | Control the default-off `dc_run` tool callable by pi's model. |
+| `/dc-cancel` | Cancel the active DeepClause execution. |
+
+Run options:
+
+- `--context=turn|branch|isolated` overrides session-context import for one run.
+- `--verbose` or `-v` displays lifecycle events.
+- `--debug` or `-d` displays complete event payloads and SDK model diagnostics.
+
+Examples:
+
+```text
+/dc-run example --debug
+/dc-run deep_research "What are the practical impacts of small language models?" --verbose
+/dc-run skills/my_skill.dml "first argument" --context=isolated
+/dc-plan inspect this repository and propose a safe ESM migration --name=esm-migration
+/dc-run plans/esm_migration.dml
+```
+
+## Workspace layout
+
+The first `/dc` or `/dc-run` creates missing files under the active workspace:
+
+```text
+.pi/deepclause/
+├── config.json
+├── AGENTS.md
+├── DML_REFERENCE.md
+├── skills/
+│   ├── example.dml
+│   └── deep_research.dml
+└── plans/
+```
+
+Existing files are never overwritten silently. The extension neither creates nor reads `.deepclause/`.
+
+`AGENTS.md` teaches pi how to author and conservatively edit DML. `DML_REFERENCE.md` is the bundled language/runtime reference. Add user-maintained programs to `skills/`; `/dc-plan` writes generated executable programs to `plans/`. Pi can edit either with its normal coding tools.
+
+## Session context
+
+Configure the default mode in `.pi/deepclause/config.json`:
+
+```json
+{
+  "version": 1,
+  "contextMode": "turn",
+  "branchMessageLimit": 20,
+  "gasLimit": 100000,
+  "maxTokens": 16384,
+    "verbose": false,
+    "modelToolEnabled": false
+}
+```
+
+- `turn` imports the current request and relevant immediate context. This is the default.
+- `branch` imports a bounded set of messages from the active pi branch, including compacted history.
+- `isolated` imports no pi conversation.
+
+Pi remains the sole persistent session owner. Executions stop when their pi session closes or changes, and results are rendered into the current session.
+
+## Opt-in model tool
+
+The model-callable `dc_run` tool is disabled by default. Enable it explicitly for the current workspace:
+
+```text
+/dc-tool enable
+```
+
+The change takes effect immediately and persists in `.pi/deepclause/config.json`; no reload is required. Use `/dc-tool status` to inspect it and `/dc-tool disable` to remove it from pi's active tools.
+
+When active, pi can call `dc_run` with an existing `skill`, optional positional `args`, and an optional `turn`, `branch`, or `isolated` context override. The tool reuses the same path isolation, active model, cancellation, session context, events, and runtime policy as `/dc-run`. It rejects concurrent execution, cannot compile natural language into DML, and cannot escape `.pi/deepclause/`. Any DML request for `pi_bash` still requires explicit user approval.
+
+Contextual plans containing `pi_agent_step` cannot be invoked through `dc_run`. They must be started explicitly by the user with `/dc-run`, which displays a confirmation first.
+
+## Contextual executable plans
+
+`/dc-plan` starts a normal pi agent turn. The planner can inspect the workspace and account for project instructions, loaded skills, the selected model, and currently active built-in or extension tools. It does not ask the model to emit raw DML. Instead, a transaction-scoped `dc_plan_commit` tool accepts a typed plan specification; the extension validates it, deterministically assembles DML, validates the generated program with the SDK parser, previews it for confirmation, and writes it without overwriting an existing plan.
+
+The resulting `.dml` file is the plan. Steps use one of two executors:
+
+- `dml` — contained reasoning through ordinary typed DML tasks.
+- `pi` — a bounded `pi_agent_step` that runs as a normal pi turn with current session context and loaded skills.
+
+For each pi step, only the exact tools named in the committed plan are temporarily active. They must still be installed and active when execution begins; existing tool policies, UI, and approvals remain authoritative. DeepClause control tools cannot be requested recursively. The prior active-tool set is restored after success, failure, or cancellation.
+
+## Runtime tools and approval
+
+The extension never exposes pi's general tool registry directly to ordinary DML. The optional `dc_run` tool runs an existing DML program; inside that runtime, only these host operations are registered:
+
+- `pi_workspace_list(RelativePath)` — read-only, one-level workspace listing. Absolute paths, traversal, and resolved symlink escapes are rejected.
+- `pi_bash(Command)` — runs an explicitly approved shell command in the active workspace.
+- `pi_bash(Executable, Args)` — runs an explicitly approved executable with a separate argv list, avoiding shell interpolation.
+
+Every `pi_bash` call has a 60-second timeout, inherits cancellation, and is denied when interactive approval is unavailable.
+
+User-approved contextual plans additionally receive the internal `pi_agent_step` bridge. That bridge delegates a bounded instruction to a normal pi turn rather than invoking arbitrary tools itself, preserving policies from pi and other extensions.
+
+DML can wrap these runtime operations in higher-level tool predicates. It can also wrap the SDK's internal `ask_user` operation. During `/dc-run`, `ask_user` opens pi's native, cancellable input UI and returns the response to the DML task loop.
+
+```prolog
+tool(user_feedback(Prompt, Response), "Ask the user for feedback") :-
+    exec(ask_user(prompt: Prompt), Result),
+    get_dict(user_response, Result, Response).
+
+tool(bing_search(Query, Results), "Search Bing RSS with curl") :-
+    format(string(QueryArg), "q=~w", [Query]),
+    exec(pi_bash("curl", [
+        "--fail", "--silent", "--show-error", "--location", "--get",
+        "--data-urlencode", QueryArg,
+        "https://www.bing.com/search?format=rss&count=8"
+    ]), Result),
+    get_dict(stdout, Result, Results).
+```
+
+DML predicates remain visible to `task/N` agent loops, while their nested `exec/2` calls are still checked against the host runtime whitelist.
+
+## Bundled examples
+
+### `example.dml`
+
+Demonstrates:
+
+- CLP(FD) constraint solving
+- Read-only workspace listing
+- Approval-gated bash execution
+- Typed task output through pi's active model
+- Runtime progress, tool, usage, and answer events
+
+Run `/dc-run example --debug` and approve the harmless displayed `printf` command.
+
+### `deep_research.dml`
+
+Demonstrates model-callable DML tool predicates:
+
+1. The model creates three focused research queries.
+2. `user_feedback/2` presents the plan through pi's input UI.
+3. The model revises or accepts the plan.
+4. `bing_search/2` invokes approved `curl` requests against Bing RSS.
+5. The model synthesizes a cited Markdown report from the returned result snippets.
+
+The example does not use SDK web search, URL fetch, file writing, or unrestricted pi tools. Each curl request requires explicit approval.
+
+## Event presentation
+
+Every run displays a live panel containing the skill, active model, context mode, elapsed time, phase, output, recent events, and token usage. Runtime events map into pi as follows:
+
+- `task_activity` → progress
+- `stream` → model text
+- `tool_call` → tool activity
+- `input_required` → native pi input prompt
+- `usage` → usage totals
+- `answer` → command result
+- `error` → concise error notification
+
+The SDK supports incremental text callbacks inside `task/N`. The current pi adapter uses pi's completion API, so model text presently arrives as one completed stream chunk; task, tool, input, and usage events remain live.
+
+## Authoring a skill
+
+New workspaces receive a comprehensive `.pi/deepclause/AGENTS.md` authoring guide distilled from the SDK language reference, runtime implementation, examples, compiler prompts, and planning benchmarks. It teaches pi to design DML as deterministic Prolog orchestration around typed model tasks, narrow tools, explicit progress, constraints, and safe fallback.
+
+The evidence and design decisions behind it are recorded in [docs/AUTHORING_GUIDE_ANALYSIS.md](docs/AUTHORING_GUIDE_ANALYSIS.md).
+
+The design and security rationale for `/dc-plan` are recorded in [docs/DC_PLAN_PROPOSAL.md](docs/DC_PLAN_PROPOSAL.md).
+
+The guide covers:
+
+- `agent_main/0` through `agent_main/3`, typed `task/N` and isolated `prompt/N`
+- memory, interpolation, dicts, model-callable DML tools, and pi's restricted host tools
+- backtracking, CLP constraints, failure handling, command approval, and validation workflow
+- architecture patterns for research, constrained planning, workspace engineering, compliance gates, interactive expert systems, data pipelines, and generate-review-repair workflows
+
+A minimal skill accepts one slash-command argument:
+
+```prolog
+agent_main(Topic) :-
+    system("You are a concise analyst."),
+    format(string(Request), "Explain ~w and store the final text in Summary.", [Topic]),
+    task(Request, string(Summary)),
+    answer(Summary).
+```
+
+Before creating or modifying DML, consult `.pi/deepclause/AGENTS.md` and `.pi/deepclause/DML_REFERENCE.md`. DeepClause compilation is intentionally unavailable in this integration; authored content must already be valid DML.
+
+## Development
+
+```sh
+git clone https://github.com/deepclause/deepclause-pi.git
+cd deepclause-pi
+npm install
+npm run check
+```
+
+The package depends on `deepclause-sdk` 0.0.87 and uses pi packages as peer dependencies. The source extension entry point is declared in the `pi.extensions` package field, matching pi's TypeScript extension-loading convention.
+
+## Scope
+
+- No Markdown-to-DML compiler
+- No dynamic per-skill slash commands
+- No independent DeepClause session or execution-log store
+- No direct DML access to pi's full tool registry
+- No model-callable execution unless the user enables `dc_run` for the workspace
+- No silent mutation of user files
+- No workspace path escape
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export type ContextMode = "turn" | "branch" | "isolated";
+export interface DeepClauseConfig {
+    version: 1;
+    contextMode: ContextMode;
+    branchMessageLimit: number;
+    gasLimit: number;
+    maxTokens: number;
+    verbose: boolean;
+    modelToolEnabled: boolean;
+}
+export declare const DEFAULT_CONFIG: DeepClauseConfig;
+export declare function loadConfig(path: string): Promise<DeepClauseConfig>;
+export declare function setModelToolEnabled(configPath: string, enabled: boolean): Promise<DeepClauseConfig>;

package/dist/config.js

@@ -0,0 +1,59 @@
+import { readFile, writeFile } from "node:fs/promises";
+export const DEFAULT_CONFIG = {
+    version: 1,
+    contextMode: "turn",
+    branchMessageLimit: 20,
+    gasLimit: 100_000,
+    maxTokens: 16_384,
+    verbose: false,
+    modelToolEnabled: false,
+};
+const isContextMode = (value) => value === "turn" || value === "branch" || value === "isolated";
+export async function loadConfig(path) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return DEFAULT_CONFIG;
+        throw new Error(`Invalid DeepClause config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!value || typeof value !== "object")
+        throw new Error("DeepClause config must be a JSON object");
+    const config = value;
+    const contextMode = config.contextMode ?? DEFAULT_CONFIG.contextMode;
+    if (!isContextMode(contextMode))
+        throw new Error("contextMode must be turn, branch, or isolated");
+    const positiveInteger = (key, fallback) => {
+        const candidate = config[key] ?? fallback;
+        if (!Number.isInteger(candidate) || Number(candidate) <= 0) {
+            throw new Error(`${key} must be a positive integer`);
+        }
+        return Number(candidate);
+    };
+    return {
+        version: 1,
+        contextMode,
+        branchMessageLimit: positiveInteger("branchMessageLimit", DEFAULT_CONFIG.branchMessageLimit),
+        gasLimit: positiveInteger("gasLimit", DEFAULT_CONFIG.gasLimit),
+        maxTokens: positiveInteger("maxTokens", DEFAULT_CONFIG.maxTokens),
+        verbose: config.verbose === true,
+        modelToolEnabled: config.modelToolEnabled === true,
+    };
+}
+export async function setModelToolEnabled(configPath, enabled) {
+    let existing = {};
+    try {
+        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new Error(`Invalid DeepClause config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    await writeFile(configPath, `${JSON.stringify({ ...existing, modelToolEnabled: enabled }, null, 2)}\n`, "utf8");
+    return loadConfig(configPath);
+}

package/dist/context.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryMessage } from "deepclause-sdk";
+import type { ContextMode } from "./config.js";
+export declare function buildInitialMessages(entries: readonly unknown[], mode: ContextMode, branchMessageLimit: number): MemoryMessage[];

package/dist/context.js

@@ -0,0 +1,38 @@
+function textContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((block) => Boolean(block) && typeof block === "object")
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n");
+}
+function entryToMessage(entry) {
+    if (entry.type === "compaction" && typeof entry.summary === "string") {
+        return { role: "system", content: `Compacted pi session context:\n${entry.summary}` };
+    }
+    if (entry.type !== "message" || !entry.message)
+        return undefined;
+    if (entry.message.role !== "user" && entry.message.role !== "assistant")
+        return undefined;
+    const content = textContent(entry.message.content).trim();
+    return content ? { role: entry.message.role, content } : undefined;
+}
+export function buildInitialMessages(entries, mode, branchMessageLimit) {
+    if (mode === "isolated")
+        return [];
+    const messages = entries
+        .map(entryToMessage)
+        .filter((message) => message !== undefined);
+    if (mode === "branch")
+        return messages.slice(-branchMessageLimit);
+    const immediate = [];
+    for (let index = messages.length - 1; index >= 0 && immediate.length < 2; index--) {
+        const message = messages[index];
+        if (message)
+            immediate.unshift(message);
+    }
+    return immediate;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ContextMode } from "./config.js";
+export interface ParsedRun {
+    target: string;
+    args: string[];
+    contextMode?: ContextMode;
+    verbose: boolean;
+    debug: boolean;
+}
+interface ParsedPlan {
+    request: string;
+    name?: string;
+    debug: boolean;
+}
+export declare function splitArguments(input: string): string[];
+export declare function parseRun(input: string): ParsedRun;
+export declare function parsePlan(input: string): ParsedPlan;
+export default function deepClauseExtension(pi: ExtensionAPI): void;
+export {};