@pikku/core 0.12.20 → 0.12.21

package/dist/wirings/ai-agent/ai-agent-runner.js

@@ -1,4 +1,4 @@
-import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
+import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, } from './ai-agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
@@ -20,9 +20,19 @@ function stripNulls(obj) {
     return result;
 }
 import { randomUUID } from 'crypto';
+function extractStructuredAssistantOutput(object) {
+    if (!object || typeof object !== 'object') {
+        return { text: null, uiSpec: null };
+    }
+    const record = object;
+    return {
+        text: typeof record.text === 'string' ? record.text : null,
+        uiSpec: record.ui ?? null,
+    };
+}
 export async function runAIAgent(agentName, input, params, agentSessionMap) {
     const sessionMap = agentSessionMap ?? new Map();
-    const { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemoryJsonSchema, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
+    const { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
     const singletonServices = getSingletonServices();
     const { aiRunState } = singletonServices;
     if (!aiRunState) {
@@ -48,7 +58,15 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             usage: { inputTokens: 0, outputTokens: 0 },
         };
     }
-    const aiMiddlewares = agent.aiMiddleware ?? [];
+    const aiMiddlewares = [
+        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+            threadId,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        }),
+        ...(agent.aiMiddleware ?? []),
+    ];
     let modifiedMessages = runnerParams.messages;
     let modifiedInstructions = runnerParams.instructions;
     for (const mw of aiMiddlewares) {
@@ -152,12 +170,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                         args: a.args,
                     });
                 const completedStepsForSave = accumulatedSteps.slice(0, -1);
-                await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, { text: '', steps: completedStepsForSave }, {
-                    workingMemoryJsonSchema,
-                    workingMemorySchemaName,
-                    logger: singletonServices.logger,
-                    schemaService: singletonServices.schema,
-                });
+                await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, { text: '', steps: completedStepsForSave });
                 if (storage) {
                     await storage.saveMessages(threadId, [
                         {
@@ -197,19 +210,14 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             }
             appendStepMessages(runnerParams, stepResult);
         }
-        const finalText = lastStepResult?.text ?? '';
         const finalObject = lastStepResult?.object;
+        const structuredOutput = extractStructuredAssistantOutput(finalObject);
+        const finalText = structuredOutput.text ?? lastStepResult?.text ?? '';
         const result = {
             text: finalText,
             steps: accumulatedSteps,
         };
-        const responseText = await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, result, {
-            workingMemoryJsonSchema,
-            workingMemorySchemaName,
-            logger: singletonServices.logger,
-            schemaService: singletonServices.schema,
-        });
-        let outputText = responseText;
+        let outputText = finalText;
         let outputMessages = runnerParams.messages;
         for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
             const mw = aiMiddlewares[i];
@@ -223,6 +231,11 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
                 outputMessages = modResult.messages;
             }
         }
+        await saveMessages(storage, threadId, input.resourceId, memoryConfig, userMessage, {
+            ...result,
+            text: outputText,
+            uiSpec: structuredOutput.uiSpec,
+        });
         await aiRunState.updateRun(runId, {
             status: 'completed',
             usage: { ...totalUsage, model: agent.model },
@@ -369,7 +382,15 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
     const allMessages = [...contextMessages, ...messages];
     const trimmedMessages = trimMessages(allMessages);
     const instructions = await buildInstructions(resolvedName, packageName);
-    const aiMiddlewares = agent.aiMiddleware ?? [];
+    const aiMiddlewares = [
+        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+            threadId: run.threadId,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        }),
+        ...(agent.aiMiddleware ?? []),
+    ];
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
     for (const mw of aiMiddlewares) {
@@ -463,12 +484,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                     });
                 const completedSteps = accumulatedSteps.slice(0, -1);
                 if (completedSteps.length > 0) {
-                    await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, { text: '', steps: completedSteps }, {
-                        workingMemoryJsonSchema,
-                        workingMemorySchemaName,
-                        logger: singletonServices.logger,
-                        schemaService: singletonServices.schema,
-                    });
+                    await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, { text: '', steps: completedSteps });
                 }
                 if (storage) {
                     await storage.saveMessages(run.threadId, [
@@ -515,13 +531,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             text: finalText,
             steps: accumulatedSteps,
         };
-        const responseText = await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, result, {
-            workingMemoryJsonSchema,
-            workingMemorySchemaName,
-            logger: singletonServices.logger,
-            schemaService: singletonServices.schema,
-        });
-        let outputText = responseText;
+        let outputText = finalText;
         let outputMessages = runnerParams.messages;
         for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
             const mw = aiMiddlewares[i];
@@ -535,6 +545,10 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
                 outputMessages = modResult.messages;
             }
         }
+        await saveMessages(storage, run.threadId, run.resourceId, memoryConfig, null, {
+            ...result,
+            text: outputText,
+        });
         await aiRunState.updateRun(run.runId, {
             status: 'completed',
             usage: { ...totalUsage, model: agent.model },

package/dist/wirings/ai-agent/ai-agent-stream.js

@@ -2,12 +2,13 @@ import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { randomUUID } from 'crypto';
-import { parseWorkingMemory, deepMergeWorkingMemory, resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
+import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 function createPersistingChannel(parent, storage, threadId) {
     let fullText = '';
     let stepText = '';
+    let stepGenerativeUI = null;
     let stepToolCalls = [];
     let stepToolResults = [];
     const totalUsage = {
@@ -18,16 +19,23 @@ function createPersistingChannel(parent, storage, threadId) {
         if (!storage)
             return;
         const text = stepText;
+        const generativeUI = stepGenerativeUI;
         const calls = stepToolCalls;
         const results = stepToolResults;
         stepText = '';
+        stepGenerativeUI = null;
         stepToolCalls = [];
         stepToolResults = [];
-        if (text || calls.length > 0) {
+        if (text || generativeUI != null || calls.length > 0) {
             const assistantMsg = {
                 id: randomUUID(),
                 role: 'assistant',
-                content: text || undefined,
+                content: generativeUI != null
+                    ? [
+                        ...(text ? [{ type: 'text', text }] : []),
+                        { type: 'generative-ui', spec: generativeUI },
+                    ]
+                    : text || undefined,
                 toolCalls: calls.length > 0 ? calls : undefined,
                 createdAt: new Date(),
             };
@@ -81,6 +89,9 @@ function createPersistingChannel(parent, storage, threadId) {
                                 : JSON.stringify(event.result),
                         });
                         break;
+                    case 'generative-ui':
+                        stepGenerativeUI = event.spec;
+                        break;
                     case 'usage':
                         totalUsage.inputTokens += event.tokens.input;
                         totalUsage.outputTokens += event.tokens.output;
@@ -95,10 +106,13 @@ function createPersistingChannel(parent, storage, threadId) {
             }
             parent.send(event);
         },
+        setState: (s) => parent.setState(s),
+        getState: () => parent.getState(),
+        clearState: () => parent.clearState(),
     };
     return channel;
 }
-async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, threadId, workingMemorySchemaName, messages, aiRunState, runId) {
+async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, messages, aiRunState, runId) {
     const usage = persistingChannel.totalUsage;
     let outputText = persistingChannel.fullText;
     let outputMessages = messages;
@@ -117,22 +131,6 @@ async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServ
             outputMessages = result.messages;
         }
     }
-    if (storage && memoryConfig?.workingMemory && outputText) {
-        const parsed = parseWorkingMemory(outputText);
-        if (parsed) {
-            const existing = (await storage.getWorkingMemory(threadId, 'thread')) ?? {};
-            const merged = deepMergeWorkingMemory(existing, parsed);
-            if (singletonServices.schema && workingMemorySchemaName) {
-                try {
-                    await singletonServices.schema.validateSchema(workingMemorySchemaName, merged);
-                }
-                catch (err) {
-                    singletonServices.logger.warn(`Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            await storage.saveWorkingMemory(threadId, 'thread', merged);
-        }
-    }
     await aiRunState.updateRun(runId, {
         status: 'completed',
         ...(usage.model
@@ -147,7 +145,7 @@ async function postStreamCleanup(persistingChannel, aiMiddlewares, singletonServ
     });
 }
 async function runStreamStepLoop(params) {
-    const { agent, runnerParams, maxSteps, agentRunner, persistingChannel, channel, runId, aiMiddlewares, } = params;
+    const { agent, runnerParams, maxSteps, agentRunner, streamChannel, channel, runId, aiMiddlewares, } = params;
     const singletonServices = getSingletonServices();
     for (let step = 0; step < maxSteps; step++) {
         if (agent.prepareStep) {
@@ -166,7 +164,7 @@ async function runStreamStepLoop(params) {
                 break;
         }
         channel.send({ type: 'step-start', stepNumber: step });
-        const stepResult = await agentRunner.stream(runnerParams, persistingChannel);
+        const stepResult = await agentRunner.stream(runnerParams, streamChannel);
         for (const mw of aiMiddlewares) {
             if (mw.afterStep) {
                 await mw.afterStep(singletonServices, {
@@ -246,10 +244,21 @@ export function checkForCredentialRequests(stepResult, runId) {
     return requests;
 }
 export function appendStepMessages(runnerParams, stepResult) {
+    const structuredOutput = stepResult.object && typeof stepResult.object === 'object'
+        ? stepResult.object
+        : null;
+    const assistantContent = structuredOutput?.ui != null
+        ? [
+            ...(stepResult.text
+                ? [{ type: 'text', text: stepResult.text }]
+                : []),
+            { type: 'generative-ui', spec: structuredOutput.ui },
+        ]
+        : stepResult.text || undefined;
     const assistantMsg = {
         id: randomUUID(),
         role: 'assistant',
-        content: stepResult.text || undefined,
+        content: assistantContent,
         toolCalls: stepResult.toolCalls.length > 0
             ? stepResult.toolCalls.map((tc) => ({
                 id: tc.toolCallId,
@@ -257,6 +266,9 @@ export function appendStepMessages(runnerParams, stepResult) {
                 args: tc.args,
             }))
             : undefined,
+        ...(stepResult.reasoningContent
+            ? { reasoningContent: stepResult.reasoningContent }
+            : {}),
         createdAt: new Date(),
     };
     runnerParams.messages.push(assistantMsg);
@@ -363,7 +375,15 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         channel.send({ type: 'done' });
         return '';
     }
-    const aiMiddlewares = agent.aiMiddleware ?? [];
+    const aiMiddlewares = [
+        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+            threadId,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        }),
+        ...(agent.aiMiddleware ?? []),
+    ];
     let modifiedMessages = runnerParams.messages;
     let modifiedInstructions = runnerParams.instructions;
     for (const mw of aiMiddlewares) {
@@ -422,9 +442,10 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             ...streamMiddleware,
         ],
     });
+    const persistingChannel = createPersistingChannel(channel, storage, threadId);
     const wrappedChannel = allChannelMiddleware.length > 0
-        ? wrapChannelWithMiddleware({ channel }, singletonServices, allChannelMiddleware).channel
-        : channel;
+        ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
+        : persistingChannel;
     // In delegate mode (default), suppress parent's text from reaching the client
     // AFTER a sub-agent has been called. If the parent responds directly (no delegation),
     // its text goes through normally. Sub-agent text bypasses this path entirely
@@ -446,13 +467,13 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             delegateState,
         }
         : wrappedChannel;
-    const persistingChannel = createPersistingChannel(outputChannel, storage, threadId);
     try {
         const loopResult = await runStreamStepLoop({
             agent,
             runnerParams,
             maxSteps,
             agentRunner,
+            streamChannel: outputChannel,
             persistingChannel,
             channel,
             runId,
@@ -466,7 +487,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             await handleCredentialRequests(loopResult.credentialRequests, runId, channel, aiRunState, persistingChannel);
             return persistingChannel.fullText;
         }
-        await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, runId);
+        await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, runId);
         channel.send({ type: 'done' });
         channel.close();
         return persistingChannel.fullText;
@@ -683,7 +704,15 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     const allMessages = [...contextMessages, ...messages];
     const trimmedMessages = trimMessages(allMessages);
     const instructions = await buildInstructions(resolvedName, packageName);
-    const aiMiddlewares = agent.aiMiddleware ?? [];
+    const aiMiddlewares = [
+        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+            threadId: run.threadId,
+            workingMemorySchemaName,
+            logger: singletonServices.logger,
+            schemaService: singletonServices.schema,
+        }),
+        ...(agent.aiMiddleware ?? []),
+    ];
     let modifiedMessages = trimmedMessages;
     let modifiedInstructions = instructions;
     for (const mw of aiMiddlewares) {
@@ -726,14 +755,13 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             ...streamMiddleware,
         ],
     });
+    const persistingChannel = createPersistingChannel(channel, storage, run.threadId);
     const wrappedChannel = allChannelMiddleware.length > 0
-        ? wrapChannelWithMiddleware({ channel }, singletonServices, allChannelMiddleware).channel
-        : channel;
-    const persistingChannel = createPersistingChannel(wrappedChannel, storage, run.threadId);
+        ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
+        : persistingChannel;
     const streamContext = { channel, options };
     const resumeTools = (await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, aiMiddlewares)).tools;
     const resolved = resolveModelConfig(resolvedName, agent);
-    console.log('[DEBUG resume] resolvedName:', resolvedName, 'agent.model:', agent.model, 'resolved.model:', resolved.model);
     const maxSteps = resolved.maxSteps ?? 10;
     const runnerParams = {
         model: resolved.model,
@@ -753,6 +781,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             runnerParams,
             maxSteps,
             agentRunner,
+            streamChannel: wrappedChannel,
             persistingChannel,
             channel,
             runId: run.runId,
@@ -766,7 +795,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             await handleCredentialRequests(loopResult.credentialRequests, run.runId, channel, aiRunState, persistingChannel);
             return;
         }
-        await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, run.threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, run.runId);
+        await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, run.runId);
         channel.send({ type: 'done' });
         channel.close();
     }

package/dist/wirings/ai-agent/ai-agent.types.d.ts

@@ -24,6 +24,13 @@ export type AIContentPart = {
     url?: string;
     mediaType: string;
     filename?: string;
+} | {
+    type: 'data';
+    name: string;
+    data: unknown;
+} | {
+    type: 'generative-ui';
+    spec: unknown;
 };
 export interface AIToolCall {
     id: string;
@@ -41,6 +48,7 @@ export interface AIMessage {
     content?: string | AIContentPart[];
     toolCalls?: AIToolCall[];
     toolResults?: AIToolResult[];
+    reasoningContent?: string;
     createdAt: Date;
 }
 export interface AIAgentStep {
@@ -298,6 +306,17 @@ export type AIStreamEvent = {
     graph: any;
     agent?: string;
     session?: string;
+} | {
+    type: 'data';
+    name: string;
+    data: unknown;
+    agent?: string;
+    session?: string;
+} | {
+    type: 'generative-ui';
+    spec: unknown;
+    agent?: string;
+    session?: string;
 } | {
     type: 'suspended';
     reason: 'rpc-missing';
@@ -364,6 +383,7 @@ export interface AgentRunRow {
 export interface AgentRunService {
     listThreads(options?: {
         agentName?: string;
+        resourceId?: string;
         limit?: number;
         offset?: number;
     }): Promise<AIThread[]>;

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

@@ -43,7 +43,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             const routeMessage = routingProperty
                 ? `route '${routingProperty}:${routerValue}'`
                 : 'the default message route';
-            logger.error(`Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for ${routeMessage}`);
+            logger.error(`Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for ${routeMessage}. No session is attached to this websocket connection. Ensure auth middleware establishes a session during websocket upgrade, and configure sessionStore when the runtime needs persisted sessions.`);
             // TODO: Send error message back breaks typescript, but should be implemented somehow
             channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;

package/dist/wirings/channel/channel-store.d.ts

@@ -13,4 +13,17 @@ export declare abstract class ChannelStore<ChannelType = unknown, OpeningData =
     }> | (TypedChannel & {
         pikkuUserId?: string;
     });
+    /**
+     * Persist per-socket scratch state scoped to a single channel (keyed by
+     * channelId). This is intentionally separate from `SessionStore` (which is
+     * keyed by `pikkuUserId` and holds the user session — shared across HTTP
+     * and channel transports).
+     *
+     * Use this for ephemeral, channel-local data: a per-socket subscription
+     * filter, a step in a connection-bound state machine, the last command sent
+     * on this socket, etc. It is cleared when the channel is removed.
+     */
+    abstract setState(channelId: string, state: unknown): Promise<void> | void;
+    abstract getState(channelId: string): Promise<unknown | undefined> | unknown | undefined;
+    abstract clearState(channelId: string): Promise<void> | void;
 }

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

@@ -80,6 +80,9 @@ export interface PikkuChannel<OpeningData, out Out> {
     sendBinary(data: BinaryData): Promise<void> | void;
     close(): Promise<void> | void;
     state: 'initial' | 'open' | 'closed';
+    setState<T>(state: T): Promise<void> | void;
+    getState<T>(): Promise<T | undefined> | T | undefined;
+    clearState(): Promise<void> | void;
 }
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
     send(message: Out, isBinary?: boolean): Promise<void> | void;

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

@@ -7,8 +7,26 @@ import { isProduction } from '../../../env.js';
 import { getErrorResponse } from '../../../errors/error-handler.js';
 import { handleHTTPError } from '../../../handle-error.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../../services/user-session-service.js';
+import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js';
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js';
-import { getSingletonServices, getCreateWireServices, } from '../../../pikku-state.js';
+import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../../pikku-state.js';
+const runUpgradeMiddleware = async (singletonServices, request, response, userSession) => {
+    const http = createHTTPWire(request, response);
+    const httpGroups = pikkuState(null, 'middleware', 'httpGroup');
+    const wireInheritedMiddleware = httpGroups['*']
+        ? [{ type: 'http', route: '*' }]
+        : undefined;
+    const middleware = combineMiddleware('channel', `upgrade:${request.path()}`, {
+        wireInheritedMiddleware,
+    });
+    if (middleware.length > 0) {
+        await runMiddleware(singletonServices, {
+            http,
+            ...createMiddlewareSessionWireProps(userSession),
+        }, middleware);
+    }
+    return http;
+};
 export const runLocalChannel = async ({ channelId, request, response, route, skipUserSession = false, respondWith404 = true, coerceDataFromSchema = true, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
@@ -17,12 +35,12 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
     let channelHandler;
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     let http;
-    if (request) {
-        http = createHTTPWire(request, response);
-        route = http?.request?.path();
-    }
     let openingData, channelConfig, meta;
     try {
+        if (request) {
+            http = await runUpgradeMiddleware(singletonServices, request, response, userSession);
+            route = request.path();
+        }
         ;
         ({ openingData, channelConfig, meta } = await openChannel({
             channelId,

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

@@ -10,6 +10,7 @@ export class PikkuAbstractChannelHandler {
     }
     getChannel() {
         if (!this.channel) {
+            let channelState;
             this.channel = {
                 channelId: this.channelId,
                 openingData: this.openingData,
@@ -17,6 +18,13 @@ export class PikkuAbstractChannelHandler {
                 sendBinary: this.sendBinary.bind(this),
                 close: this.close.bind(this),
                 state: 'initial',
+                setState: (s) => {
+                    channelState = s;
+                },
+                getState: () => channelState,
+                clearState: () => {
+                    channelState = undefined;
+                },
             };
         }
         return this.channel;

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

@@ -54,6 +54,9 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
             channelHandlerFactory,
             channelName: channelConfig.name,
         });
+        channel.setState = (state) => channelStore.setState(channelId, state);
+        channel.getState = () => channelStore.getState(channelId);
+        channel.clearState = () => channelStore.clearState(channelId);
         const wire = {
             channel,
             ...createMiddlewareSessionWireProps(userSession),
@@ -116,6 +119,9 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
         openingData,
         channelName,
     });
+    channel.setState = (state) => channelStore.setState(channelId, state);
+    channel.getState = () => channelStore.getState(channelId);
+    channel.clearState = () => channelStore.clearState(channelId);
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     if (pikkuUserId) {
         userSession.setPikkuUserId(pikkuUserId);
@@ -167,6 +173,9 @@ export const runChannelMessage = async ({ channelId, channelStore, channelHandle
         openingData,
         channelName,
     });
+    channel.setState = (state) => channelStore.setState(channelId, state);
+    channel.getState = () => channelStore.getState(channelId);
+    channel.clearState = () => channelStore.clearState(channelId);
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     if (pikkuUserId) {
         userSession.setPikkuUserId(pikkuUserId);

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

@@ -208,6 +208,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
     // Get the renderer
     const renderer = programData?.renderers[commandId] || programData?.defaultRenderer;
     // Create a CLI channel for progressive output
+    let cliState;
     const channel = {
         channelId: `cli:${program}:${commandId}`,
         openingData: pluckedData,
@@ -225,6 +226,13 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             }
         },
         state: 'open',
+        setState: (s) => {
+            cliState = s;
+        },
+        getState: () => cliState,
+        clearState: () => {
+            cliState = undefined;
+        },
     };
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     const wire = {
@@ -252,10 +260,20 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             sessionService: userSession,
             packageName: currentCommand.packageName,
         });
-        // Apply renderer one final time with the final output (if renderer exists)
-        // Skip if result is undefined (void functions handle their own output)
-        if (renderer && result !== undefined) {
-            await Promise.resolve(renderer(singletonServices, result, userSession.get()));
+        // Render the final result. `--json` / `--output json` routes the result
+        // through the global JSON renderer, but only for commands that opted into
+        // result-rendering by declaring a `render` — inline-printing commands (no
+        // per-command renderer) keep emitting their own output untouched.
+        // Skip if result is undefined (void functions handle their own output).
+        if (result !== undefined) {
+            const commandRenderer = programData?.renderers[commandId];
+            const jsonMode = data.json === true || data.output === 'json';
+            const finalRenderer = jsonMode && commandRenderer !== undefined
+                ? defaultJSONRenderer
+                : (commandRenderer ?? programData?.defaultRenderer);
+            if (finalRenderer !== undefined) {
+                await Promise.resolve(finalRenderer(singletonServices, result, userSession.get()));
+            }
         }
         return result;
     }
@@ -305,7 +323,8 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         if (parsed.errors.length > 0) {
             // Check if any error is about an unknown command
             const hasUnknownCommand = parsed.errors.some((error) => error.startsWith('Unknown command:') ||
-                error.startsWith('Command not found:'));
+                error.startsWith('Command not found:') ||
+                error.startsWith('Missing subcommand:'));
             if (hasUnknownCommand) {
                 // Show help instead of error for unknown commands
                 const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);