@pikku/core 0.12.71 → 0.12.74

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

@@ -16,18 +16,6 @@ export const clearChannelMiddlewareCache = () => {
         delete channelMiddlewareCache[key];
     }
 };
-/**
- * Combine the inherited (tag/named) channel middleware with any per-run
- * middleware for a wiring.
- *
- * Only the statically-resolved inherited middleware is deterministic per `uid`
- * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
- * an AI agent's per-invocation stream middleware holding that run's
- * thread/session state) and MUST NOT be cached — caching it lets a later run of
- * the same `uid` reuse an earlier run's closures, leaking that run's state (and
- * growing memory) across invocations. It is therefore appended fresh on every
- * call after the cached inherited slice.
- */
 export const combineChannelMiddleware = (wireType, uid, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName = null, } = {}) => {
     const cacheKey = `${wireType}:${uid}`;
     let inherited = channelMiddlewareCache[cacheKey];

package/dist/wirings/channel/channel-rpc-registry.d.ts

@@ -0,0 +1,31 @@
+import { type ChannelRPCResponse } from './channel-rpc.types.js';
+/**
+ * Tracks in-flight reverse RPC calls for one channel. One registry per
+ * connection: ids are only unique within a socket, and a dropped socket must
+ * reject exactly the calls that were riding on it.
+ */
+export declare class ChannelRPCRegistry {
+    private readonly timeoutMs;
+    private pending;
+    private nextId;
+    private closed;
+    constructor(timeoutMs?: number);
+    get inFlight(): number;
+    register(): {
+        id: string;
+        promise: Promise<unknown>;
+    };
+    /**
+     * Stops the clock on a call whose peer is asking a human. The timeout exists
+     * to bound a peer that has gone away, and a person reading a prompt is not
+     * that; `rejectAll` still fails the call the moment the socket drops.
+     *
+     * Returns false for an unknown id — a pending frame for a call that already
+     * timed out is stale, not an error.
+     */
+    hold(id: string): boolean;
+    /** Returns false for an unknown id, so a late reply is dropped. */
+    settle(response: ChannelRPCResponse): boolean;
+    /** Without this a caller awaits the full timeout on a connection that is gone. */
+    rejectAll(reason?: string): void;
+}

package/dist/wirings/channel/channel-rpc-registry.js

@@ -0,0 +1,89 @@
+import { ChannelRPCError, } from './channel-rpc.types.js';
+/**
+ * Tracks in-flight reverse RPC calls for one channel. One registry per
+ * connection: ids are only unique within a socket, and a dropped socket must
+ * reject exactly the calls that were riding on it.
+ */
+export class ChannelRPCRegistry {
+    timeoutMs;
+    pending = new Map();
+    nextId = 0;
+    closed = false;
+    constructor(timeoutMs = 30_000) {
+        this.timeoutMs = timeoutMs;
+    }
+    get inFlight() {
+        return this.pending.size;
+    }
+    register() {
+        if (this.closed) {
+            return {
+                id: '',
+                promise: Promise.reject(new ChannelRPCError('Channel is closed', 'closed')),
+            };
+        }
+        const id = `${++this.nextId}`;
+        const promise = new Promise((resolve, reject) => {
+            const timer = this.timeoutMs > 0
+                ? setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new ChannelRPCError(`Channel RPC ${id} timed out after ${this.timeoutMs}ms`, 'timeout'));
+                }, this.timeoutMs)
+                : undefined;
+            // Never hold the process open waiting on a peer that may not answer.
+            timer?.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        return { id, promise };
+    }
+    /**
+     * Stops the clock on a call whose peer is asking a human. The timeout exists
+     * to bound a peer that has gone away, and a person reading a prompt is not
+     * that; `rejectAll` still fails the call the moment the socket drops.
+     *
+     * Returns false for an unknown id — a pending frame for a call that already
+     * timed out is stale, not an error.
+     */
+    hold(id) {
+        const call = this.pending.get(id);
+        if (!call || call.awaitingHuman) {
+            return false;
+        }
+        clearTimeout(call.timer);
+        call.timer = undefined;
+        call.awaitingHuman = true;
+        return true;
+    }
+    /** Returns false for an unknown id, so a late reply is dropped. */
+    settle(response) {
+        const call = this.pending.get(response.id);
+        if (!call) {
+            return false;
+        }
+        this.pending.delete(response.id);
+        clearTimeout(call.timer);
+        if (response.ok) {
+            call.resolve(response.result);
+        }
+        else {
+            // Peer input: a non-string name or message falls back rather than being
+            // attached to an Error, where it would surface as `[object Object]`.
+            const { name, message } = response.error ?? {};
+            const error = new ChannelRPCError(typeof message === 'string' ? message : 'Remote channel RPC failed', 'remote');
+            if (typeof name === 'string' && name.length > 0) {
+                error.name = name;
+            }
+            call.reject(error);
+        }
+        return true;
+    }
+    /** Without this a caller awaits the full timeout on a connection that is gone. */
+    rejectAll(reason = 'Channel closed') {
+        this.closed = true;
+        for (const [, call] of this.pending) {
+            clearTimeout(call.timer);
+            call.reject(new ChannelRPCError(reason, 'closed'));
+        }
+        this.pending.clear();
+    }
+}

package/dist/wirings/channel/channel-rpc-responder.d.ts

@@ -0,0 +1,15 @@
+import { type ApprovalRequester, type Capabilities } from './channel-rpc.types.js';
+/**
+ * Answers reverse RPC requests arriving on a channel.
+ *
+ * `capabilities` is the authorisation boundary, not a convenience: the peer is
+ * asking this process to execute code, so only listed names run. An absent
+ * name is refused exactly like an unknown one, so the caller cannot probe for
+ * what this end can do.
+ */
+export declare const createChannelRPCResponder: ({ capabilities, send, approve, }: {
+    capabilities: Capabilities;
+    send: (data: unknown) => Promise<void> | void;
+    /** Omitted means there is nobody to ask, which refuses rather than runs. */
+    approve?: ApprovalRequester;
+}) => (message: unknown) => Promise<boolean>;

package/dist/wirings/channel/channel-rpc-responder.js

@@ -0,0 +1,71 @@
+import { CHANNEL_RPC_PENDING, CHANNEL_RPC_RESPONSE, isCapabilityDef, isChannelRPCRequest, resolveCapability, } from './channel-rpc.types.js';
+/**
+ * Answers reverse RPC requests arriving on a channel.
+ *
+ * `capabilities` is the authorisation boundary, not a convenience: the peer is
+ * asking this process to execute code, so only listed names run. An absent
+ * name is refused exactly like an unknown one, so the caller cannot probe for
+ * what this end can do.
+ */
+export const createChannelRPCResponder = ({ capabilities, send, approve, }) => {
+    return async (message) => {
+        if (!isChannelRPCRequest(message)) {
+            return false;
+        }
+        const refuse = (name, why) => ({
+            action: CHANNEL_RPC_RESPONSE,
+            id: message.id,
+            ok: false,
+            error: { name, message: why },
+        });
+        // Own properties only: an object literal inherits from `Object.prototype`,
+        // so a peer asking for `toString` would otherwise resolve a real function.
+        const entry = Object.prototype.hasOwnProperty.call(capabilities, message.funcName)
+            ? capabilities[message.funcName]
+            : undefined;
+        if (entry === undefined ||
+            (typeof entry !== 'function' && !isCapabilityDef(entry))) {
+            await send(refuse('RPCNotFoundError', `Capability not exposed: ${message.funcName}`));
+            return true;
+        }
+        const { execute, needsApproval, approvalDescriptionFn } = resolveCapability(entry);
+        let response;
+        try {
+            if (needsApproval) {
+                if (!approve) {
+                    await send(refuse('RPCNotApprovedError', `"${message.funcName}" needs approval and there is nobody to ask`));
+                    return true;
+                }
+                // Before the asking, not after: an answer arriving past the caller's
+                // timeout is dropped, silently discarding the human's decision.
+                const description = await approvalDescriptionFn?.(message.data);
+                await send({
+                    action: CHANNEL_RPC_PENDING,
+                    id: message.id,
+                    reason: description ?? `approval for ${message.funcName}`,
+                });
+                const approved = await approve({
+                    funcName: message.funcName,
+                    data: message.data,
+                    description,
+                });
+                if (!approved) {
+                    await send(refuse('RPCDeniedError', `"${message.funcName}" was not approved`));
+                    return true;
+                }
+            }
+            response = {
+                action: CHANNEL_RPC_RESPONSE,
+                id: message.id,
+                ok: true,
+                result: await execute(message.data),
+            };
+        }
+        catch (e) {
+            const error = e;
+            response = refuse(error?.name ?? 'Error', error?.message ?? String(e));
+        }
+        await send(response);
+        return true;
+    };
+};

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

@@ -0,0 +1,40 @@
+import type { DeploymentService } from '../../services/deployment-service.js';
+import { ChannelRPCRegistry } from './channel-rpc-registry.js';
+import { type ChannelRPCValidator } from './channel-rpc.types.js';
+/**
+ * `remote` for channels that only ever flow one way — a server-sent stream, an
+ * agent's output, a local CLI. Nothing is listening for a request on them, so
+ * the call is refused rather than waiting out a timeout.
+ */
+export declare const unsupportedChannelRemote: (funcName: string) => Promise<never>;
+/**
+ * A `DeploymentService` whose transport is an open channel rather than an
+ * address, so a server-side function can call back into a peer that has no
+ * inbound route of its own.
+ *
+ * It slots into the existing `services.deploymentService` hole, leaving
+ * `rpc.remote` resolution, session propagation and traceId plumbing unchanged.
+ */
+export declare class ChannelDeploymentService implements DeploymentService {
+    private readonly send;
+    readonly registry: ChannelRPCRegistry;
+    private readonly validateInput?;
+    private readonly validateResult?;
+    constructor(send: (data: unknown) => Promise<void> | void, options?: {
+        timeoutMs?: number;
+        validateInput?: ChannelRPCValidator;
+        validateResult?: ChannelRPCValidator;
+    });
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** The channel owner must call this — the service has no read side. */
+    handleResponse(message: unknown): boolean;
+    /**
+     * `session` is accepted to satisfy `DeploymentService` and deliberately not
+     * sent: the peer runs the capability as itself, on its own machine, so a
+     * session on the wire would carry the caller's credentials while authorising
+     * nothing.
+     */
+    invoke(funcName: string, data: unknown, _session?: unknown, traceId?: string): Promise<unknown>;
+}

package/dist/wirings/channel/channel-rpc-service.js

@@ -0,0 +1,106 @@
+import { ChannelRPCRegistry } from './channel-rpc-registry.js';
+import { CHANNEL_RPC_REQUEST, CHANNEL_RPC_RESPONSE, ChannelRPCError, isChannelRPCPending, isChannelRPCResponse, } from './channel-rpc.types.js';
+/**
+ * `remote` for channels that only ever flow one way — a server-sent stream, an
+ * agent's output, a local CLI. Nothing is listening for a request on them, so
+ * the call is refused rather than waiting out a timeout.
+ */
+export const unsupportedChannelRemote = async (funcName) => {
+    throw new ChannelRPCError(`Cannot call "${funcName}" remotely: this channel has no peer that answers`, 'unsupported');
+};
+/**
+ * A `DeploymentService` whose transport is an open channel rather than an
+ * address, so a server-side function can call back into a peer that has no
+ * inbound route of its own.
+ *
+ * It slots into the existing `services.deploymentService` hole, leaving
+ * `rpc.remote` resolution, session propagation and traceId plumbing unchanged.
+ */
+export class ChannelDeploymentService {
+    send;
+    registry;
+    validateInput;
+    validateResult;
+    constructor(send, options = {}) {
+        this.send = send;
+        this.registry = new ChannelRPCRegistry(options.timeoutMs);
+        this.validateInput = options.validateInput;
+        this.validateResult = options.validateResult;
+    }
+    async init() { }
+    async start() { }
+    async stop() {
+        this.registry.rejectAll('Deployment service stopped');
+    }
+    /** The channel owner must call this — the service has no read side. */
+    handleResponse(message) {
+        if (isChannelRPCPending(message)) {
+            return this.registry.hold(message.id);
+        }
+        return isChannelRPCResponse(message) ? this.registry.settle(message) : false;
+    }
+    /**
+     * `session` is accepted to satisfy `DeploymentService` and deliberately not
+     * sent: the peer runs the capability as itself, on its own machine, so a
+     * session on the wire would carry the caller's credentials while authorising
+     * nothing.
+     */
+    async invoke(funcName, data, _session, traceId) {
+        // Not a security control — the peer must check what it is handed, and a
+        // hostile caller would send arguments that pass. It catches version drift
+        // and fails it here rather than inside the peer's process.
+        if (this.validateInput) {
+            try {
+                await this.validateInput(funcName, data);
+            }
+            catch (e) {
+                throw new ChannelRPCError(`Invalid arguments for "${funcName}": ${e?.message ?? String(e)}`, 'invalid');
+            }
+        }
+        const { id, promise } = this.registry.register();
+        // A closed registry answers with an already-rejected promise and no id.
+        // Returning it before the send keeps that rejection from sitting unobserved.
+        if (!id) {
+            return promise;
+        }
+        const request = {
+            action: CHANNEL_RPC_REQUEST,
+            id,
+            funcName,
+            data,
+            traceId,
+        };
+        try {
+            await this.send(request);
+        }
+        catch (e) {
+            // The call is registered before the request goes out, so a failed send
+            // would otherwise leave an entry whose timeout rejects into an unhandled
+            // rejection with nobody waiting on it.
+            this.registry.settle({
+                action: CHANNEL_RPC_RESPONSE,
+                id,
+                ok: false,
+                error: {
+                    name: e?.name ?? 'Error',
+                    message: e?.message ?? String(e),
+                },
+            });
+            promise.catch(() => { });
+            throw e;
+        }
+        const result = await promise;
+        if (!this.validateResult) {
+            return result;
+        }
+        // The peer answers with whatever it likes, so this is where a value that
+        // has been through nothing enters a server-side command.
+        try {
+            await this.validateResult(funcName, result);
+        }
+        catch (e) {
+            throw new ChannelRPCError(`Invalid result from "${funcName}": ${e?.message ?? String(e)}`, 'invalid');
+        }
+        return result;
+    }
+}

package/dist/wirings/channel/channel-rpc-validators.d.ts

@@ -0,0 +1,14 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { ChannelRPCValidator } from './channel-rpc.types.js';
+/**
+ * Checks a capability's answer against the schema codegen generated from its
+ * declared return type — the same one an agent tool or an HTTP response is
+ * checked against.
+ */
+export declare const createChannelRPCResultValidator: (singletonServices: Pick<CoreSingletonServices, "logger" | "schema">, packageName?: string | null) => ChannelRPCValidator;
+/**
+ * Checks outbound arguments against the declared input type. Unlike the result
+ * check this is not a boundary — it catches version drift, where a server built
+ * against a newer capability signature calls a client that predates it.
+ */
+export declare const createChannelRPCInputValidator: (singletonServices: Pick<CoreSingletonServices, "logger" | "schema">, packageName?: string | null) => ChannelRPCValidator;

package/dist/wirings/channel/channel-rpc-validators.js

@@ -0,0 +1,30 @@
+import { pikkuState } from '../../pikku-state.js';
+import { validateSchema } from '../../schema.js';
+/**
+ * A name with no function metadata is left alone: it is a capability this app
+ * never declared a contract for, and failing it would break callers that
+ * deliberately treat the value as opaque.
+ */
+const createChannelRPCSchemaValidator = (key, singletonServices, packageName = null) => async (funcName, value) => {
+    const pikkuFuncId = pikkuState(packageName, 'rpc', 'meta')[funcName];
+    if (!pikkuFuncId) {
+        return;
+    }
+    const schemaName = pikkuState(packageName, 'function', 'meta')[pikkuFuncId]?.[key];
+    if (!schemaName) {
+        return;
+    }
+    await validateSchema(singletonServices.logger, singletonServices.schema, schemaName, value, packageName);
+};
+/**
+ * Checks a capability's answer against the schema codegen generated from its
+ * declared return type — the same one an agent tool or an HTTP response is
+ * checked against.
+ */
+export const createChannelRPCResultValidator = (singletonServices, packageName = null) => createChannelRPCSchemaValidator('outputSchemaName', singletonServices, packageName);
+/**
+ * Checks outbound arguments against the declared input type. Unlike the result
+ * check this is not a boundary — it catches version drift, where a server built
+ * against a newer capability signature calls a client that predates it.
+ */
+export const createChannelRPCInputValidator = (singletonServices, packageName = null) => createChannelRPCSchemaValidator('inputSchemaName', singletonServices, packageName);

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

@@ -0,0 +1,5 @@
+export * from './channel-rpc.types.js';
+export * from './channel-rpc-registry.js';
+export * from './channel-rpc-service.js';
+export * from './channel-rpc-responder.js';
+export * from './channel-rpc-validators.js';

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

@@ -0,0 +1,5 @@
+export * from './channel-rpc.types.js';
+export * from './channel-rpc-registry.js';
+export * from './channel-rpc-service.js';
+export * from './channel-rpc-responder.js';
+export * from './channel-rpc-validators.js';

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

@@ -0,0 +1,90 @@
+/**
+ * Envelope actions for request/response RPC carried over an already-open
+ * channel. Both directions share one socket, so every frame is tagged and
+ * correlated by `id`.
+ */
+export declare const CHANNEL_RPC_REQUEST = "pikku-rpc-request";
+export declare const CHANNEL_RPC_RESPONSE = "pikku-rpc-response";
+export declare const CHANNEL_RPC_PENDING = "pikku-rpc-pending";
+export interface ChannelRPCRequest {
+    action: typeof CHANNEL_RPC_REQUEST;
+    id: string;
+    funcName: string;
+    data: unknown;
+    traceId?: string;
+}
+export interface ChannelRPCResponse {
+    action: typeof CHANNEL_RPC_RESPONSE;
+    id: string;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * "Still working on it — a human is being asked." Stops the caller's timeout,
+ * which otherwise fails any approval slower than it and then discards the
+ * answer when it arrives. Grants nothing: a peer that sends it dishonestly can
+ * only keep its own call waiting.
+ */
+export interface ChannelRPCPending {
+    action: typeof CHANNEL_RPC_PENDING;
+    id: string;
+    reason?: string;
+}
+/**
+ * The guards check the whole envelope, not just the action tag: `id` is peer
+ * input and is used as a map key, so a frame carrying one of the wrong type
+ * must not reach `settle`.
+ */
+export declare const isChannelRPCRequest: (message: unknown) => message is ChannelRPCRequest;
+export declare const isChannelRPCResponse: (message: unknown) => message is ChannelRPCResponse;
+export declare const isChannelRPCPending: (message: unknown) => message is ChannelRPCPending;
+/** `reason` exists so a dropped socket cannot look like a resolved call. */
+export declare class ChannelRPCError extends Error {
+    readonly reason: 'timeout' | 'closed' | 'remote' | 'invalid' | 'unsupported';
+    constructor(message: string, reason: 'timeout' | 'closed' | 'remote' | 'invalid' | 'unsupported');
+}
+/**
+ * Whether a callable exposed to a remote decider needs a human to agree before
+ * it runs, and how to describe the invocation while asking.
+ *
+ * Shared with `AIAgentToolDef`: both are an allowlist of named callables
+ * invoked by something other than the code that wrote them. The runtime around
+ * them is not shared — an agent suspends and resumes, a reverse call is a live
+ * await.
+ */
+export interface ApprovalPolicy {
+    needsApproval: boolean;
+    approvalDescriptionFn?: (input: unknown) => Promise<string> | string;
+}
+export type CapabilityHandler = (data: any) => Promise<unknown> | unknown;
+/**
+ * `needsApproval` is required here on purpose. On `AIAgentToolDef` the same
+ * field is optional and absence means "do not ask"; here absence means the
+ * opposite, so it must not be expressible — a bare function is the
+ * unclassified form.
+ */
+export interface CapabilityDef extends ApprovalPolicy {
+    execute: CapabilityHandler;
+}
+export type Capability = CapabilityHandler | CapabilityDef;
+export type Capabilities = Record<string, Capability>;
+export declare const isCapabilityDef: (capability: Capability) => capability is CapabilityDef;
+/**
+ * A bare function is unclassified, which resolves to needing approval:
+ * forgetting the annotation costs a prompt rather than costing a key.
+ */
+export declare const resolveCapability: (capability: Capability) => {
+    execute: CapabilityHandler;
+} & ApprovalPolicy;
+/** Returning false refuses the call, and the peer is told so. */
+export type ApprovalRequester = (request: {
+    funcName: string;
+    data: unknown;
+    description?: string;
+}) => Promise<boolean> | boolean;
+/** Checks one end of a call — arguments going out, or the answer coming back. */
+export type ChannelRPCValidator = (funcName: string, value: unknown) => Promise<void> | void;

package/dist/wirings/channel/channel-rpc.types.js

@@ -0,0 +1,50 @@
+/**
+ * Envelope actions for request/response RPC carried over an already-open
+ * channel. Both directions share one socket, so every frame is tagged and
+ * correlated by `id`.
+ */
+export const CHANNEL_RPC_REQUEST = 'pikku-rpc-request';
+export const CHANNEL_RPC_RESPONSE = 'pikku-rpc-response';
+export const CHANNEL_RPC_PENDING = 'pikku-rpc-pending';
+const isRecord = (message) => typeof message === 'object' && message !== null;
+/**
+ * The guards check the whole envelope, not just the action tag: `id` is peer
+ * input and is used as a map key, so a frame carrying one of the wrong type
+ * must not reach `settle`.
+ */
+export const isChannelRPCRequest = (message) => isRecord(message) &&
+    message.action === CHANNEL_RPC_REQUEST &&
+    typeof message.id === 'string' &&
+    message.id.length > 0 &&
+    typeof message.funcName === 'string' &&
+    message.funcName.length > 0 &&
+    (message.traceId === undefined || typeof message.traceId === 'string');
+export const isChannelRPCResponse = (message) => isRecord(message) &&
+    message.action === CHANNEL_RPC_RESPONSE &&
+    typeof message.id === 'string' &&
+    message.id.length > 0 &&
+    typeof message.ok === 'boolean';
+export const isChannelRPCPending = (message) => isRecord(message) &&
+    message.action === CHANNEL_RPC_PENDING &&
+    typeof message.id === 'string' &&
+    message.id.length > 0 &&
+    (message.reason === undefined || typeof message.reason === 'string');
+/** `reason` exists so a dropped socket cannot look like a resolved call. */
+export class ChannelRPCError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'ChannelRPCError';
+    }
+}
+export const isCapabilityDef = (capability) => typeof capability === 'object' &&
+    capability !== null &&
+    typeof capability.execute === 'function';
+/**
+ * A bare function is unclassified, which resolves to needing approval:
+ * forgetting the annotation costs a prompt rather than costing a key.
+ */
+export const resolveCapability = (capability) => isCapabilityDef(capability)
+    ? capability
+    : { execute: capability, needsApproval: true };

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

@@ -2,10 +2,6 @@ import type { CorePikkuPermission } from '../../function/functions.types.js';
 import type { SessionService } from '../../services/user-session-service.js';
 import type { CorePikkuMiddleware } from '../../types/core.types.js';
 import type { ChannelMeta, CoreChannel, RunChannelOptions, RunChannelParams } from './channel.types.js';
-/**
- * Adds a channel and registers all functions referenced in it using the
- * function names already stored in the channel metadata
- */
 export declare const wireChannel: <In, Channel extends string, PikkuPermission extends CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware, ChannelFunction>(channel: CoreChannel<In, Channel, PikkuPermission, PikkuMiddleware, ChannelFunction>) => void;
 export declare const openChannel: ({ route, coerceDataFromSchema, request, }: Pick<CoreChannel<unknown, string>, "route"> & RunChannelParams<unknown> & {
     userSession: SessionService<any>;

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

@@ -3,53 +3,39 @@ import { addFunction } from '../../function/function-runner.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js';
 import { httpRouter } from '../http/routers/http-router.js';
-/**
- * Adds a channel and registers all functions referenced in it using the
- * function names already stored in the channel metadata
- */
 export const wireChannel = (channel) => {
-    // Get the channel metadata
     const channelsMeta = pikkuState(null, 'channel', 'meta');
     const channelMeta = channelsMeta[channel.name];
     if (!channelMeta) {
         console.warn(`[pikku] Skipping channel '${channel.name}' — metadata not found. Consider moving this wiring to its own file.`);
         return;
     }
-    // Register onConnect function if provided
     if (channel.onConnect && channelMeta.connect) {
         addFunction(channelMeta.connect.pikkuFuncId, channel.onConnect);
     }
-    // Register onDisconnect function if provided
     if (channel.onDisconnect && channelMeta.disconnect) {
         addFunction(channelMeta.disconnect.pikkuFuncId, channel.onDisconnect);
     }
-    // Register onMessage function if provided
     if (channel.onMessage && channelMeta.message?.pikkuFuncId) {
         addFunction(channelMeta.message.pikkuFuncId, channel.onMessage.func instanceof Function
             ? channel.onMessage
             : channel.onMessage.func);
     }
-    // Register functions in onMessageWiring
     if (channel.onMessageWiring && channelMeta.messageWirings) {
-        // Iterate through each channel in onMessageWiring
         Object.entries(channel.onMessageWiring).forEach(([channelKey, wirings]) => {
             const channelWirings = channelMeta.messageWirings[channelKey];
             if (!channelWirings)
                 return;
-            // Iterate through each wiring in the channel
             Object.entries(wirings).forEach(([wiringKey, handler]) => {
                 const wiringMeta = channelWirings[wiringKey];
                 if (!wiringMeta)
                     return;
-                // Register the function using the pikku name from metadata
-                // It could be a FuncConfig or a wiring override with a funcConfig
                 addFunction(wiringMeta.pikkuFuncId, handler.func instanceof Function
                     ? handler
                     : handler.func);
             });
         });
     }
-    // Store the channel configuration
     pikkuState(null, 'channel', 'channels').set(channel.name, channel);
 };
 const getMatchingChannelConfig = (path) => {

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

@@ -13,16 +13,6 @@ 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;