@puddle-code/cli 0.2.24 → 0.3.0

package/CHANGELOG.md

@@ -4,8 +4,12 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
 
 # Changelog
 
-## [0.2.24] — 2026-10-14
+## [0.3.0] — 2026-10-14
 
-### Fixed
+### Added
 
-- macOS releases without signing secrets unset the empty certificate environment before ad-hoc packaging, preventing electron-builder from treating the desktop directory as a certificate file. Desktop packaging leaves publication to the release job.
+- Add puddlang: host-executed TypeScript agent workflows, Codex exact turns and structured replies, profile/account selection, durable run records, cancellation, CLI and stdio MCP access; bundle `puddlang` with existing CLI installers (daemon protocol 23.0, remote protocol unchanged).
+
+### Changed
+
+- Bump daemon/cockpit protocol to 23.0 for the puddlang rollout; require matching clients and hosts through the existing approved upgrade flow, while retaining remote transport protocol 3.

package/README.md

@@ -29,6 +29,10 @@ installer (replace the example host):
 curl -fsSL https://app.example.com/install.sh | sh
 ```
 
+The CLI also includes `puddlang`, a TypeScript interface for coder/reviewer loops
+and other agent workflows, available through the shell or stdio MCP. See the
+[puddlang guide](docs/puddlang.md) for setup, examples and initial limitations.
+
 This installs the CLI under `~/.local/share/puddle/cli` and its launcher at
 `~/.local/bin/puddle`. Add `~/.local/bin` to your `PATH` if the installer asks.
 The standalone releases support Linux x64/arm64 and macOS arm64. The script and

package/dist/host-control.mjs

@@ -16188,6 +16188,153 @@ var connectorNotificationSchema = external_exports.object({
 var pushDispatchResultSchema = external_exports.object({ accepted: external_exports.number().int().nonnegative(), failed: external_exports.number().int().nonnegative() }).strict();
 var pushPreferenceResultSchema = external_exports.object({ enabled: external_exports.boolean() }).strict();
 
+// ../shared/src/api/puddlang.ts
+var PUDDLANG_MAX_SOURCE = 256 * 1024;
+var sourceSchema = external_exports.string().min(1).max(PUDDLANG_MAX_SOURCE).refine(
+  (source) => new TextEncoder().encode(source).length <= PUDDLANG_MAX_SOURCE,
+  "Source exceeds 256 KiB"
+);
+var puddlangSpawnSchema = external_exports.object({
+  agent: external_exports.string().min(1).max(100),
+  account: external_exports.union([external_exports.string().min(1).max(100), external_exports.number().int().positive()]).optional(),
+  project: external_exports.string().min(1).max(200).optional(),
+  worktree: external_exports.string().min(1).max(4096).optional(),
+  path: external_exports.string().min(1).max(4096).optional(),
+  title: external_exports.string().min(1).max(200).optional()
+}).refine((v) => Boolean(v.path) !== Boolean(v.project), "Choose path or project").refine((v) => !v.path || !v.worktree, "worktree requires project");
+var puddlangHandleSchema = external_exports.object({ runtime_id: external_exports.uuid(), session_id: sessionId });
+var puddlangAskSchema = external_exports.object({
+  prompt: external_exports.string().min(1).max(128 * 1024),
+  output_schema: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangStartSchema = external_exports.object({
+  id: external_exports.uuid(),
+  source: sourceSchema,
+  input: external_exports.unknown().optional(),
+  accounts: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number().int().positive()])).default({}),
+  max_turns: external_exports.number().int().min(1).max(1e3).default(50),
+  max_agents: external_exports.number().int().min(1).max(32).default(8),
+  timeout_ms: external_exports.number().int().min(1e3).max(24 * 60 * 60 * 1e3).default(60 * 60 * 1e3)
+});
+var puddlangRunSchema = external_exports.object({
+  id: external_exports.uuid(),
+  profile_id: profileId,
+  source_hash: external_exports.string(),
+  status: external_exports.enum(["running", "completed", "failed", "cancelled", "interrupted"]),
+  result: external_exports.unknown().nullable(),
+  error: external_exports.string().nullable(),
+  created_at: external_exports.string(),
+  updated_at: external_exports.string()
+});
+var puddlangEventSchema = external_exports.object({
+  sequence: external_exports.number().int(),
+  run_id: external_exports.uuid(),
+  type: external_exports.string(),
+  data: external_exports.unknown(),
+  created_at: external_exports.string()
+});
+var puddlangEventsSchema = external_exports.object({ events: external_exports.array(puddlangEventSchema) });
+var puddlangOperationSchema = external_exports.discriminatedUnion("op", [
+  external_exports.object({ op: external_exports.literal("spawn"), options: puddlangSpawnSchema }),
+  external_exports.object({ op: external_exports.literal("attach"), reference: external_exports.string().min(1).max(100) }),
+  external_exports.object({ op: external_exports.literal("ask"), handle: puddlangHandleSchema, request: puddlangAskSchema }),
+  external_exports.object({ op: external_exports.literal("stop"), handle: puddlangHandleSchema })
+]);
+var puddlangRunnerMessageSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("operation"),
+    id: external_exports.number().int(),
+    operation: puddlangOperationSchema
+  }),
+  external_exports.object({
+    type: external_exports.literal("finished"),
+    result: external_exports.unknown().optional(),
+    error: external_exports.string().max(8192).optional()
+  })
+]);
+var puddlangRunnerInputSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("start"),
+    source: sourceSchema,
+    input: external_exports.unknown().optional()
+  }),
+  external_exports.object({
+    type: external_exports.literal("reply"),
+    id: external_exports.number().int(),
+    value: external_exports.unknown().optional(),
+    error: external_exports.string().optional()
+  })
+]);
+var puddlangContextSchema = external_exports.object({
+  profile: external_exports.object({ id: profileId, name: external_exports.string() }),
+  projects: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), path: external_exports.string() })),
+  accounts: external_exports.array(
+    external_exports.object({ id: external_exports.number(), label: external_exports.string(), agent: external_exports.string(), logged_in: external_exports.boolean() })
+  ),
+  agents: external_exports.array(external_exports.object({ id: external_exports.string(), scripted_turns: external_exports.boolean() }))
+});
+
+// ../shared/src/api/puddlang-mcp.ts
+var puddlangMcpRequestSchema = external_exports.object({
+  jsonrpc: external_exports.literal("2.0"),
+  id: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+  method: external_exports.string(),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangMcpCallSchema = external_exports.object({
+  name: external_exports.string(),
+  arguments: external_exports.unknown().optional()
+});
+var puddlangMcpRunSchema = puddlangStartSchema;
+var puddlangMcpIdSchema = external_exports.object({ id: external_exports.uuid() });
+var puddlangMcpEventsSchema = puddlangMcpIdSchema.extend({
+  after: external_exports.number().int().nonnegative().default(0)
+});
+var puddlangMcpEmptySchema = external_exports.object({}).strict();
+var definitions = [
+  [
+    "puddlang_context",
+    "List this host profile, projects, accounts and supported agents.",
+    puddlangMcpEmptySchema,
+    true
+  ],
+  [
+    "puddlang_run",
+    'Execute a trusted single-file TypeScript programme on the host. Imports: puddlang (spawn, attach, input, z), zod, node: built-ins. Returns immediately with a durable run id; use status/events. Supply a fresh UUID id, or reuse it with identical input to recover an uncertain submission. spawn({agent:"codex",project:"name",account:"label"}); await agent.ask("task"); export default result. Supports structured ask({prompt,input,schema:z.object(...)}) and agent.stop().',
+    puddlangMcpRunSchema,
+    false
+  ],
+  [
+    "puddlang_status",
+    "Read a run and its final default export, if finished.",
+    puddlangMcpIdSchema,
+    true
+  ],
+  [
+    "puddlang_events",
+    "Read up to 100 events after a sequence; paginate until empty.",
+    puddlangMcpEventsSchema,
+    true
+  ],
+  [
+    "puddlang_cancel",
+    "Cancel a run, interrupt its pending asks, and stop agents it created. Attached agents are retained.",
+    puddlangMcpIdSchema,
+    false
+  ]
+];
+var puddlangMcpTools = definitions.map(([name, description, schema, readOnlyHint]) => ({
+  name,
+  description,
+  inputSchema: external_exports.toJSONSchema(schema, { io: "input" }),
+  annotations: {
+    readOnlyHint,
+    destructiveHint: !readOnlyHint,
+    idempotentHint: true,
+    openWorldHint: !readOnlyHint
+  }
+}));
+
 // ../shared/src/node/security.ts
 import { createHash, randomBytes } from "node:crypto";
 import {

package/dist/index.js

@@ -3925,7 +3925,7 @@ import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
 
 // ../shared/src/protocol.ts
-var PROTOCOL_VERSION = { major: 22, minor: 5 };
+var PROTOCOL_VERSION = { major: 23, minor: 0 };
 
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -20108,6 +20108,153 @@ var connectorNotificationSchema = external_exports.object({
 var pushDispatchResultSchema = external_exports.object({ accepted: external_exports.number().int().nonnegative(), failed: external_exports.number().int().nonnegative() }).strict();
 var pushPreferenceResultSchema = external_exports.object({ enabled: external_exports.boolean() }).strict();
 
+// ../shared/src/api/puddlang.ts
+var PUDDLANG_MAX_SOURCE = 256 * 1024;
+var sourceSchema = external_exports.string().min(1).max(PUDDLANG_MAX_SOURCE).refine(
+  (source) => new TextEncoder().encode(source).length <= PUDDLANG_MAX_SOURCE,
+  "Source exceeds 256 KiB"
+);
+var puddlangSpawnSchema = external_exports.object({
+  agent: external_exports.string().min(1).max(100),
+  account: external_exports.union([external_exports.string().min(1).max(100), external_exports.number().int().positive()]).optional(),
+  project: external_exports.string().min(1).max(200).optional(),
+  worktree: external_exports.string().min(1).max(4096).optional(),
+  path: external_exports.string().min(1).max(4096).optional(),
+  title: external_exports.string().min(1).max(200).optional()
+}).refine((v) => Boolean(v.path) !== Boolean(v.project), "Choose path or project").refine((v) => !v.path || !v.worktree, "worktree requires project");
+var puddlangHandleSchema = external_exports.object({ runtime_id: external_exports.uuid(), session_id: sessionId });
+var puddlangAskSchema = external_exports.object({
+  prompt: external_exports.string().min(1).max(128 * 1024),
+  output_schema: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangStartSchema = external_exports.object({
+  id: external_exports.uuid(),
+  source: sourceSchema,
+  input: external_exports.unknown().optional(),
+  accounts: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number().int().positive()])).default({}),
+  max_turns: external_exports.number().int().min(1).max(1e3).default(50),
+  max_agents: external_exports.number().int().min(1).max(32).default(8),
+  timeout_ms: external_exports.number().int().min(1e3).max(24 * 60 * 60 * 1e3).default(60 * 60 * 1e3)
+});
+var puddlangRunSchema = external_exports.object({
+  id: external_exports.uuid(),
+  profile_id: profileId,
+  source_hash: external_exports.string(),
+  status: external_exports.enum(["running", "completed", "failed", "cancelled", "interrupted"]),
+  result: external_exports.unknown().nullable(),
+  error: external_exports.string().nullable(),
+  created_at: external_exports.string(),
+  updated_at: external_exports.string()
+});
+var puddlangEventSchema = external_exports.object({
+  sequence: external_exports.number().int(),
+  run_id: external_exports.uuid(),
+  type: external_exports.string(),
+  data: external_exports.unknown(),
+  created_at: external_exports.string()
+});
+var puddlangEventsSchema = external_exports.object({ events: external_exports.array(puddlangEventSchema) });
+var puddlangOperationSchema = external_exports.discriminatedUnion("op", [
+  external_exports.object({ op: external_exports.literal("spawn"), options: puddlangSpawnSchema }),
+  external_exports.object({ op: external_exports.literal("attach"), reference: external_exports.string().min(1).max(100) }),
+  external_exports.object({ op: external_exports.literal("ask"), handle: puddlangHandleSchema, request: puddlangAskSchema }),
+  external_exports.object({ op: external_exports.literal("stop"), handle: puddlangHandleSchema })
+]);
+var puddlangRunnerMessageSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("operation"),
+    id: external_exports.number().int(),
+    operation: puddlangOperationSchema
+  }),
+  external_exports.object({
+    type: external_exports.literal("finished"),
+    result: external_exports.unknown().optional(),
+    error: external_exports.string().max(8192).optional()
+  })
+]);
+var puddlangRunnerInputSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("start"),
+    source: sourceSchema,
+    input: external_exports.unknown().optional()
+  }),
+  external_exports.object({
+    type: external_exports.literal("reply"),
+    id: external_exports.number().int(),
+    value: external_exports.unknown().optional(),
+    error: external_exports.string().optional()
+  })
+]);
+var puddlangContextSchema = external_exports.object({
+  profile: external_exports.object({ id: profileId, name: external_exports.string() }),
+  projects: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), path: external_exports.string() })),
+  accounts: external_exports.array(
+    external_exports.object({ id: external_exports.number(), label: external_exports.string(), agent: external_exports.string(), logged_in: external_exports.boolean() })
+  ),
+  agents: external_exports.array(external_exports.object({ id: external_exports.string(), scripted_turns: external_exports.boolean() }))
+});
+
+// ../shared/src/api/puddlang-mcp.ts
+var puddlangMcpRequestSchema = external_exports.object({
+  jsonrpc: external_exports.literal("2.0"),
+  id: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+  method: external_exports.string(),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangMcpCallSchema = external_exports.object({
+  name: external_exports.string(),
+  arguments: external_exports.unknown().optional()
+});
+var puddlangMcpRunSchema = puddlangStartSchema;
+var puddlangMcpIdSchema = external_exports.object({ id: external_exports.uuid() });
+var puddlangMcpEventsSchema = puddlangMcpIdSchema.extend({
+  after: external_exports.number().int().nonnegative().default(0)
+});
+var puddlangMcpEmptySchema = external_exports.object({}).strict();
+var definitions = [
+  [
+    "puddlang_context",
+    "List this host profile, projects, accounts and supported agents.",
+    puddlangMcpEmptySchema,
+    true
+  ],
+  [
+    "puddlang_run",
+    'Execute a trusted single-file TypeScript programme on the host. Imports: puddlang (spawn, attach, input, z), zod, node: built-ins. Returns immediately with a durable run id; use status/events. Supply a fresh UUID id, or reuse it with identical input to recover an uncertain submission. spawn({agent:"codex",project:"name",account:"label"}); await agent.ask("task"); export default result. Supports structured ask({prompt,input,schema:z.object(...)}) and agent.stop().',
+    puddlangMcpRunSchema,
+    false
+  ],
+  [
+    "puddlang_status",
+    "Read a run and its final default export, if finished.",
+    puddlangMcpIdSchema,
+    true
+  ],
+  [
+    "puddlang_events",
+    "Read up to 100 events after a sequence; paginate until empty.",
+    puddlangMcpEventsSchema,
+    true
+  ],
+  [
+    "puddlang_cancel",
+    "Cancel a run, interrupt its pending asks, and stop agents it created. Attached agents are retained.",
+    puddlangMcpIdSchema,
+    false
+  ]
+];
+var puddlangMcpTools = definitions.map(([name, description, schema, readOnlyHint]) => ({
+  name,
+  description,
+  inputSchema: external_exports.toJSONSchema(schema, { io: "input" }),
+  annotations: {
+    readOnlyHint,
+    destructiveHint: !readOnlyHint,
+    idempotentHint: true,
+    openWorldHint: !readOnlyHint
+  }
+}));
+
 // src/lib/transport/local.ts
 import { spawn } from "node:child_process";
 import { copyFileSync, mkdirSync, readFileSync } from "node:fs";
@@ -21646,7 +21793,7 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { dirname as dirname4, join as join5 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function cliVersion() {
-  if (true) return "0.2.24";
+  if (true) return "0.3.0";
   const here = dirname4(fileURLToPath2(import.meta.url));
   for (const candidate of [
     join5(here, "..", "..", "package.json"),
@@ -22043,7 +22190,8 @@ var RELEASE_PROTOCOLS = {
   "0.2.21": { major: 22, minor: 4 },
   "0.2.22": { major: 22, minor: 4 },
   "0.2.23": { major: 22, minor: 5 },
-  "0.2.24": { major: 22, minor: 5 }
+  "0.2.24": { major: 22, minor: 5 },
+  "0.3.0": { major: 23, minor: 0 }
 };
 function validProtocol(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -24313,9 +24461,14 @@ function standaloneInstallation(entryFile = fileURLToPath4(import.meta.url), exe
   try {
     const root = resolve5(release, "..", "..");
     const record2 = JSON.parse(readFileSync9(join15(root, "installation.json"), "utf8"));
-    if (readFileSync9(join15(release, "STANDALONE"), "utf8").trim() !== "puddle-cli" || readFileSync9(join15(root, "INSTALLATION"), "utf8").trim() !== "puddle-cli" || dirname9(release) !== join15(root, "versions") || realpathSync2(release) !== release || realpathSync2(execPath) !== join15(release, "bin/node") || record2.kind !== "puddle-cli" || typeof record2.launcher !== "string" || !isAbsolute(record2.launcher))
+    if (readFileSync9(join15(release, "STANDALONE"), "utf8").trim() !== "puddle-cli" || readFileSync9(join15(root, "INSTALLATION"), "utf8").trim() !== "puddle-cli" || dirname9(release) !== join15(root, "versions") || realpathSync2(release) !== release || realpathSync2(execPath) !== join15(release, "bin/node") || record2.kind !== "puddle-cli" || typeof record2.launcher !== "string" || !isAbsolute(record2.launcher) || record2.scriptLauncher !== void 0 && record2.scriptLauncher !== join15(dirname9(record2.launcher), "puddlang"))
       throw new Error("Installation metadata does not match this CLI");
-    return { root, release, launcher: record2.launcher };
+    return {
+      root,
+      release,
+      launcher: record2.launcher,
+      ...typeof record2.scriptLauncher === "string" ? { scriptLauncher: record2.scriptLauncher } : {}
+    };
   } catch {
     throw new CliError(
       "not_installed",
@@ -24349,8 +24502,8 @@ function upgradeStandaloneCli(installation, version2, repo) {
     });
   });
 }
-function standaloneLauncher(root) {
-  const quoted = `'${join15(root, "current/puddle").replaceAll("'", "'\\''")}'`;
+function standaloneLauncher(root, command = "puddle") {
+  const quoted = `'${join15(root, `current/${command}`).replaceAll("'", "'\\''")}'`;
   return `#!/bin/sh
 # puddle standalone launcher
 exec ${quoted} "$@"
@@ -24366,6 +24519,11 @@ async function removeStandaloneCli(installation) {
   try {
     if (lstatSync2(installation.launcher).isSymbolicLink() || await readFile2(installation.launcher, "utf8") !== standaloneLauncher(installation.root))
       throw new CliError("not_installed", "the CLI launcher was replaced; refusing removal");
+    if (installation.scriptLauncher && existsSync5(installation.scriptLauncher)) {
+      if (!lstatSync2(installation.scriptLauncher).isFile() || await readFile2(installation.scriptLauncher, "utf8") !== standaloneLauncher(installation.root, "puddlang"))
+        throw new CliError("not_installed", "the puddlang launcher was replaced; refusing removal");
+      await unlink(installation.scriptLauncher);
+    }
     await unlink(installation.launcher);
     await rm2(installation.root, { recursive: true, force: true });
   } finally {

package/dist/install-cli.sh

@@ -125,16 +125,24 @@ main() {
   done
   # Help loads the bundle without touching a daemon or user state.
   "$STAGE/puddle" --help >/dev/null || die "CLI smoke test failed"
+  if [ -f "$STAGE/puddlang" ]; then
+    "$STAGE/puddlang" --help >/dev/null || die "puddlang smoke test failed"
+  fi
   "$STAGE/bin/node" --input-type=commonjs - "$PREFIX" "$BIN_DIR" "$STAGE" <<'NODE'
 const fs = require('node:fs'), path = require('node:path');
 const [root, binDir, stage] = process.argv.slice(2);
 const launcher = path.join(binDir, 'puddle');
 const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
 const wrapper = '#!/bin/sh\n# puddle standalone launcher\nexec ' + quote(path.join(root, 'current/puddle')) + ' "$@"\n';
+const scriptLauncher = path.join(binDir, 'puddlang');
+const scriptWrapper = '#!/bin/sh\n# puddle standalone launcher\nexec ' + quote(path.join(root, 'current/puddlang')) + ' "$@"\n';
+const hasScript = fs.existsSync(path.join(stage, 'puddlang'));
 const stat = (p) => { try { return fs.lstatSync(p); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } };
 if (stat(launcher) && (!stat(launcher).isFile() || fs.readFileSync(launcher, 'utf8') !== wrapper)) {
   throw Error('Refusing to replace an unrelated launcher: ' + launcher + '; choose --bin-dir');
 }
+const ownsScript = stat(scriptLauncher)?.isFile() && fs.readFileSync(scriptLauncher, 'utf8') === scriptWrapper;
+if (hasScript && stat(scriptLauncher) && !ownsScript) throw Error('Refusing to replace an unrelated launcher: ' + scriptLauncher + '; choose --bin-dir');
 const current = path.join(root, 'current');
 if (stat(current) && !stat(current).isSymbolicLink()) throw Error('current must be a symlink');
 const record = path.join(root, 'installation.json');
@@ -144,14 +152,17 @@ if (stat(record)) {
 }
 const tmp = '.new-' + process.pid;
 try {
-  fs.writeFileSync(record + tmp, JSON.stringify({ kind: 'puddle-cli', launcher }) + '\n', { flag: 'wx', mode: 0o600 });
+  fs.writeFileSync(record + tmp, JSON.stringify({ kind: 'puddle-cli', launcher, ...(hasScript ? { scriptLauncher } : {}) }) + '\n', { flag: 'wx', mode: 0o600 });
   fs.writeFileSync(launcher + tmp, wrapper, { flag: 'wx', mode: 0o755 });
+  if (hasScript) fs.writeFileSync(scriptLauncher + tmp, scriptWrapper, { flag: 'wx', mode: 0o755 });
   fs.symlinkSync(path.relative(root, stage), current + tmp);
   fs.renameSync(record + tmp, record);
   fs.renameSync(launcher + tmp, launcher);
+  if (hasScript) fs.renameSync(scriptLauncher + tmp, scriptLauncher);
   fs.renameSync(current + tmp, current); // Activate only after every other write succeeds.
+  if (!hasScript && ownsScript) fs.unlinkSync(scriptLauncher); // Named older releases remain installable.
 } finally {
-  for (const file of [record + tmp, launcher + tmp, current + tmp]) fs.rmSync(file, { force: true });
+  for (const file of [record + tmp, launcher + tmp, scriptLauncher + tmp, current + tmp]) fs.rmSync(file, { force: true });
 }
 NODE
   STAGE="" # Published releases stay intact, including those serving live cockpits.