@puddle-code/cli 0.2.21 → 0.3.0

package/CHANGELOG.md

@@ -4,9 +4,12 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
 
 # Changelog
 
-## [0.2.21] — 2026-10-14
+## [0.3.0] — 2026-10-14
 
-### Fixed
+### Added
 
-- Align the shared API protocol assertion with protocol 22.4 so CI accepts the remote push notification changes.
-- Publish the npm CLI through GitHub OIDC trusted publishing with a compatible npm version instead of relying on a stored publishing token.
+- 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

@@ -14521,6 +14521,21 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// ../shared/src/api/common.ts
+var errorResponseSchema = external_exports.object({
+  error: external_exports.object({
+    code: external_exports.string(),
+    message: external_exports.string(),
+    /** Optional machine-readable context for recoverable conflicts. */
+    details: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+  })
+});
+var isoTimestamp = external_exports.iso.datetime({ offset: true });
+var rowId = external_exports.number().int().positive();
+var sessionId = external_exports.uuid();
+var projectId = external_exports.string().regex(/^[0-9a-f]{10}$/);
+var profileId = external_exports.string().regex(/^[0-9a-f]{10}$/);
+
 // ../shared/src/notifications.ts
 var notificationPreferencesSchema = external_exports.object({
   desktop: external_exports.boolean().default(true),
@@ -14528,10 +14543,22 @@ var notificationPreferencesSchema = external_exports.object({
   when_focused: external_exports.boolean().default(true),
   muted_projects: external_exports.array(external_exports.string()).default([])
 });
+var notificationTargetSchema = external_exports.object({
+  project: projectId,
+  session: sessionId,
+  host: external_exports.string().uuid().optional()
+}).strict();
+var notificationContentSchema = external_exports.object({
+  title: external_exports.string().min(1).max(160),
+  body: external_exports.string().min(1).max(256),
+  project: projectId,
+  session: sessionId
+}).strict();
 var desktopNotificationRequestSchema = external_exports.object({
   id: external_exports.string().min(1).max(128),
   title: external_exports.string().min(1).max(160),
-  body: external_exports.string().min(1).max(256)
+  body: external_exports.string().min(1).max(256),
+  target: notificationTargetSchema.optional()
 }).strict();
 var notificationDeliverySchema = external_exports.object({
   state: external_exports.enum(["unverified", "shown", "failed", "unsupported"]),
@@ -14541,29 +14568,16 @@ var agentNotificationSchema = external_exports.object({
   t: external_exports.literal("agent-notification"),
   id: external_exports.string().uuid(),
   session: external_exports.string().uuid(),
-  reason: external_exports.enum(["waiting_input", "exited"])
+  reason: external_exports.enum(["waiting_input", "exited"]),
+  content: notificationContentSchema.optional()
 });
 
-// ../shared/src/api/common.ts
-var errorResponseSchema = external_exports.object({
-  error: external_exports.object({
-    code: external_exports.string(),
-    message: external_exports.string(),
-    /** Optional machine-readable context for recoverable conflicts. */
-    details: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
-  })
-});
-var isoTimestamp = external_exports.iso.datetime({ offset: true });
-var rowId = external_exports.number().int().positive();
-var sessionId = external_exports.uuid();
-var projectId = external_exports.string().regex(/^[0-9a-f]{10}$/);
-var profileId = external_exports.string().regex(/^[0-9a-f]{10}$/);
-
 // ../shared/src/api/version.ts
 var versionResponseSchema = external_exports.object({
   version: external_exports.string(),
   /** Added by the host connector; absent on direct daemon responses and older connectors. */
   remote_notifications: external_exports.boolean().optional(),
+  remote_notification_previews: external_exports.boolean().optional(),
   remote_image_uploads: external_exports.boolean().optional(),
   protocol: external_exports.object({
     major: external_exports.number().int().nonnegative(),
@@ -15932,6 +15946,7 @@ var remoteHostSchema = external_exports.object({
 var remoteHostsSchema = external_exports.array(remoteHostSchema);
 var remoteServiceInfoSchema = external_exports.object({
   push_public_key: external_exports.string().max(100).optional(),
+  push_encrypted_previews: external_exports.boolean().optional(),
   providers: external_exports.array(external_exports.enum(["google", "github"])),
   protocol: external_exports.literal(REMOTE_PROTOCOL_VERSION)
 });
@@ -16125,6 +16140,12 @@ var imageUploadProgressSchema = external_exports.object({
 });
 
 // ../shared/src/remote/notifications.ts
+var notificationPreviewKeySchema = external_exports.object({ id: remoteIdSchema, secret: remoteSecretSchema }).strict();
+var encryptedNotificationSchema = external_exports.object({
+  key: remoteIdSchema,
+  iv: external_exports.string().regex(/^[a-f0-9]{24}$/),
+  ciphertext: external_exports.string().min(32).max(3072).regex(/^(?:[a-f0-9]{2})+$/)
+}).strict();
 var pushEndpointSchema = external_exports.string().max(2048).url().refine((value) => {
   let url2;
   try {
@@ -16143,18 +16164,177 @@ var pushSubscriptionSchema = external_exports.object({
     auth: external_exports.string().regex(/^[A-Za-z0-9_-]{22}={0,2}$/)
   }).strict()
 }).strict();
-var pushPreferenceSchema = external_exports.object({ subscription: pushSubscriptionSchema.nullable() }).strict();
-var pushRegistrationSchema = pushPreferenceSchema.extend({ credential: remoteSecretSchema, device: remoteIdSchema }).strict();
+var pushPreferenceSchema = external_exports.object({
+  subscription: pushSubscriptionSchema.nullable(),
+  preview_key: notificationPreviewKeySchema.optional()
+}).strict();
+var pushRegistrationSchema = pushPreferenceSchema.omit({ preview_key: true }).extend({ credential: remoteSecretSchema, device: remoteIdSchema }).strict();
 var pushDispatchSchema = external_exports.object({
   credential: remoteSecretSchema,
   devices: external_exports.array(remoteIdSchema).min(1).max(64),
-  id: remoteIdSchema
+  id: remoteIdSchema,
+  preview: encryptedNotificationSchema.optional()
+}).strict();
+var pushPayloadSchema = external_exports.object({
+  id: remoteIdSchema,
+  host: remoteIdSchema,
+  preview: encryptedNotificationSchema.optional()
+}).strict();
+var connectorNotificationSchema = external_exports.object({
+  t: external_exports.literal("notify"),
+  id: remoteIdSchema,
+  content: notificationContentSchema.optional()
 }).strict();
-var pushPayloadSchema = external_exports.object({ id: remoteIdSchema, host: remoteIdSchema }).strict();
-var connectorNotificationSchema = external_exports.object({ t: external_exports.literal("notify"), id: remoteIdSchema }).strict();
 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: 4 };
+var PROTOCOL_VERSION = { major: 23, minor: 0 };
 
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -18441,6 +18441,21 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// ../shared/src/api/common.ts
+var errorResponseSchema = external_exports.object({
+  error: external_exports.object({
+    code: external_exports.string(),
+    message: external_exports.string(),
+    /** Optional machine-readable context for recoverable conflicts. */
+    details: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+  })
+});
+var isoTimestamp = external_exports.iso.datetime({ offset: true });
+var rowId = external_exports.number().int().positive();
+var sessionId = external_exports.uuid();
+var projectId = external_exports.string().regex(/^[0-9a-f]{10}$/);
+var profileId = external_exports.string().regex(/^[0-9a-f]{10}$/);
+
 // ../shared/src/notifications.ts
 var notificationPreferencesSchema = external_exports.object({
   desktop: external_exports.boolean().default(true),
@@ -18448,10 +18463,22 @@ var notificationPreferencesSchema = external_exports.object({
   when_focused: external_exports.boolean().default(true),
   muted_projects: external_exports.array(external_exports.string()).default([])
 });
+var notificationTargetSchema = external_exports.object({
+  project: projectId,
+  session: sessionId,
+  host: external_exports.string().uuid().optional()
+}).strict();
+var notificationContentSchema = external_exports.object({
+  title: external_exports.string().min(1).max(160),
+  body: external_exports.string().min(1).max(256),
+  project: projectId,
+  session: sessionId
+}).strict();
 var desktopNotificationRequestSchema = external_exports.object({
   id: external_exports.string().min(1).max(128),
   title: external_exports.string().min(1).max(160),
-  body: external_exports.string().min(1).max(256)
+  body: external_exports.string().min(1).max(256),
+  target: notificationTargetSchema.optional()
 }).strict();
 var notificationDeliverySchema = external_exports.object({
   state: external_exports.enum(["unverified", "shown", "failed", "unsupported"]),
@@ -18461,29 +18488,16 @@ var agentNotificationSchema = external_exports.object({
   t: external_exports.literal("agent-notification"),
   id: external_exports.string().uuid(),
   session: external_exports.string().uuid(),
-  reason: external_exports.enum(["waiting_input", "exited"])
+  reason: external_exports.enum(["waiting_input", "exited"]),
+  content: notificationContentSchema.optional()
 });
 
-// ../shared/src/api/common.ts
-var errorResponseSchema = external_exports.object({
-  error: external_exports.object({
-    code: external_exports.string(),
-    message: external_exports.string(),
-    /** Optional machine-readable context for recoverable conflicts. */
-    details: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
-  })
-});
-var isoTimestamp = external_exports.iso.datetime({ offset: true });
-var rowId = external_exports.number().int().positive();
-var sessionId = external_exports.uuid();
-var projectId = external_exports.string().regex(/^[0-9a-f]{10}$/);
-var profileId = external_exports.string().regex(/^[0-9a-f]{10}$/);
-
 // ../shared/src/api/version.ts
 var versionResponseSchema = external_exports.object({
   version: external_exports.string(),
   /** Added by the host connector; absent on direct daemon responses and older connectors. */
   remote_notifications: external_exports.boolean().optional(),
+  remote_notification_previews: external_exports.boolean().optional(),
   remote_image_uploads: external_exports.boolean().optional(),
   protocol: external_exports.object({
     major: external_exports.number().int().nonnegative(),
@@ -19852,6 +19866,7 @@ var remoteHostSchema = external_exports.object({
 var remoteHostsSchema = external_exports.array(remoteHostSchema);
 var remoteServiceInfoSchema = external_exports.object({
   push_public_key: external_exports.string().max(100).optional(),
+  push_encrypted_previews: external_exports.boolean().optional(),
   providers: external_exports.array(external_exports.enum(["google", "github"])),
   protocol: external_exports.literal(REMOTE_PROTOCOL_VERSION)
 });
@@ -20045,6 +20060,12 @@ var imageUploadProgressSchema = external_exports.object({
 });
 
 // ../shared/src/remote/notifications.ts
+var notificationPreviewKeySchema = external_exports.object({ id: remoteIdSchema, secret: remoteSecretSchema }).strict();
+var encryptedNotificationSchema = external_exports.object({
+  key: remoteIdSchema,
+  iv: external_exports.string().regex(/^[a-f0-9]{24}$/),
+  ciphertext: external_exports.string().min(32).max(3072).regex(/^(?:[a-f0-9]{2})+$/)
+}).strict();
 var pushEndpointSchema = external_exports.string().max(2048).url().refine((value) => {
   let url2;
   try {
@@ -20063,18 +20084,177 @@ var pushSubscriptionSchema = external_exports.object({
     auth: external_exports.string().regex(/^[A-Za-z0-9_-]{22}={0,2}$/)
   }).strict()
 }).strict();
-var pushPreferenceSchema = external_exports.object({ subscription: pushSubscriptionSchema.nullable() }).strict();
-var pushRegistrationSchema = pushPreferenceSchema.extend({ credential: remoteSecretSchema, device: remoteIdSchema }).strict();
+var pushPreferenceSchema = external_exports.object({
+  subscription: pushSubscriptionSchema.nullable(),
+  preview_key: notificationPreviewKeySchema.optional()
+}).strict();
+var pushRegistrationSchema = pushPreferenceSchema.omit({ preview_key: true }).extend({ credential: remoteSecretSchema, device: remoteIdSchema }).strict();
 var pushDispatchSchema = external_exports.object({
   credential: remoteSecretSchema,
   devices: external_exports.array(remoteIdSchema).min(1).max(64),
-  id: remoteIdSchema
+  id: remoteIdSchema,
+  preview: encryptedNotificationSchema.optional()
+}).strict();
+var pushPayloadSchema = external_exports.object({
+  id: remoteIdSchema,
+  host: remoteIdSchema,
+  preview: encryptedNotificationSchema.optional()
+}).strict();
+var connectorNotificationSchema = external_exports.object({
+  t: external_exports.literal("notify"),
+  id: remoteIdSchema,
+  content: notificationContentSchema.optional()
 }).strict();
-var pushPayloadSchema = external_exports.object({ id: remoteIdSchema, host: remoteIdSchema }).strict();
-var connectorNotificationSchema = external_exports.object({ t: external_exports.literal("notify"), id: remoteIdSchema }).strict();
 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";
@@ -21613,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.21";
+  if (true) return "0.3.0";
   const here = dirname4(fileURLToPath2(import.meta.url));
   for (const candidate of [
     join5(here, "..", "..", "package.json"),
@@ -22007,7 +22187,11 @@ var RELEASE_PROTOCOLS = {
   "0.2.18": { major: 22, minor: 0 },
   "0.2.19": { major: 22, minor: 0 },
   "0.2.20": { major: 22, minor: 4 },
-  "0.2.21": { major: 22, minor: 4 }
+  "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.3.0": { major: 23, minor: 0 }
 };
 function validProtocol(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -24277,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",
@@ -24313,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} "$@"
@@ -24330,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 {