@pikku/core 0.12.71 → 0.12.74

package/dist/wirings/channel/channel.types.d.ts

@@ -69,7 +69,12 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
     onBinaryMessage?: (services: any, data: BinaryData, channel: PikkuChannel<ChannelData, any>) => Promise<BinaryData | void> | BinaryData | void;
     tags?: string[];
 };
-export interface PikkuChannel<OpeningData, out Out> {
+/**
+ * The shape of `channel.remote` before generated types narrow it to the app's
+ * own functions. Loose on purpose: core cannot know the names.
+ */
+export type ChannelRemote = (funcName: string, data?: any) => Promise<any>;
+export interface PikkuChannel<OpeningData, out Out, Remote extends (...args: any[]) => any = ChannelRemote> {
     channelId: string;
     openingData: OpeningData;
     send(data: Out, isBinary?: boolean): Promise<void> | void;
@@ -79,6 +84,12 @@ export interface PikkuChannel<OpeningData, out Out> {
     setState<T>(state: T): Promise<void> | void;
     getState<T>(): Promise<T | undefined> | T | undefined;
     clearState(): Promise<void> | void;
+    /**
+     * Calls a function on the peer at the other end of this connection and waits
+     * for its answer — the only way to reach a peer with no address of its own.
+     * The peer decides what it answers to; an unregistered name is refused.
+     */
+    remote: Remote;
 }
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
     send(message: Out, isBinary?: boolean): Promise<void> | void;

package/dist/wirings/channel/define-channel-routes.d.ts

@@ -1,21 +1 @@
-/**
- * Type-safe helper for defining channel message routes that can be composed.
- * Returns the routes record as-is (identity function) for use with `wireChannel`.
- *
- * @example
- * ```typescript
- * export const chatRoutes = defineChannelRoutes({
- *   greet: pikkuChannelFunc({ func: greetFunc }),
- *   farewell: pikkuChannelFunc({ func: farewellFunc }),
- * })
- *
- * wireChannel({
- *   name: 'chat',
- *   route: '/ws/chat',
- *   onMessageWiring: {
- *     command: chatRoutes,
- *   }
- * })
- * ```
- */
 export declare function defineChannelRoutes<T extends Record<string, any>>(routes: T): T;

package/dist/wirings/channel/define-channel-routes.js

@@ -1,23 +1,3 @@
-/**
- * Type-safe helper for defining channel message routes that can be composed.
- * Returns the routes record as-is (identity function) for use with `wireChannel`.
- *
- * @example
- * ```typescript
- * export const chatRoutes = defineChannelRoutes({
- *   greet: pikkuChannelFunc({ func: greetFunc }),
- *   farewell: pikkuChannelFunc({ func: farewellFunc }),
- * })
- *
- * wireChannel({
- *   name: 'chat',
- *   route: '/ws/chat',
- *   onMessageWiring: {
- *     command: chatRoutes,
- *   }
- * })
- * ```
- */
 export function defineChannelRoutes(routes) {
     return routes;
 }

package/dist/wirings/channel/eventhub-service.d.ts

@@ -1,23 +1,5 @@
-/**
- * Interface defining the methods of a EventHub Service.
- */
 export interface EventHubService<Topics extends Record<string, any>> {
-    /**
-     * Subscribes a connection to a specific topic.
-     * @param topic - The topic to subscribe to.
-     * @param channelId - The unique ID of the connection to subscribe.
-     */
     subscribe<T extends keyof Topics>(topic: T, channelId: string): Promise<void> | void;
-    /**
-     * Unsubscribes a connection from a specific topic.
-     * @param topic - The topic to unsubscribe from.
-     * @param channelId - The unique ID of the connection to unsubscribe.
-     */
     unsubscribe<T extends keyof Topics>(topic: T, channelId: string): Promise<void> | void;
-    /**
-     * Sends data to all connections subscribed to a topic.
-     * @param topic - The topic to send data to.
-     * @param data - The data to send to the subscribers.
-     */
     publish<T extends keyof Topics>(topic: T, channelId: string | null, data: Topics[T], isBinary?: boolean): Promise<void> | void;
 }

package/dist/wirings/channel/index.d.ts

@@ -6,5 +6,8 @@ export type { EventHubService } from './eventhub-service.js';
 export { ChannelStore } from './channel-store.js';
 export type { Channel } from './channel-store.js';
 export { EventHubStore } from './eventhub-store.js';
-export type { BinaryData, ChannelsMeta, CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, ChannelMessageMeta, ChannelMeta, PikkuChannel, PikkuChannelHandlerFactory, } from './channel.types.js';
+export type { BinaryData, ChannelsMeta, CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, ChannelMessageMeta, ChannelMeta, ChannelRemote, PikkuChannel, PikkuChannelHandlerFactory, } from './channel.types.js';
 export { defineChannelRoutes } from './define-channel-routes.js';
+export { CHANNEL_RPC_PENDING, CHANNEL_RPC_REQUEST, CHANNEL_RPC_RESPONSE, ChannelDeploymentService, ChannelRPCError, ChannelRPCRegistry, createChannelRPCResponder, createChannelRPCInputValidator, createChannelRPCResultValidator, isChannelRPCPending, isChannelRPCRequest, isChannelRPCResponse, resolveCapability, unsupportedChannelRemote, } from './channel-rpc.js';
+export type { ApprovalPolicy, ApprovalRequester, Capabilities, Capability, CapabilityDef, CapabilityHandler, ChannelRPCPending, ChannelRPCRequest, ChannelRPCResponse, ChannelRPCValidator, } from './channel-rpc.js';
+export { channelRemote, getChannelHostRPC, handleChannelRPCResponse, releaseChannelHostRPC, } from './channel-host-rpc.js';

package/dist/wirings/channel/index.js

@@ -5,3 +5,5 @@ export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js
 export { ChannelStore } from './channel-store.js';
 export { EventHubStore } from './eventhub-store.js';
 export { defineChannelRoutes } from './define-channel-routes.js';
+export { CHANNEL_RPC_PENDING, CHANNEL_RPC_REQUEST, CHANNEL_RPC_RESPONSE, ChannelDeploymentService, ChannelRPCError, ChannelRPCRegistry, createChannelRPCResponder, createChannelRPCInputValidator, createChannelRPCResultValidator, isChannelRPCPending, isChannelRPCRequest, isChannelRPCResponse, resolveCapability, unsupportedChannelRemote, } from './channel-rpc.js';
+export { channelRemote, getChannelHostRPC, handleChannelRPCResponse, releaseChannelHostRPC, } from './channel-host-rpc.js';

package/dist/wirings/channel/local/local-channel-runner.js

@@ -16,7 +16,7 @@ const runUpgradeMiddleware = async (singletonServices, request, response, userSe
     const wireInheritedMiddleware = httpGroups['*']
         ? [{ type: 'http', route: '*' }]
         : undefined;
-    const middleware = combineMiddleware('channel', `upgrade:${request.path()}`, {
+    const middleware = combineMiddleware('channel', 'upgrade', {
         wireInheritedMiddleware,
     });
     if (middleware.length > 0) {
@@ -88,6 +88,7 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                             channel,
                             data: openingData,
                             channelMiddlewareMeta: meta.channelMiddleware,
+                            userSession,
                         });
                         if (result !== undefined) {
                             await channel.send(result);
@@ -115,6 +116,7 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                             services,
                             channel,
                             channelMiddlewareMeta: meta.channelMiddleware,
+                            userSession,
                         });
                     }
                     catch (e) {

package/dist/wirings/channel/local/local-eventhub-service.d.ts

@@ -1,44 +1,11 @@
 import type { PikkuChannelHandler } from '../channel.types.js';
 import type { EventHubService } from '../eventhub-service.js';
-/**
- * Implementation of the SubscriptionService interface.
- * Manages subscriptions and publishes messages to subscribers.
- */
 export declare class LocalEventHubService<Data extends Record<string, any> = {}> implements EventHubService<Data> {
     private channels;
-    /**
-     * A map storing topics and their associated connection IDs.
-     */
     private subscriptions;
-    /**
-     * Subscribes a connection to a specific topic.
-     * Creates the topic if it does not already exist.
-     * @param topic - The topic to subscribe to.
-     * @param channelId - The unique ID of the connection to subscribe.
-     */
     subscribe<T extends keyof Data>(topic: T, channelId: string): void | Promise<void>;
-    /**
-     * Unsubscribes a connection from a specific topic.
-     * Removes the topic if it has no more subscribers.
-     * @param topic - The topic to unsubscribe from.
-     * @param channelId - The unique ID of the connection to unsubscribe.
-     */
     unsubscribe<T extends keyof Data>(topic: T, channelId: string): void | Promise<void>;
-    /**
-     * Sends data to all connections subscribed to a topic.
-     * @param topic - The topic to send data to.
-     * @param data - The data to send to the subscribers.
-     */
     publish<T extends keyof Data>(topic: T, channelId: string | null, data: Data[T], isBinary?: boolean): void | Promise<void>;
-    /**
-     * Registers a channel on open
-     */
     onChannelOpened(channelHandler: PikkuChannelHandler): void;
-    /**
-     * Handles cleanup when a channel is closed.
-     * Removes the channel from all topics it is subscribed to.
-     * Deletes the topic if no more channels are subscribed to it.
-     * @param channelId - The ID of the channel that was closed.
-     */
     onChannelClosed(channelId: string): void;
 }

package/dist/wirings/channel/local/local-eventhub-service.js

@@ -1,31 +1,12 @@
-/**
- * Implementation of the SubscriptionService interface.
- * Manages subscriptions and publishes messages to subscribers.
- */
 export class LocalEventHubService {
     channels = new Map();
-    /**
-     * A map storing topics and their associated connection IDs.
-     */
     subscriptions = new Map();
-    /**
-     * Subscribes a connection to a specific topic.
-     * Creates the topic if it does not already exist.
-     * @param topic - The topic to subscribe to.
-     * @param channelId - The unique ID of the connection to subscribe.
-     */
     subscribe(topic, channelId) {
         if (!this.subscriptions.has(topic)) {
             this.subscriptions.set(topic, new Set());
         }
         this.subscriptions.get(topic).add(channelId);
     }
-    /**
-     * Unsubscribes a connection from a specific topic.
-     * Removes the topic if it has no more subscribers.
-     * @param topic - The topic to unsubscribe from.
-     * @param channelId - The unique ID of the connection to unsubscribe.
-     */
     unsubscribe(topic, channelId) {
         const topicSubscriptions = this.subscriptions.get(topic);
         if (topicSubscriptions) {
@@ -35,11 +16,6 @@ export class LocalEventHubService {
             }
         }
     }
-    /**
-     * Sends data to all connections subscribed to a topic.
-     * @param topic - The topic to send data to.
-     * @param data - The data to send to the subscribers.
-     */
     publish(topic, channelId, data, isBinary) {
         const subscribedChannelIds = this.subscriptions.get(topic);
         if (!subscribedChannelIds) {
@@ -47,36 +23,26 @@ export class LocalEventHubService {
         }
         for (const toChannelId of subscribedChannelIds) {
             if (channelId === toChannelId)
-                continue; // Skip sending to the sender
+                continue;
             const channel = this.channels.get(toChannelId);
             if (channel) {
                 try {
                     channel.send(data, isBinary);
                 }
                 catch {
-                    // Channel closed (e.g. SSE ReadableStream controller already closed on browser disconnect) — clean up
                     this.onChannelClosed(toChannelId);
                 }
             }
         }
     }
-    /**
-     * Registers a channel on open
-     */
     onChannelOpened(channelHandler) {
         this.channels.set(channelHandler.getChannel().channelId, channelHandler);
     }
-    /**
-     * Handles cleanup when a channel is closed.
-     * Removes the channel from all topics it is subscribed to.
-     * Deletes the topic if no more channels are subscribed to it.
-     * @param channelId - The ID of the channel that was closed.
-     */
     onChannelClosed(channelId) {
         for (const [topic, channelIds] of this.subscriptions.entries()) {
             channelIds.delete(channelId);
             if (channelIds.size === 0) {
-                this.subscriptions.delete(topic); // Cleanup empty topics
+                this.subscriptions.delete(topic);
             }
         }
         this.channels.delete(channelId);

package/dist/wirings/channel/log-channels.d.ts

@@ -1,6 +1,2 @@
 import type { Logger } from '../../services/index.js';
-/**
- * Logs all the loaded channels.
- * @param logger - A logger for logging information.
- */
 export declare const logChannels: (logger: Logger) => void;

package/dist/wirings/channel/log-channels.js

@@ -1,8 +1,4 @@
 import { pikkuState } from '../../pikku-state.js';
-/**
- * Logs all the loaded channels.
- * @param logger - A logger for logging information.
- */
 export const logChannels = (logger) => {
     const channels = pikkuState(null, 'channel', 'channels');
     if (channels.size === 0) {

package/dist/wirings/channel/pikku-abstract-channel-handler.js

@@ -1,3 +1,4 @@
+import { channelRemote, releaseChannelHostRPC } from './channel-host-rpc.js';
 export class PikkuAbstractChannelHandler {
     channelId;
     channelName;
@@ -25,6 +26,7 @@ export class PikkuAbstractChannelHandler {
                 clearState: () => {
                     channelState = undefined;
                 },
+                remote: (funcName, data) => channelRemote(this.getChannel(), funcName, data),
             };
         }
         return this.channel;
@@ -34,5 +36,9 @@ export class PikkuAbstractChannelHandler {
     }
     close() {
         this.getChannel().state = 'closed';
+        // Fails anything the departing peer still owed an answer to. Not awaited:
+        // `close` is on every runtime's synchronous path, and nothing here can fail
+        // in a way a closing channel could act on.
+        void releaseChannelHostRPC(this.channelId);
     }
 }

package/dist/wirings/channel/serverless/serverless-channel-runner.js

@@ -78,9 +78,9 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
                 channel,
                 data: openingData,
                 channelMiddlewareMeta: meta.channelMiddleware,
+                userSession,
             });
         }
-        // Store the pikkuUserId mapping after auth middleware has run
         const pikkuUserId = userSession.getPikkuUserId();
         if (pikkuUserId) {
             await channelStore.setPikkuUserId(channelId, pikkuUserId);
@@ -100,10 +100,6 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
     let wireServices;
-    // Try to get channel from store. In serverless environments (especially with
-    // serverless-offline or worker threads), disconnect can be called multiple times
-    // or after the channel has already been cleaned up. If channel doesn't exist,
-    // there's nothing to disconnect, so we can return early.
     let channelData;
     try {
         channelData = await channelStore.getChannel(channelId);
@@ -151,6 +147,7 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
                 services,
                 channel,
                 channelMiddlewareMeta: meta.channelMiddleware,
+                userSession,
             });
         }
         catch (e) {

package/dist/wirings/cli/channel/cli-approval.d.ts

@@ -0,0 +1,41 @@
+import type { ApprovalRequester } from '../../channel/channel-rpc.js';
+/**
+ * - `prompt`   — ask about anything not classified `needsApproval: false`.
+ * - `auto`     — run the classified-safe set, refuse the rest without asking.
+ * - `dangerous`— run everything.
+ */
+export type ApprovalMode = 'prompt' | 'auto' | 'dangerous';
+export declare const APPROVAL_FLAGS: {
+    readonly auto: "--auto-approve";
+    readonly dangerous: "--dangerously-auto-approve";
+};
+/**
+ * Stripped from argv, not just read: the server owns the command tree and has
+ * never heard of these, and a flag the server can see is one it could act on.
+ */
+export declare const takeApprovalFlags: (args: string[], env?: Record<string, string | undefined>) => {
+    mode: ApprovalMode;
+    args: string[];
+};
+/**
+ * `a` is scoped to the one capability and to this run: widening it to every
+ * capability would quietly turn an interactive run into
+ * `--dangerously-auto-approve`, and persisting it would outlive anyone's memory
+ * of agreeing.
+ */
+export declare const createTerminalApprover: ({ input, output, signal, }?: {
+    input?: NodeJS.ReadStream;
+    output?: NodeJS.WritableStream;
+    /** Aborted when the run ends, so a prompt nobody can answer stops waiting. */
+    signal?: AbortSignal;
+}) => ApprovalRequester;
+/**
+ * Undefined reads as "nobody to ask", which refuses rather than runs. That is
+ * what a non-interactive run gets: CI is exactly where an unattended push would
+ * otherwise happen.
+ */
+export declare const approverForMode: (mode: ApprovalMode, { isTTY, warn, signal, }?: {
+    isTTY?: boolean;
+    warn?: (message: string) => void;
+    signal?: AbortSignal;
+}) => ApprovalRequester | undefined;

package/dist/wirings/cli/channel/cli-approval.js

@@ -0,0 +1,81 @@
+export const APPROVAL_FLAGS = {
+    auto: '--auto-approve',
+    dangerous: '--dangerously-auto-approve',
+};
+/**
+ * Stripped from argv, not just read: the server owns the command tree and has
+ * never heard of these, and a flag the server can see is one it could act on.
+ */
+export const takeApprovalFlags = (args, env = process.env) => {
+    const remaining = args.filter((arg) => arg !== APPROVAL_FLAGS.auto && arg !== APPROVAL_FLAGS.dangerous);
+    const dangerous = args.includes(APPROVAL_FLAGS.dangerous) ||
+        env.PIKKU_DANGEROUSLY_AUTO_APPROVE === '1';
+    const auto = args.includes(APPROVAL_FLAGS.auto) || env.PIKKU_AUTO_APPROVE === '1';
+    return {
+        mode: dangerous ? 'dangerous' : auto ? 'auto' : 'prompt',
+        args: remaining,
+    };
+};
+/**
+ * `a` is scoped to the one capability and to this run: widening it to every
+ * capability would quietly turn an interactive run into
+ * `--dangerously-auto-approve`, and persisting it would outlive anyone's memory
+ * of agreeing.
+ */
+export const createTerminalApprover = ({ input = process.stdin, output = process.stderr, signal, } = {}) => {
+    const allowed = new Set();
+    const ask = async ({ funcName, description }) => {
+        if (allowed.has(funcName) || signal?.aborted) {
+            return allowed.has(funcName);
+        }
+        // stderr, so a command whose stdout is piped still shows the prompt rather
+        // than corrupting the stream it is asking about.
+        output.write(`\nThe server is asking to run "${funcName}" on this machine.\n` +
+            (description ? `  ${description}\n` : '') +
+            `Allow? [y]es / [n]o / [a]lways for "${funcName}": `);
+        const answer = await new Promise((resolve) => {
+            const done = (value) => {
+                input.off('data', onData);
+                signal?.removeEventListener('abort', onAbort);
+                // Reading resumed stdin, which holds the event loop open.
+                input.pause?.();
+                resolve(value);
+            };
+            const onData = (chunk) => done(String(chunk).trim().toLowerCase());
+            // An aborted prompt is a refusal: its command is already over.
+            const onAbort = () => done('n');
+            input.on('data', onData);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+        if (answer === 'a' || answer === 'always') {
+            allowed.add(funcName);
+            return true;
+        }
+        return answer === 'y' || answer === 'yes';
+    };
+    // Requests are dispatched without awaiting, so two can be in flight at once.
+    // Unserialized, both prompts print interleaved and the first keystroke
+    // answers both — approving something the user never read.
+    let queue = Promise.resolve();
+    return (request) => {
+        const answered = queue.then(() => ask(request));
+        queue = answered.catch(() => { });
+        return answered;
+    };
+};
+/**
+ * Undefined reads as "nobody to ask", which refuses rather than runs. That is
+ * what a non-interactive run gets: CI is exactly where an unattended push would
+ * otherwise happen.
+ */
+export const approverForMode = (mode, { isTTY = process.stdin.isTTY, warn = console.error, signal, } = {}) => {
+    if (mode === 'dangerous') {
+        // Once, on stderr, so the log of a run that went wrong records it.
+        warn(`${APPROVAL_FLAGS.dangerous}: every capability this client exposes will run without asking.`);
+        return () => true;
+    }
+    if (mode === 'auto' || !isTTY) {
+        return undefined;
+    }
+    return createTerminalApprover({ signal });
+};

package/dist/wirings/cli/channel/cli-channel-runner.d.ts

@@ -1,8 +1,4 @@
 import type { CorePikkuCLIRender } from '../cli.types.js';
-/**
- * Execute a CLI program via WebSocket channel
- * This is the main entry point for CLI-over-Channel clients
- */
 export declare function executeCLIViaChannel({ programName, pikkuWS, args, renderers, defaultRenderer, }: {
     programName: string;
     pikkuWS: any;

package/dist/wirings/cli/channel/cli-channel-runner.js

@@ -1,19 +1,10 @@
 import { pikkuState } from '../../../pikku-state.js';
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js';
-/**
- * Default JSON renderer for CLI output. Emits single-line NDJSON so
- * the output stays machine-parseable when the CLI is run with
- * `--output json`; pretty-printing here would break NDJSON consumers.
- */
+// knowledge: decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md
 const defaultJSONRenderer = (_services, data) => {
     console.log(JSON.stringify(data));
 };
-/**
- * Execute a CLI program via WebSocket channel
- * This is the main entry point for CLI-over-Channel clients
- */
 export async function executeCLIViaChannel({ programName, pikkuWS, args = process.argv.slice(2), renderers = {}, defaultRenderer, }) {
-    // Get CLI metadata from state
     const cliMeta = pikkuState(null, 'cli', 'meta');
     if (!cliMeta || !('programs' in cliMeta)) {
         throw new Error('[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.');
@@ -24,54 +15,44 @@ export async function executeCLIViaChannel({ programName, pikkuWS, args = proces
         console.error(`Error: CLI program "${programName}" not found`);
         process.exit(1);
     }
-    // Parse arguments for this specific program
     const parsed = parseCLIArguments(args, programName, allCLIMeta);
-    // Handle help (check after parsing to support subcommand help)
+    // Parsed first so that `<command> --help` resolves to that command's help.
     if (args.includes('--help') || args.includes('-h') || args.length === 0) {
         const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
         console.log(helpText);
         return;
     }
     if (parsed.errors.length > 0) {
-        // Check if any error is about an unknown command
+        // knowledge: decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md
         const hasUnknownCommand = parsed.errors.some((error) => error.startsWith('Unknown command:') ||
             error.startsWith('Command not found:'));
         if (hasUnknownCommand) {
-            // Show help instead of error for unknown commands
             const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
             console.log(helpText);
             process.exit(1);
         }
         else {
-            // Show errors for other types of errors
             console.error('Errors:');
             parsed.errors.forEach((error) => console.error(`  ${error}`));
             process.exit(1);
         }
     }
-    // Merge positionals and options into single data object
     const data = { ...parsed.positionals, ...parsed.options };
-    // Get the renderer for this command
     const commandId = parsed.commandPath.join('.');
     const renderer = renderers[commandId] || defaultRenderer || defaultJSONRenderer;
     return new Promise((resolve, reject) => {
-        // Subscribe to responses for this command
         const commandRoute = pikkuWS.getRoute('command');
         const responseHandler = (response) => {
-            // Check if this is a control message
             if (response?.action === 'cli-control' &&
                 response?.event === 'complete') {
-                // Server signals command is complete, close the connection client-side
                 commandRoute.unsubscribe(commandId, responseHandler);
                 pikkuWS.ws.close();
                 resolve(undefined);
                 return;
             }
-            // Call renderer for any output
             renderer(null, response, undefined);
         };
         commandRoute.subscribe(commandId, responseHandler);
-        // Handle connection close
         pikkuWS.ws.addEventListener('close', () => {
             commandRoute.unsubscribe(commandId, responseHandler);
             resolve(undefined);
@@ -80,13 +61,10 @@ export async function executeCLIViaChannel({ programName, pikkuWS, args = proces
             commandRoute.unsubscribe(commandId, responseHandler);
             reject(error);
         });
-        // Send the command once connected
         if (pikkuWS.ws.readyState === 1) {
-            // Already open
             commandRoute.send(commandId, data);
         }
         else {
-            // Wait for open
             pikkuWS.ws.addEventListener('open', () => {
                 commandRoute.send(commandId, data);
             });

package/dist/wirings/cli/channel/cli-raw-channel-runner.d.ts

@@ -1,15 +1,53 @@
-import type { CoreSingletonServices, CreateWireServices } from '../../../types/core.types.js';
+import type { CoreSingletonServices, CoreUserSession, CreateWireServices } from '../../../types/core.types.js';
+import type { PikkuChannel } from '../../channel/channel.types.js';
 /**
- * Handles raw CLI input from a WebSocket channel.
- * Parses the args, resolves the command, and either returns help or executes it.
+ * A frame sent from the server to a raw CLI client. `output` carries command
+ * data to render; `complete` terminates the command and carries the exit code
+ * so the client process can exit non-zero on failure.
  */
-export declare function handleRawCLI({ programName, args, singletonServices, createWireServices, }: {
+export type RawCLIFrame = {
+    action: 'cli-output';
+    commandId?: string;
+    data: unknown;
+} | {
+    action: 'cli-result';
+    commandId?: string;
+    result: unknown;
+} | {
+    action: 'cli-help';
+    help: string;
+} | {
+    action: 'cli-error';
+    error: string;
+} | {
+    action: 'cli-control';
+    event: 'complete';
+    exitCode: number;
+};
+export interface RawCLIResult {
+    help?: string;
+    result?: unknown;
+    error?: string;
+    /** 0 on success, 1 on any parse or execution failure. */
+    exitCode: number;
+    /** The command the server resolved, so a client can pick a renderer. */
+    commandId?: string;
+}
+/**
+ * The client sends argv untouched and this side owns parsing, so the command
+ * tree lives with the server and a client binary never needs to know it.
+ */
+export declare function handleRawCLI({ programName, args, singletonServices, createWireServices, onOutput, session, transport, }: {
     programName: string;
     args: string[];
     singletonServices: CoreSingletonServices;
     createWireServices?: CreateWireServices;
-}): Promise<{
-    help?: string;
-    result?: unknown;
-    error?: string;
-}>;
+    /** Established during the upgrade; commands run as that user. */
+    session?: CoreUserSession;
+    onOutput?: (data: unknown, commandId: string) => Promise<void> | void;
+    /**
+     * The channel the command arrived on, so `channel.remote(...)` reaches the
+     * calling client rather than being refused as a one-way stream.
+     */
+    transport?: PikkuChannel<unknown, any, any>;
+}): Promise<RawCLIResult>;