@yunazgr/pi-companion 0.2.6 → 0.3.1

package/README.md

@@ -2,6 +2,8 @@
 
 Lightweight, local-first remote control for Pi sessions.
 
+**New in 0.3.1:** claymorphic automation workspaces with searchable, status-filtered, paginated lists; Summary/History tabs and calendar-style run cards; sanitized Markdown/ADF/JSON results; a staged job editor with strict validation and optional failed-action retries (up to 5, default 10-second interval). Per-automation history keeps the latest 30 runs by default, with 10 per page. Automated sessions are clearly marked as answers-only. Type `/` in a normal session to discover available commands, skills, and prompt templates. See [automations](docs/automations.md).
+
 Pi Companion is deliberately not another agent runtime. Pi owns execution and conversation state. A single Rust daemon owns session discovery, pairing, temporary file exchange, browser fan-out, and the embedded web UI.
 
 The UI is a static SvelteKit application. There is no Node runtime in production and no Tauri shell. Rust embeds the generated frontend into the daemon binary.
@@ -13,7 +15,7 @@ The UI is a static SvelteKit application. There is no Node runtime in production
   <img src="docs/mobile.webp" alt="Session detail on a phone" width="28%" />
 </p>
 
-Screenshots use demo sessions, not private conversation data, and are regenerated with `node tools/screenshots.mjs` (see [Running locally from source](#running-locally-from-source)). See the [session menu](docs/session-menu.webp), [desktop session rows](docs/session-list-desktop.webp) and [mobile session list](docs/session-list.webp), plus [attachment previews](docs/attachments.webp), [file-grouped changes](docs/changes.webp) and [connection recovery](docs/connection-error.webp).
+Screenshots use demo sessions, not private conversation data, and are regenerated with `node tools/screenshots.mjs` (see [Running locally from source](#running-locally-from-source)). See the [session menu](docs/session-menu.webp), [desktop session rows](docs/session-list-desktop.webp) and [mobile session list](docs/session-list.webp), plus [attachment previews](docs/attachments.webp), [file-grouped changes](docs/changes.webp) and [connection recovery](docs/connection-error.webp). Explore the new [automation list](docs/automations.webp), [summary](docs/automation-detail.webp), [run history](docs/automation-history.webp), [job editor](docs/automation-editor.webp), and [rich results](docs/automation-result.webp).
 
 ## Install
 
@@ -352,7 +354,7 @@ Clone the repository, then:
 
 `npm run serve` builds the embedded Svelte UI and starts the Rust daemon in the foreground. It prints:
 
-      Pi Companion v0.2.6
+      Pi Companion v0.3.1
 
       Console          http://127.0.0.1:43721
       Paired devices   http://127.0.0.1:43722
@@ -390,6 +392,8 @@ To regenerate the README screenshots from demo sessions (your running daemon is
     npm run ui:build && cargo build --release --manifest-path server/Cargo.toml
     node tools/screenshots.mjs
 
+The generator also refreshes automation list/detail/history/editor/results, automated session, and [slash-command suggestions](docs/slash-commands.webp) screenshots. Type `/` in a shared session to search its available extension commands, skills, and prompt templates; use ↑/↓ and Tab/Enter to choose, then send when ready. Built-in terminal-only commands and ordinary tool names are not included. Automated answers-only sessions never expose this picker.
+
 It needs Playwright and `cwebp`. Set `PLAYWRIGHT=/path/to/node_modules/playwright/index.mjs` if Playwright isn't installed in this repo, and `CHROME=/path/to/chrome` to use an existing browser.
 
 To test the same behavior as a published install, stop any development daemon first and install the package normally:

package/SECURITY.md

@@ -24,7 +24,7 @@ Strict Origin checks: WebSocket upgrades and POST/DELETE requests must carry an
 
 Pairing invitations are single-use and expire (5 minutes by default). The short typed code is rate limited: ten wrong codes within ten minutes withdraw every open invitation and further code claims get HTTP 429 until the window passes.
 
-Paired devices can see only sessions that explicitly enabled remote control.
+Paired devices can see only sessions that explicitly enabled remote control, including daemon-owned automation sessions created by an authorized automation run. Paired devices may read automation definitions/history and start/stop existing automations, but cannot create, edit, delete, or enable/disable them.
 
 Revoking a device deletes its credential hash and closes its open connections immediately (WebSocket close 4003). Disconnecting closes them without deleting the credential (close 4001).
 
@@ -32,6 +32,14 @@ Revoking a device deletes its credential hash and closes its open connections im
 
 Paired devices (name, browser user agent, pairing and last-seen times, and the SHA-256 hash of the credential; never the credential) and settings are written atomically to `~/.pi/agent/pi-companion/state.json`. On Unix the directory is 0700 and the file is created 0600 before any byte is written; a looser mode found at startup is tightened.
 
+Automation definitions, prompts, and bounded run output are stored separately in `automations.json`, using atomic replacement and private Unix permissions. Output can contain sensitive command/agent data; it is readable by paired devices. Failed or stopped runs are retained; interrupted runs are marked failed on daemon restart.
+
+### Automations
+
+Only the local admin surface can author automation scripts. Native extension and standalone MCP tools use that surface and do not start the daemon implicitly. Commands use argv without an implicit shell, but both commands and spawned Pi agents run with the OS user's permissions; this is not a sandbox. A paired device can start a previously authorized script with side effects. Disabling a definition prevents scheduling, not explicit manual runs.
+
+Automation sessions accept only question answers/cancellation from browsers. Prompts, steering, abort/plan/diff commands, uploads, and file deletion are denied server-side. Stop a run through its automation endpoint instead. Five-field UTC schedules run only while the daemon is alive, without overlapping runs or catch-up. Automatic session archiving after seven disconnected days removes registry/feed records only, never local Pi/project files.
+
 ### Web UI hardening
 
 HTML responses send a same-origin Content-Security-Policy (no third-party scripts, styles, fonts or connections), `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` and `X-Content-Type-Options: nosniff`. The UI loads nothing from the network beyond the daemon itself.
@@ -54,7 +62,7 @@ Agent deletion uses the opaque id rather than a path. Before unlinking, the daem
 
 Pi Companion does not provide:
 
-- remote shell access
+- arbitrary remote shell access (paired devices can start admin-authored automation commands)
 - arbitrary filesystem browsing
 - arbitrary tool invocation
 - direct git push/commit endpoints

package/docs/automations.md

@@ -0,0 +1,100 @@
+# Automations (0.3.1)
+
+Automations are persisted, named JSON scripts run by the Companion daemon. Open **Automations** in the navigation to view definitions, start/stop runs, and inspect timestamped run history. Click a run to view its captured output and Pi summary. Desktop console users can create, edit, delete, and enable/disable definitions; mobile and paired-device users can only inspect and start/stop them.
+
+## Workspace & editor
+
+The claymorphic automation collection supports name search, Enabled/Disabled filters, ten-item pagination, and its own scrollable card region. The detail workspace has **Summary** and **Run history** tabs; history is newest-first with calendar tiles, duration, status filters, and ten-item pagination over each automation’s retained history (latest 30 finished runs by default, configurable 1–1000).
+
+The job editor separates name, enablement, UTC cron, optional retry policy, preconditions, actions, and post-actions. Each step is a reorderable JSON DSL object with Command/Pi templates. Saving validates the definition, cron ranges, action types, arguments, absolute directories, timeouts, step count, and retry bounds; the daemon validates again before persistence. Only computer desktop administrators can author definitions.
+
+Run results have a formatted and raw view. Formatted results split daemon execution phases, render sanitized Markdown (including tables, links, code, and diagrams), recognise whole/fenced JSON, and render Atlassian Document Format (`type: "doc"`) or `{ "adf": ... }` documents. ADF supports headings, lists, marks, tables, panels, and safe links; unsupported nodes preserve their text, and attachments are placeholders. HTML/scripts and executable link protocols are not trusted. Raw output remains available for inspection and copying.
+
+## Screenshots
+
+Screenshots use only demo data. The same generator refreshes the existing overview, session, and mobile screenshots too.
+
+![Automations on the overview below live sessions](overview-automations.webp)
+![Searchable automation cards](automations.webp)
+![Automation cards on a phone](automations-mobile.webp)
+![Run history on a phone](automation-history-mobile.webp)
+![Automation summary and execution steps](automation-detail.webp)
+![Filtered, paginated run history](automation-history.webp)
+![Friendly staged job editor](automation-editor.webp)
+![Rich review summary with linked PR table](automation-result.webp)
+![Answers-only automated session](automation-session.webp)
+
+## History retention
+
+`historyLimit` is an optional integer **1–1000**, default **30**. Each automation retains its latest N finished runs, replacing older history as newer runs finish. Lowering the limit prunes older runs immediately on save; active runs are retained until finished. The same policy is applied on daemon startup. Deleted run results cannot be recovered from the dashboard. Run history pages show **10 items** at a time.
+
+Automations also appear below running sessions on the overview. Automated sessions are labelled **Automated · answers only** in session cards, tables, and the session workspace. Their browser controls allow question answers but not steering, planning, uploads, or code changes; backend restrictions remain authoritative.
+
+## Optional retries
+
+`maxRetries` is an optional integer **0–5** (default **0**, no retries). `retryIntervalSeconds` is an optional integer **1–86400** (default **10 seconds**). Only a failed main action is retried; completed steps do not repeat, and precondition skips and finalizers are never retried. Stop cancels an active process or retry delay. Save-time validation requires the total retry-delay budget to be shorter than the shortest daily UTC trigger gap (a conservative bound for schedules limited to selected dates). Before each wait, the daemon also skips a retry that would reach the next scheduled trigger. It cannot guarantee action duration; overlapping runs remain prohibited. Attempt diagnostics are included in run output, and finalizers execute after the final outcome unless stopped.
+
+**Retries can duplicate side effects**, including model calls and remote submissions after ambiguous failures. Enable them only for retry-safe work; the PR-review automation should keep retries off. Existing definitions without either field retain their original behavior.
+
+## JSON DSL
+
+```json
+{
+  "name": "Daily repository check",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "maxRetries": 0,
+  "retryIntervalSeconds": 10,
+  "historyLimit": 30,
+  "preconditions": [
+    { "type": "command", "command": "git", "args": ["rev-parse", "--is-inside-work-tree"], "cwd": "/absolute/project" }
+  ],
+  "actions": [
+    { "type": "command", "command": "npm", "args": ["test"], "cwd": "/absolute/project", "timeoutSeconds": 600 },
+    { "type": "pi", "prompt": "Summarize the repository's current health. Do not edit files.", "cwd": "/absolute/project", "timeoutSeconds": 900 }
+  ],
+  "postActions": []
+}
+```
+
+Commands run as executable + argv, not through an implicit shell. A nonzero precondition skips the main actions. Actions execute in order. Post-actions provide a finalization stage. `schedule: null` is manual-only; otherwise use five cron fields (minute, hour, day of month, month, day of week), evaluated in **UTC**. Scheduled execution requires the daemon to remain running; it does not catch up missed executions. A definition cannot have overlapping runs. Disabling scheduling and stopping a run are separate operations.
+
+A Pi action starts `pi --mode rpc --no-session` in the specified directory. Pi must be on PATH and already configured with credentials/model settings. It exposes a read-only Companion session: the feed and questions are visible, but steering, prompts, plan changes, file uploads, and diffs are unavailable. This restriction applies to browser control, **not** the agent's own tools or filesystem access. Pi's final assistant output is stored in the run result. Supported RPC `select`, `confirm`, `input`, and `editor` questions are forwarded; terminal-only custom dialogs cannot be displayed. The native `companion_ask_user` tool falls back to these RPC dialogs for daemon-owned runs.
+
+**Security:** automations run with the daemon user's operating-system privileges. They are not sandboxed. Paired devices can start an existing automation, including commands with side effects. Pair only devices you trust, and review commands, prompts, working directories, and schedules before saving/enabling a definition. Native agent tools and MCP management use the local admin surface; do not expose that surface publicly.
+
+## Agent surface
+
+The extension registers `companion_automation` and ships the `companion-automations` skill. Operations: `list`, `get`, `create`, `update`, `delete`, `enable`, `disable`, `start`, `stop`, `runs`, and `run`. Supply `id` except for list/create, a full `automation` definition for create/update, and `runId` for run detail.
+
+```json
+{"action":"create","automation":{"name":"Check","enabled":true,"schedule":null,"preconditions":[],"actions":[{"type":"command","command":"git","args":["status","--short"],"cwd":"/absolute/project"}],"postActions":[]}}
+```
+
+Tools only contact an already-running daemon. They never download/start one or activate sharing for a normal Pi session. Start Companion explicitly via `/companion` or `npm run serve` first. Inspect the final run status rather than assuming an accepted start means success.
+
+## Standalone MCP
+
+Node >=22.17 can run the shipped stdio MCP server, without an MCP SDK dependency:
+
+```bash
+pi mcp add companion-automations -- node --experimental-strip-types --no-warnings /absolute/path/to/pi-companion/src/automation-mcp.ts
+```
+
+Other MCP clients can configure the same executable and arguments. The server exposes `companion_automation` with the same schema as the native extension tool. Configure only one surface if you want to avoid duplicate tools. It uses the default local admin address, overridable with `PI_COMPANION_URL=ws://127.0.0.1:PORT`; non-loopback management targets are rejected.
+
+## HTTP API
+
+Admin console:
+
+- `GET /api/automations` → `{automations}`; `POST` creates a definition.
+- `GET /api/automations/{id}` → definition; `PUT` replaces it; `DELETE` removes it.
+- `POST /api/automations/{id}/start` and `/stop`.
+- `GET /api/automations/{id}/runs` → `{runs}`.
+- `GET /api/automations/{id}/runs/{runId}` → run details including result.
+
+The paired-device surface requires valid device authentication and allowed Origin, and exposes only GET/start/stop. Mobile layout is a UI restriction, not a separate authentication role; local console API callers remain administrators.
+
+## Automatic archiving
+
+Disconnected/stopped session records older than seven days are archived automatically. Live command channels, active/idle sessions, and recent disconnections are retained. Archiving removes only the daemon registry/feed entries, never the project, local Pi history, or files. Automation definitions and run history are independent of session archiving.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunazgr/pi-companion",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Local-first remote control for Pi sessions: live activity feed, steering, git diff, file drop and phone pairing from a single Rust daemon.",
   "keywords": [
     "pi-package",
@@ -28,6 +28,8 @@
   "main": "src/index.ts",
   "files": [
     "src",
+    "skills",
+    "docs/automations.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -37,6 +39,7 @@
   },
   "scripts": {
     "serve": "npm run --silent ui:build -- --logLevel warn && cargo run -q --manifest-path server/Cargo.toml",
+    "automation:mcp": "node --experimental-strip-types --no-warnings src/automation-mcp.ts",
     "server:dev": "npm run serve",
     "server:check": "npm run ui:build && cargo check --manifest-path server/Cargo.toml",
     "ui:dev": "cd ui && vite dev",
@@ -44,13 +47,17 @@
     "check": "tsc --noEmit && npm run ui:check",
     "ui:check": "cd ui && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings",
     "test": "npm run test:extension && npm run test:server",
-    "test:extension": "node --test --experimental-transform-types --no-warnings test/*.test.ts",
-    "test:server": "cargo test --manifest-path server/Cargo.toml"
+    "test:extension": "node --test --experimental-transform-types --no-warnings test/*.test.ts ui/automation.test.ts",
+    "test:server": "cargo test --manifest-path server/Cargo.toml",
+    "test:smoke": "npm run ui:build && cargo build --manifest-path server/Cargo.toml --locked && node tools/smoke-automations.mjs"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "image": "https://raw.githubusercontent.com/ygrip/pi-companion/main/docs/dashboard.png"
   },
   "dependencies": {

package/skills/companion-automations/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: companion-automations
+description: Create, update, delete, enable, disable, run, stop, and inspect Pi Companion automations with the companion_automation tool. Use for recurring repository tasks, scheduled agent work, and automation run history.
+---
+
+# Companion automations
+
+Use `companion_automation` (native extension or standalone MCP surface). It talks only to the local admin daemon; it does not launch the daemon or enable session sharing. If unavailable, ask the user to start Companion with `/companion` or `npm run serve`.
+
+## Safety
+
+Before saving or starting an automation, confirm the user's intended command, working directory, schedule, and side effects. Do not silently schedule destructive commands, spend model quota, or turn an untrusted prompt into a recurring task. Commands and Pi runs execute with the user's OS permissions, not in a sandbox. Remote/mobile clients can inspect, start, and stop existing definitions, but cannot author them.
+
+Read the current definition with `get` before `update`, `enable`, or `disable`. Updating replaces the full definition. Preserve fields not intentionally changed. `disable` prevents scheduled runs; use `stop` separately to cancel a running automation. Definitions and run history are daemon-owned; archiving sessions never deletes local Pi data.
+
+## Definition DSL
+
+```json
+{
+  "name": "Repository check",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "preconditions": [],
+  "actions": [
+    { "type": "command", "command": "npm", "args": ["test"], "cwd": "/absolute/repo", "timeoutSeconds": 600 },
+    { "type": "pi", "prompt": "Summarize repository health. Do not edit files.", "cwd": "/absolute/repo", "timeoutSeconds": 900 }
+  ],
+  "postActions": []
+}
+```
+
+- `schedule` is a five-field **UTC** cron expression; `null` means manual only. The daemon must be running for scheduling. There is no catch-up while it is stopped.
+- Commands use executable plus argument array, **no implicit shell**. Shell syntax must never be passed as an executable. Avoid explicit shells unless the user requested and authorized them.
+- Preconditions gate execution. Actions run sequentially. Post-actions are the cleanup/finalization stage; inspect the run result to determine failures.
+- Optional `maxRetries` (integer 0–5, default 0) and `retryIntervalSeconds` (integer 1–86400, default 10) retry only the failed main action, never completed steps, preconditions, or finalizers. Stop cancels a retry delay. Retries may duplicate side effects or model usage: obtain authorization, and keep them off for non-idempotent remote submissions.
+- Optional `historyLimit` (integer 1–1000, default 30) keeps the latest N finished runs per automation. Lowering it immediately removes older history on save. Retry delays must fit before the next scheduled trigger.
+- A Pi action starts a daemon-owned, read-only Companion session: users can answer asks, but cannot steer, prompt, upload, request changes, or edit its plan. The agent itself still has ordinary Pi tool permissions.
+- Pi must be installed on PATH and configured with model credentials. Its final assistant output is saved in run history.
+
+## Tool operations
+
+- `list`, `get` (`id`)
+- `create` (`automation`), `update` (`id`, full `automation`)
+- `delete`, `enable`, `disable`, `start`, `stop` (`id`)
+- `runs` (`id`), `run` (`id`, `runId`)
+
+After `start`, inspect `runs`/`run`; an accepted start is not completion. Report the actual final status and stored result. Do not retry a side-effecting run automatically after an ambiguous network error.

package/src/automation-mcp.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/** Standalone stdio MCP surface. Run with Node >=22.17 (native TypeScript stripping). */
+import { automationTool, executeAutomation, type AutomationParams } from "./automation.ts";
+
+const inFlight = new Map<string | number, AbortController>();
+let output = Promise.resolve();
+function send(record: unknown) {
+  const line = JSON.stringify(record) + "\n";
+  output = output.then(() => new Promise<void>((resolve, reject) => {
+    process.stdout.write(line, error => error ? reject(error) : resolve());
+  }));
+  void output.catch(() => { process.exitCode = 1; process.stdin.destroy(); });
+}
+const error = (id: unknown, code: number, message: string) => send({ jsonrpc: "2.0", id, error: { code, message } });
+async function receive(line: string) {
+  let message: { jsonrpc?: string; id?: string | number; method?: string; params?: Record<string, unknown> };
+  try { message = JSON.parse(line); }
+  catch { error(null, -32700, "Invalid JSON"); return; }
+  if (!message || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    error(message?.id ?? null, -32600, "Invalid JSON-RPC request"); return;
+  }
+  if (message.method === "notifications/cancelled") {
+    const id = message.params?.requestId;
+    if (typeof id === "string" || typeof id === "number") inFlight.get(id)?.abort();
+    return;
+  }
+  if (message.id === undefined) return;
+  const id = message.id;
+  const reply = (result: unknown) => send({ jsonrpc: "2.0", id, result });
+  switch (message.method) {
+    case "initialize": {
+      const versions = ["2025-06-18", "2025-03-26", "2024-11-05"];
+      const requested = message.params?.protocolVersion;
+      reply({ protocolVersion: versions.includes(String(requested)) ? requested : versions[0], capabilities: { tools: {} }, serverInfo: { name: "pi-companion-automations", version: "0.3.1" } });
+      return;
+    }
+    case "ping": reply({}); return;
+    case "tools/list": reply({ tools: [automationTool] }); return;
+    case "tools/call": {
+      if (message.params?.name !== automationTool.name) { error(id, -32602, "Unknown tool"); return; }
+      const args = message.params?.arguments;
+      if (!args || typeof args !== "object" || Array.isArray(args)) { error(id, -32602, "Expected tool arguments"); return; }
+      const controller = new AbortController();
+      inFlight.set(id, controller);
+      try {
+        const result = await executeAutomation(args as AutomationParams, controller.signal);
+        reply({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
+      } catch (failure) {
+        reply({ isError: true, content: [{ type: "text", text: String(failure instanceof Error ? failure.message : failure) }] });
+      } finally { inFlight.delete(id); }
+      return;
+    }
+    default: error(id, -32601, "Method not found");
+  }
+}
+
+// Split only LF: Unicode line separators are legal inside JSON string values.
+let buffer = Buffer.alloc(0);
+for await (const chunk of process.stdin) {
+  buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+  let newline: number;
+  while ((newline = buffer.indexOf(10)) !== -1) {
+    const line = buffer.subarray(0, newline).toString("utf8").replace(/\r$/, "");
+    buffer = buffer.subarray(newline + 1);
+    if (Buffer.byteLength(line) > 1024 * 1024) { error(null, -32600, "Request too large"); continue; }
+    if (line.trim()) void receive(line);
+  }
+  if (buffer.length > 1024 * 1024) { error(null, -32600, "Request too large"); process.stdin.destroy(); break; }
+}
+for (const controller of inFlight.values()) controller.abort();
+await output;

package/src/automation.ts

@@ -0,0 +1,111 @@
+import { adminHttpUrl } from "./daemon.ts";
+
+export type AutomationAction =
+  | { type: "command"; command: string; args: string[]; cwd?: string; timeoutSeconds?: number }
+  | { type: "pi"; prompt: string; cwd: string; timeoutSeconds?: number };
+export type AutomationDefinition = {
+  name: string;
+  enabled: boolean;
+  schedule: string | null;
+  preconditions: AutomationAction[];
+  actions: AutomationAction[];
+  postActions: AutomationAction[];
+  historyLimit?: number;
+  maxRetries?: number;
+  retryIntervalSeconds?: number;
+};
+export type AutomationParams = {
+  action: "list" | "get" | "create" | "update" | "delete" | "enable" | "disable" | "start" | "stop" | "runs" | "run";
+  id?: string;
+  runId?: string;
+  automation?: AutomationDefinition;
+};
+
+const actionSchema = {
+  oneOf: [
+    { type: "object", additionalProperties: false, required: ["type", "command", "args"], properties: {
+      type: { const: "command" }, command: { type: "string", minLength: 1 },
+      args: { type: "array", items: { type: "string" } }, cwd: { type: "string" },
+      timeoutSeconds: { type: "integer", minimum: 1, maximum: 86400 }
+    } },
+    { type: "object", additionalProperties: false, required: ["type", "prompt", "cwd"], properties: {
+      type: { const: "pi" }, prompt: { type: "string", minLength: 1 }, cwd: { type: "string", minLength: 1 },
+      timeoutSeconds: { type: "integer", minimum: 1, maximum: 86400 }
+    } }
+  ]
+};
+
+export const automationTool = {
+  name: "companion_automation",
+  description: "Manage Pi Companion automations: list, get, create, update, delete, enable, disable, start, stop, runs, or run detail. Definitions use preconditions, actions, postActions and optional five-field UTC cron schedule. Commands execute argv without a shell. Mutations require the user's authorization; running actions has the computer user's permissions. Does not start the daemon or enable session sharing.",
+  inputSchema: {
+    type: "object", additionalProperties: false, required: ["action"],
+    properties: {
+      action: { type: "string", enum: ["list", "get", "create", "update", "delete", "enable", "disable", "start", "stop", "runs", "run"] },
+      id: { type: "string", minLength: 1 }, runId: { type: "string", minLength: 1 },
+      automation: {
+        type: "object", additionalProperties: false,
+        required: ["name", "enabled", "schedule", "preconditions", "actions", "postActions"],
+        properties: {
+          name: { type: "string", minLength: 1 }, enabled: { type: "boolean" },
+          schedule: { type: ["string", "null"], description: "Five-field UTC cron; null for manual only." },
+          preconditions: { type: "array", items: actionSchema },
+          actions: { type: "array", minItems: 1, items: actionSchema },
+          postActions: { type: "array", items: actionSchema },
+          historyLimit: { type: "integer", minimum: 1, maximum: 1000, description: "Retain latest N finished runs; default 30." },
+          maxRetries: { type: "integer", minimum: 0, maximum: 5, description: "Optional retries of the failed main action only; default 0. May repeat side effects." },
+          retryIntervalSeconds: { type: "integer", minimum: 1, maximum: 86400, description: "Optional delay between retries; default 10 seconds; total retry delay must fit before the next scheduled trigger." }
+        }
+      }
+    }
+  }
+};
+
+/** Explicit tool calls only: never probe, download, or launch a daemon here. */
+export async function executeAutomation(params: AutomationParams, signal?: AbortSignal) {
+  const actions = ['list', 'get', 'create', 'update', 'delete', 'enable', 'disable', 'start', 'stop', 'runs', 'run'];
+  if (!params || typeof params !== 'object' || !actions.includes(params.action)) throw new Error("Unknown automation action.");
+  if (params.id !== undefined && (typeof params.id !== 'string' || !params.id.trim())) throw new Error("id must be a nonempty string.");
+  if (params.runId !== undefined && (typeof params.runId !== 'string' || !params.runId.trim())) throw new Error("runId must be a nonempty string.");
+  const base = adminHttpUrl();
+  const target = new URL(base);
+  if (!['127.0.0.1', 'localhost', '[::1]', '::1'].includes(target.hostname) || !['http:', 'https:'].includes(target.protocol)) {
+    throw new Error("Automation management requires the local Companion admin address.");
+  }
+  const request = async (path: string, method = "GET", body?: unknown) => {
+    const response = await fetch(base + path, {
+      method,
+      headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000)
+    });
+    if (!response.ok) throw new Error(`Companion ${response.status}: ${await response.text()}`);
+    return response.status === 204 ? { ok: true } : await response.json();
+  };
+  if (params.action === "list") return request("/api/automations");
+  if (params.action === "create") {
+    if (!params.automation) throw new Error("create requires automation.");
+    return request("/api/automations", "POST", params.automation);
+  }
+  if (!params.id) throw new Error(`${params.action} requires id.`);
+  const path = "/api/automations/" + encodeURIComponent(params.id);
+  switch (params.action) {
+    case "get": return request(path);
+    case "update":
+      if (!params.automation) throw new Error("update requires a complete automation definition.");
+      return request(path, "PUT", params.automation);
+    case "delete": return request(path, "DELETE");
+    case "enable": case "disable": {
+      const current = await request(path) as AutomationDefinition;
+      // PUT only definition fields, never server-generated metadata.
+      const { name, schedule, preconditions, actions, postActions, maxRetries, retryIntervalSeconds, historyLimit } = current;
+      return request(path, "PUT", { name, schedule, preconditions, actions, postActions, maxRetries, retryIntervalSeconds, historyLimit, enabled: params.action === "enable" });
+    }
+    case "start": case "stop": return request(path + "/" + params.action, "POST");
+    case "runs": return request(path + "/runs");
+    case "run":
+      if (!params.runId) throw new Error("run requires runId.");
+      return request(path + "/runs/" + encodeURIComponent(params.runId));
+    default: throw new Error("Unknown automation action.");
+  }
+}

package/src/bridge.ts

@@ -70,7 +70,11 @@ export class CompanionBridge implements AskChannel {
       shortTitle: name?.trim() || cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
       mainModel: ctx.model?.id ?? null,
       effort: ctx.thinkingLevel ?? this.pi.getThinkingLevel?.() ?? null,
-      telemetry: this.telemetry.snapshot(ctx)
+      telemetry: this.telemetry.snapshot(ctx),
+      // Expose only executable slash commands, not local source paths or credentials.
+      commands: (this.pi.getCommands?.() ?? []).slice(0, 500).map(command => ({
+        name: command.name, description: command.description?.slice(0, 500), source: command.source
+      }))
     };
     const patch: Partial<SessionSnapshot> = {};
     for (const key of Object.keys(next) as Array<keyof typeof next>) {

package/src/index.ts

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 import { formatAnswers, toQuestions } from "./ask.js";
 import { CompanionBridge } from "./bridge.js";
 import { adminHttpUrl, ensureDaemon } from "./daemon.js";
+import { automationTool, executeAutomation, type AutomationParams } from "./automation.ts";
 
 const AskOptionParam = Type.Union([
   Type.String(),
@@ -143,6 +144,22 @@ export default function companionExtension(pi: ExtensionAPI) {
     bridge.close();
   });
 
+  pi.registerTool({
+    name: automationTool.name,
+    label: "Companion automation",
+    description: automationTool.description,
+    parameters: Type.Unsafe<AutomationParams>(automationTool.inputSchema),
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal) {
+      try {
+        const result = await executeAutomation(params, signal);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: { result, error: null as string | null } };
+      } catch (error) {
+        return { isError: true, content: [{ type: "text", text: String(error instanceof Error ? error.message : error) }], details: { result: null, error: String(error) } };
+      }
+    }
+  });
+
   pi.registerTool({
     name: "companion_ask_user",
     label: "Ask via Companion",
@@ -150,7 +167,46 @@ export default function companionExtension(pi: ExtensionAPI) {
       "Ask the user one to four questions through the Pi Companion web/phone UI. Each question can offer options (single or multi-select) and an optional free-text answer.",
     parameters: AskParams,
     executionMode: "sequential",
-    async execute(_toolCallId, params, signal) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      // Daemon-owned RPC runs relay supported extension UI dialogs, not a second bridge.
+      // Normal sessions still require explicit /companion activation.
+      if (ctx?.mode === "rpc" && process.env.PI_COMPANION_AUTOMATION_RUN_ID) {
+        const items = params.questions?.length ? params.questions : params.question ? [{ question: params.question, options: params.options }] : [];
+        if (!items.length) return { content: [{ type: "text", text: "Provide `question` or `questions`." }], details: { questions: [], answers: null } };
+        const questions = toQuestions(items);
+        const answers: Record<string, string[]> = {};
+        for (const question of questions) {
+          if (signal?.aborted) break;
+          const choices = question.options.map(option => option.label);
+          const title = question.question + (question.options.some(option => option.description) ? "\n" + question.options.map(option => option.label + (option.description ? ": " + option.description : "")).join("\n") : "");
+          if (choices.length && !question.multiSelect) {
+            const custom = "Other (enter a response)";
+            const selected = await ctx.ui.select(title, question.allowCustom ? [...choices, custom] : choices, { signal, timeout: ASK_TIMEOUT_MS });
+            if (selected === undefined) break;
+            if (question.allowCustom && selected === custom) {
+              const value = await ctx.ui.input(question.question, "Your response", { signal, timeout: ASK_TIMEOUT_MS });
+              if (value === undefined) break;
+              answers[question.id] = [value];
+            } else answers[question.id] = [selected];
+          } else if (question.multiSelect && choices.length) {
+            answers[question.id] = [];
+            for (const choice of choices) {
+              if (signal?.aborted) break;
+              if (await ctx.ui.confirm(question.question, "Select: " + choice, { signal, timeout: ASK_TIMEOUT_MS })) answers[question.id].push(choice);
+            }
+            if (question.allowCustom) {
+              const value = await ctx.ui.input(question.question, "Optional additional response", { signal, timeout: ASK_TIMEOUT_MS });
+              if (value?.trim()) answers[question.id].push(value);
+            }
+          } else {
+            const value = await ctx.ui.input(title, question.placeholder, { signal, timeout: ASK_TIMEOUT_MS });
+            if (value === undefined) break;
+            answers[question.id] = [value];
+          }
+        }
+        const complete = !signal?.aborted && questions.every(question => question.id in answers);
+        return { content: [{ type: "text", text: complete ? formatAnswers(questions, answers) : "The user dismissed the question in Pi Companion." }], details: { questions, answers: complete ? answers : null } };
+      }
       if (!bridge.isActivated()) {
         return {
           content: [{ type: "text", text: "Pi Companion is not enabled for this session. Run /companion before asking through the dashboard." }],

package/src/protocol.ts

@@ -61,6 +61,7 @@ export type SessionSnapshot = {
   effort?: string | null;
   telemetry?: SessionTelemetry;
   remoteEnabled: boolean;
+  commands?: { name: string; description?: string; source: 'extension' | 'prompt' | 'skill' }[];
   connectedAt: string;
   /** Questions waiting for an answer. Kept in the snapshot so late-joining browsers see them. */
   asks: AskRequest[];