Initial commit

Supervised action bridge between Claude Code and the host system.
Server accepts structured action requests, applies per-action policies
(auto-accept/auto-deny/queue), and executes approved actions via typed
handlers. Client provides CLI and module interfaces for calling the API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

server/actions.js

@@ -0,0 +1,61 @@
+// Action registry — defines all available actions, their parameters, and policies.
+// policy: "auto-accept" | "auto-deny" | "queue"
+
+export const actions = {
+	"list-actions": {
+		description: "List all available actions and their definitions",
+		params: [],
+		policy: "auto-accept",
+		handler: async () => {
+			return Object.entries(actions).map(([name, def]) => ({
+				action: name,
+				description: def.description,
+				params: def.params,
+				policy: def.policy,
+			}));
+		},
+	},
+
+	"edit-file": {
+		description: "Open a file in the editor",
+		params: [{ name: "filename", required: true, type: "path" }],
+		policy: "auto-accept",
+		handler: async ({ filename }, { resolvePath, exec }) => {
+			const resolved = resolvePath(filename);
+			await exec("xdg-open", [resolved]);
+			return { opened: resolved };
+		},
+	},
+
+	"open-directory": {
+		description: "Open a directory in the file manager",
+		params: [{ name: "path", required: true, type: "path" }],
+		policy: "auto-accept",
+		handler: async ({ path }, { resolvePath, exec }) => {
+			const resolved = resolvePath(path);
+			await exec("xdg-open", [resolved]);
+			return { opened: resolved };
+		},
+	},
+
+	"open-browser": {
+		description: "Open a URL in the web browser",
+		params: [{ name: "url", required: true, type: "string" }],
+		policy: "queue",
+		handler: async ({ url }, { exec }) => {
+			await exec("xdg-open", [url]);
+			return { opened: url };
+		},
+	},
+
+	"open-terminal": {
+		description: "Open a terminal in a given directory",
+		params: [{ name: "path", required: false, type: "path" }],
+		policy: "queue",
+		handler: async ({ path }, { resolvePath, exec }) => {
+			const resolved = path ? resolvePath(path) : process.env.HOME;
+			await exec("xdg-open", [resolved]);
+			return { opened: resolved };
+		},
+	},
+};

server/index.js

@@ -0,0 +1,127 @@
+import express from "express";
+import { spawnSync } from "child_process";
+import path from "path";
+import { actions } from "./actions.js";
+import { enqueue, getEntry, listPending, resolve } from "./queue.js";
+
+const PORT = process.env.CONDUIT_PORT || 3015;
+const WORKSPACE_ROOT = process.env.CONDUIT_ROOT || "/workspace";
+
+const app = express();
+app.use(express.json());
+
+// Resolve a path param relative to WORKSPACE_ROOT, preventing traversal.
+function resolvePath(userPath) {
+	const resolved = path.resolve(WORKSPACE_ROOT, userPath.replace(/^\//, ""));
+	if (!resolved.startsWith(WORKSPACE_ROOT)) {
+		throw new Error(`Path escapes workspace root: ${userPath}`);
+	}
+	return resolved;
+}
+
+// Execute a binary with an argument list — no shell interpolation.
+function exec(bin, args = []) {
+	return new Promise((resolve, reject) => {
+		const result = spawnSync(bin, args, { stdio: "inherit" });
+		if (result.error) {
+			reject(result.error);
+		} else {
+			resolve(result.status);
+		}
+	});
+}
+
+const helpers = { resolvePath, exec };
+
+// Validate that all required params are present.
+function validateParams(actionDef, params) {
+	const errors = [];
+	for (const p of actionDef.params) {
+		if (p.required && (params[p.name] === undefined || params[p.name] === null)) {
+			errors.push(`Missing required param: ${p.name}`);
+		}
+	}
+	return errors;
+}
+
+// POST /action  — main entry point
+app.post("/action", async (req, res) => {
+	const { action, ...params } = req.body ?? {};
+
+	if (!action) {
+		return res.status(400).json({ error: "Missing 'action' field" });
+	}
+
+	const def = actions[action];
+	if (!def) {
+		return res.status(404).json({ error: `Unknown action: ${action}` });
+	}
+
+	const errors = validateParams(def, params);
+	if (errors.length) {
+		return res.status(400).json({ error: "Invalid params", details: errors });
+	}
+
+	if (def.policy === "auto-deny") {
+		return res.status(403).json({ status: "denied", reason: "Policy: auto-deny" });
+	}
+
+	if (def.policy === "auto-accept") {
+		try {
+			const result = await def.handler(params, helpers);
+			return res.json({ status: "accepted", result });
+		} catch (err) {
+			return res.status(500).json({ status: "error", error: err.message });
+		}
+	}
+
+	if (def.policy === "queue") {
+		const id = enqueue(action, params);
+		return res.status(202).json({ status: "queued", id });
+	}
+});
+
+// GET /queue — list pending items
+app.get("/queue", (req, res) => {
+	res.json(listPending());
+});
+
+// POST /queue/:id/approve — user approves a queued action
+app.post("/queue/:id/approve", async (req, res) => {
+	const entry = getEntry(req.params.id);
+	if (!entry) {
+		return res.status(404).json({ error: "Not found" });
+	}
+	if (entry.status !== "pending") {
+		return res.status(409).json({ error: "Already resolved" });
+	}
+
+	resolve(req.params.id, "approved");
+
+	const def = actions[entry.action];
+	try {
+		const result = await def.handler(entry.params, helpers);
+		res.json({ status: "approved", result });
+	} catch (err) {
+		res.status(500).json({ status: "error", error: err.message });
+	}
+});
+
+// POST /queue/:id/deny — user denies a queued action
+app.post("/queue/:id/deny", (req, res) => {
+	const entry = getEntry(req.params.id);
+	if (!entry) {
+		return res.status(404).json({ error: "Not found" });
+	}
+	if (entry.status !== "pending") {
+		return res.status(409).json({ error: "Already resolved" });
+	}
+
+	resolve(req.params.id, "denied");
+	res.json({ status: "denied" });
+});
+
+app.listen(PORT, () => {
+	console.log(`claude-code-conduit server running on port ${PORT}`);
+	console.log(`Workspace root: ${WORKSPACE_ROOT}`);
+});

server/queue.js

@@ -0,0 +1,41 @@
+// Pending queue — holds actions awaiting user approval.
+
+import { randomUUID } from "crypto";
+
+const pending = new Map();
+
+export function enqueue(action, params) {
+	const id = randomUUID();
+	const entry = {
+		id,
+		action,
+		params,
+		status: "pending",
+		createdAt: new Date().toISOString(),
+	};
+	pending.set(id, entry);
+	console.log(`\n[QUEUE] New request #${id.slice(0, 8)}`);
+	console.log(`  Action: ${action}`);
+	console.log(`  Params: ${JSON.stringify(params)}`);
+	console.log(`  Approve: POST /queue/${id}/approve`);
+	console.log(`  Deny:    POST /queue/${id}/deny\n`);
+	return id;
+}
+
+export function getEntry(id) {
+	return pending.get(id) ?? null;
+}
+
+export function listPending() {
+	return [...pending.values()].filter((e) => e.status === "pending");
+}
+
+export function resolve(id, decision) {
+	const entry = pending.get(id);
+	if (!entry) {
+		return null;
+	}
+	entry.status = decision; // "approved" | "denied"
+	entry.resolvedAt = new Date().toISOString();
+	return entry;
+}