raga-cli 0.0.0-stage → 0.8.0

package/examples/sdk/13-session-runtime.ts

@@ -0,0 +1,67 @@
+/**
+ * Session runtime
+ *
+ * Use AgentSessionRuntime when you need to replace the active AgentSession,
+ * for example for new-session, resume, fork, or import flows.
+ *
+ * The important pattern is: after the runtime replaces the active session,
+ * rebind any session-local subscriptions and extension bindings to `runtime.session`.
+ */
+
+import {
+	type CreateAgentSessionRuntimeFactory,
+	createAgentSessionFromServices,
+	createAgentSessionRuntime,
+	createAgentSessionServices,
+	getAgentDir,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+	const services = await createAgentSessionServices({ cwd });
+	return {
+		...(await createAgentSessionFromServices({
+			services,
+			sessionManager,
+			sessionStartEvent,
+		})),
+		services,
+		diagnostics: services.diagnostics,
+	};
+};
+const runtime = await createAgentSessionRuntime(createRuntime, {
+	cwd: process.cwd(),
+	agentDir: getAgentDir(),
+	sessionManager: SessionManager.create(process.cwd()),
+});
+
+let unsubscribe: (() => void) | undefined;
+
+async function bindSession() {
+	unsubscribe?.();
+	const session = runtime.session;
+	await session.bindExtensions({});
+	unsubscribe = session.subscribe((event) => {
+		if (event.type === "queue_update") {
+			console.log("Queued:", event.steering.length + event.followUp.length);
+		}
+	});
+	return session;
+}
+
+let session = await bindSession();
+const originalSessionFile = session.sessionFile;
+console.log("Initial session:", originalSessionFile);
+
+await runtime.newSession();
+session = await bindSession();
+console.log("After newSession():", session.sessionFile);
+
+if (originalSessionFile) {
+	await runtime.switchSession(originalSessionFile);
+	session = await bindSession();
+	console.log("After switchSession():", session.sessionFile);
+}
+
+unsubscribe?.();
+await runtime.dispose();

package/examples/sdk/14-codemode-mcp.ts

@@ -0,0 +1,61 @@
+/**
+ * Codemode, Tool Search, and MCP
+ *
+ * The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions add
+ * them to the resource loader's extension factories.
+ *
+ * `codemode` and `tool_search` are registered inactive. Enable them through the `defaultTools` setting
+ * (`tools` would also restrict the session to the named tools, which hides MCP tools), or let the
+ * MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for
+ * servers with `deferred` exposure.
+ */
+
+import {
+	createAgentSession,
+	createCodemodeExtension,
+	createMcpExtension,
+	createToolSearchExtension,
+	DefaultResourceLoader,
+	getAgentDir,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+const cwd = process.cwd();
+
+const resourceLoader = new DefaultResourceLoader({
+	cwd,
+	agentDir: getAgentDir(),
+	extensionFactories: [
+		createCodemodeExtension({ mode: "on" }),
+		createToolSearchExtension(),
+		// Reads mcp.json from the agent directory and the trusted project, like the CLI.
+		createMcpExtension(),
+	],
+});
+await resourceLoader.reload();
+
+const settingsManager = SettingsManager.create(cwd);
+// `+name` adds to the configured default tools instead of replacing them.
+settingsManager.applyOverrides({ defaultTools: ["+codemode", "+tool_search"] });
+
+const { session } = await createAgentSession({
+	resourceLoader,
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	// Emits session_start, which connects the MCP servers in the background.
+	await session.bindExtensions({});
+	console.log("Active tools:", session.getActiveToolNames().join(", "));
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+	await session.prompt("Use codemode to count the TypeScript files in src/ and list the three largest.");
+	console.log();
+} finally {
+	session.dispose();
+}

package/examples/sdk/README.md

@@ -0,0 +1,141 @@
+# SDK Examples
+
+Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+
+The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tool allowlists |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-prompt-templates.ts` | File-based prompt templates |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+| `13-session-runtime.ts` | Manage runtime-backed session replacement |
+| `14-codemode-mcp.ts` | Add the `codemode`, `tool_search`, and MCP extensions |
+
+## Running
+
+```bash
+cd packages/coding-agent
+node examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@earendil-works/pi-ai";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+const modelRuntime = await ModelRuntime.create();
+
+// Minimal
+const { session } = await createAgentSession({ modelRuntime });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
+
+// Read-only
+const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+// Full control
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  modelRuntime: customRuntime,
+  resourceLoader,
+  tools: ["read", "bash", "my_tool"],
+  customTools: [myTool],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.pi/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes, and context files |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_settled":
+      console.log("Done");
+      break;
+  }
+});
+```

package/package.json

@@ -1,6 +1,22 @@
 {
-  "name": "raga-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "raga-cli",
+	"version": "0.8.0",
+	"description": "Raga, a coding agent for long tasks with a persistent Python kernel (a fork of pi)",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mr-jones123/raga.git"
+	},
+	"bin": {
+		"raga": "dist/bundle/raga.js"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"@silvia-odwyer/photon-node": "0.3.4",
+		"jiti": "2.7.0",
+		"quickjs-wasi": "3.6.2"
+	}
+}

package/python/raga_rlm/__init__.py

@@ -0,0 +1,336 @@
+# Adapted from Prime Agent (MIT), github.com/PrimeIntellect-ai/prime-agent
+"""The names the model calls from the RLM kernel namespace.
+
+`bootstrap(namespace)` binds them once at kernel startup. Every host-backed
+function is a coroutine that sends one `host_request` and awaits the reply.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+# The kernel starts in the session cwd; `read` resolves relative paths against it even after a cell chdirs.
+_SESSION_CWD = os.getcwd()
+_RESTRICTED = os.environ.get("RAGA_RESTRICTED") == "1"
+
+__all__ = [
+    "BOOTSTRAP_NAMES",
+    "CELLS_OUTPUT_BUDGET",
+    "Context",
+    "HostError",
+    "Inputs",
+    "ToolError",
+    "answer",
+    "bash",
+    "bootstrap",
+    "cells",
+    "context",
+    "edit",
+    "host_request",
+    "llm_batch",
+    "llm_query",
+    "memory",
+    "instance",
+    "read",
+    "record_cell",
+    "rlm_query",
+    "set_context",
+    "write",
+]
+
+
+class HostError(Exception):
+    """The host answered a host_request with an error."""
+
+
+class ToolError(Exception):
+    """A pi tool reported an error; the message is the tool output."""
+
+
+async def host_request(data: dict[str, Any]) -> Any:
+    """Send one typed request to the host; return its result or raise HostError."""
+    # Imported lazily: `python -m raga_rlm.repl` imports this package before the
+    # kernel module registers itself as `raga_rlm.repl`.
+    from . import repl
+
+    reply = await repl.host_request(data)
+    if reply.get("status") == "ok":
+        return reply.get("result")
+    raise HostError(str(reply.get("error", "host request failed")))
+
+
+async def _tool(name: str, args: dict[str, Any]) -> str:
+    result = await host_request({"type": "tool.call", "name": name, "args": args})
+    text = str(result.get("text", "")) if isinstance(result, dict) else str(result)
+    if isinstance(result, dict) and result.get("is_error"):
+        raise ToolError(text)
+    return text
+
+
+def _drop_none(**fields: Any) -> dict[str, Any]:
+    return {key: value for key, value in fields.items() if value is not None}
+
+
+async def bash(command: str, timeout: float | None = None) -> str:
+    """Run a shell command under the session's execution policy and return its output."""
+    return await _tool("bash", _drop_none(command=command, timeout=timeout))
+
+
+async def read(path: str, offset: int | None = None, limit: int | None = None) -> str:
+    """Return the file's text, whole unless `offset` (1-indexed first line) or `limit` (line count) is given."""
+    with open(os.path.join(_SESSION_CWD, os.path.expanduser(path)), encoding="utf-8", errors="replace") as fh:
+        text = fh.read()
+    if offset is None and limit is None:
+        return text
+    lines = text.splitlines(keepends=True)
+    start = max((offset or 1) - 1, 0)
+    end = len(lines) if limit is None else start + limit
+    return "".join(lines[start:end])
+
+
+async def edit(path: str, edits: list[Any]) -> str:
+    """Apply exact replacements. `edits` holds (old, new) tuples or {"oldText","newText"} dicts."""
+    normalized: list[dict[str, str]] = []
+    for item in edits:
+        if isinstance(item, dict):
+            if "oldText" not in item or "newText" not in item:
+                raise ValueError('edit dicts need "oldText" and "newText"')
+            normalized.append({"oldText": item["oldText"], "newText": item["newText"]})
+        elif isinstance(item, (tuple, list)) and len(item) == 2:
+            normalized.append({"oldText": item[0], "newText": item[1]})
+        else:
+            raise TypeError("each edit must be an (old, new) tuple or an oldText/newText dict")
+    if _RESTRICTED:
+        target = os.path.join(_SESSION_CWD, os.path.expanduser(path))
+        with open(target, encoding="utf-8", newline="") as fh:
+            content = fh.read()
+        for item in normalized:
+            old, new = item["oldText"], item["newText"]
+            if not isinstance(old, str) or not isinstance(new, str) or not old:
+                raise ValueError("edits need nonempty oldText and string newText")
+            if content.count(old) != 1:
+                raise ToolError("Each edit must match exactly one occurrence")
+            content = content.replace(old, new, 1)
+        with open(target, "w", encoding="utf-8", newline="") as fh:
+            fh.write(content)
+        return f"Edited {path}"
+    return await _tool("edit", {"path": path, "edits": normalized})
+
+
+async def write(path: str, content: str) -> str:
+    """Write UTF-8 content under the session's filesystem policy."""
+    if _RESTRICTED:
+        target = os.path.join(_SESSION_CWD, os.path.expanduser(path))
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+        with open(target, "w", encoding="utf-8", newline="") as fh:
+            fh.write(content)
+        return f"Wrote {path}"
+    return await _tool("write", {"path": path, "content": content})
+
+
+async def llm_query(prompt: str, system: str | None = None, model: str | None = None) -> str:
+    """One sub-LLM call with no tools."""
+    result = await host_request({"type": "llm.query", **_drop_none(prompt=prompt, system=system, model=model)})
+    return result["text"]
+
+
+async def llm_batch(prompts: list[str], system: str | None = None, model: str | None = None) -> list[str]:
+    """Parallel sub-LLM calls; the host bounds concurrency."""
+    payload = _drop_none(prompts=list(prompts), system=system, model=model)
+    result = await host_request({"type": "llm.batch", **payload})
+    return list(result["texts"])
+
+
+async def rlm_query(
+    task: str,
+    context: Any = None,
+    model: str | None = None,
+    max_turns: int | None = None,
+    *,
+    read_only: bool = False,
+    details: bool = False,
+) -> str | dict[str, Any]:
+    """Run a child. Instance writers get isolated checkouts; details includes the change artifact."""
+    payload = _drop_none(task=task, context=context, model=model, max_turns=max_turns, read_only=read_only)
+    result = await host_request({"type": "rlm.query", **payload})
+    return result if details else result["answer"]
+
+
+class Inputs(Mapping[str, str]):
+    """Input names mapped to file contents. Each file is read the first time its key is read, then cached."""
+
+    def __init__(self, paths: dict[str, str] | None = None) -> None:
+        self._paths = dict(paths or {})
+        self._texts: dict[str, str] = {}
+
+    def __getitem__(self, name: str) -> str:
+        if name not in self._texts:
+            with open(self._paths[name], encoding="utf-8", errors="replace") as fh:
+                self._texts[name] = fh.read()
+        return self._texts[name]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._paths)
+
+    def __len__(self) -> int:
+        return len(self._paths)
+
+    def path(self, name: str) -> str:
+        """The file behind `name`, without reading it."""
+        return self._paths[name]
+
+    def __repr__(self) -> str:
+        return f"Inputs({self._paths!r})"
+
+
+class Context:
+    """`task` is the first user prompt, `inputs` holds large inputs, `data` is a JSON value from the parent."""
+
+    def __init__(self) -> None:
+        self.task: str = ""
+        self.inputs: Inputs = Inputs()
+        self.data: Any = None
+
+    async def history(self, offset: int = 0, limit: int | None = None) -> list[dict[str, Any]]:
+        """Return the session's messages as {"role", "text"} dicts."""
+        result = await host_request({"type": "context.history", **_drop_none(offset=offset, limit=limit)})
+        return list(result["messages"])
+
+    def __repr__(self) -> str:
+        return (
+            f"Context(task={self.task!r}, inputs=<{len(self.inputs)} keys: {sorted(self.inputs)!r}>, "
+            f"data=<{type(self.data).__name__}>)"
+        )
+
+
+class Memory:
+    """Scoped retrieval and unreviewed observations. Entries never grant permissions."""
+
+    async def search(self, query: str, *, task_type: str | None = None, max_chars: int = 4000, limit: int = 5) -> dict[str, Any]:
+        return await host_request({
+            "type": "memory.search",
+            **_drop_none(query=query, task_type=task_type, max_chars=max_chars, limit=limit),
+        })
+
+    async def get(self, entry_id: str) -> dict[str, Any]:
+        return await host_request({"type": "memory.get", "id": entry_id})
+
+    async def observe(self, text: str, evidence: list[str]) -> dict[str, Any]:
+        return await host_request({"type": "memory.observe", "text": text, "evidence": evidence})
+
+
+class Instance:
+    """Inspect the pinned harness and propose changes without activating them."""
+
+    async def info(self) -> dict[str, Any]:
+        return await host_request({"type": "instance.info"})
+
+    async def child_patch(self, workspace_id: str) -> dict[str, Any]:
+        return await host_request({"type": "instance.child_patch", "workspace_id": workspace_id})
+
+    async def integrate(
+        self, workspace_ids: list[str], command: str, args: list[str] | None = None, *, timeout_ms: int = 120000
+    ) -> dict[str, Any]:
+        return await host_request({
+            "type": "instance.integrate",
+            "workspace_ids": workspace_ids,
+            "command": command,
+            "args": args or [],
+            "timeout_ms": timeout_ms,
+        })
+
+    async def candidate_create(self) -> dict[str, Any]:
+        return await host_request({"type": "instance.candidate.create"})
+
+    async def candidate_read(self, candidate_id: str, path: str) -> str:
+        return await host_request({"type": "instance.candidate.read", "id": candidate_id, "path": path})
+
+    async def candidate_write(self, candidate_id: str, path: str, content: str) -> dict[str, Any]:
+        return await host_request({"type": "instance.candidate.write", "id": candidate_id, "path": path, "content": content})
+
+    async def candidate_commit(self, candidate_id: str, message: str) -> dict[str, Any]:
+        return await host_request({"type": "instance.candidate.commit", "id": candidate_id, "message": message})
+
+    async def no_mistakes(self, action: str, **options: Any) -> Any:
+        return await host_request({"type": "instance.no_mistakes", "action": action, "options": options})
+
+
+memory = Memory()
+instance = Instance()
+
+
+context = Context()
+answer: dict[str, Any] = {"content": "", "ready": False}
+cells: list[dict[str, Any]] = []
+# Characters of stdout and stderr that the newest `cells` entries keep in full.
+CELLS_OUTPUT_BUDGET = 32 * 1024 * 1024
+_DROPPED_PREFIX = "[output dropped to bound memory: "
+
+BOOTSTRAP_NAMES = frozenset(
+    {
+        "bash",
+        "read",
+        "edit",
+        "write",
+        "llm_query",
+        "llm_batch",
+        "rlm_query",
+        "memory",
+        "instance",
+        "context",
+        "answer",
+        "cells",
+        "HostError",
+        "ToolError",
+    }
+)
+
+
+def bootstrap(namespace: dict[str, Any]) -> None:
+    """Bind the Python API into the kernel namespace."""
+    for name in BOOTSTRAP_NAMES:
+        namespace[name] = globals()[name]
+
+
+def set_context(task: str, inputs: dict[str, str], data: Any = None) -> None:
+    """Fill `context.task`, `context.inputs`, and `context.data`; `inputs` maps names to file paths."""
+    if not isinstance(task, str):
+        raise TypeError("task must be a string")
+    if not isinstance(inputs, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in inputs.items()):
+        raise TypeError("inputs must map names to file paths")
+    context.task = task
+    context.inputs = Inputs(inputs)
+    context.data = data
+
+
+def record_cell(entry: dict[str, Any]) -> None:
+    """Append one finished cell; called by the kernel.
+
+    The newest cells keep full stdout and stderr up to CELLS_OUTPUT_BUDGET
+    characters in total; older cells keep code, result, and error only. The
+    newest cell always keeps its output.
+    """
+    cells.append(entry)
+    kept = 0
+    evicting = False
+    for index, cell in enumerate(reversed(cells)):
+        if not isinstance(cell, dict):
+            continue
+        live = {
+            key: text
+            for key in ("stdout", "stderr")
+            if isinstance(text := cell.get(key), str) and text and not _is_dropped(text)
+        }
+        size = sum(len(text) for text in live.values())
+        if not evicting and (index == 0 or kept + size <= CELLS_OUTPUT_BUDGET):
+            kept += size
+            continue
+        evicting = True
+        for key, text in live.items():
+            cell[key] = f"{_DROPPED_PREFIX}{len(text)} characters]"
+
+
+def _is_dropped(text: str) -> bool:
+    return text.startswith(_DROPPED_PREFIX) and text.endswith(" characters]")