@pikku/core 0.12.72 → 0.12.74

package/src/wirings/channel/channel-rpc.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/src/wirings/channel/channel-rpc.types.ts

@@ -0,0 +1,150 @@
+/**
+ * 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'
+
+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
+}
+
+const isRecord = (message: unknown): message is Record<string, unknown> =>
+  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: unknown
+): message is ChannelRPCRequest =>
+  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: unknown
+): message is ChannelRPCResponse =>
+  isRecord(message) &&
+  message.action === CHANNEL_RPC_RESPONSE &&
+  typeof message.id === 'string' &&
+  message.id.length > 0 &&
+  typeof message.ok === 'boolean'
+
+export const isChannelRPCPending = (
+  message: unknown
+): message is ChannelRPCPending =>
+  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 {
+  constructor(
+    message: string,
+    public readonly reason:
+      | 'timeout'
+      | 'closed'
+      | 'remote'
+      | 'invalid'
+      | 'unsupported'
+  ) {
+    super(message)
+    this.name = 'ChannelRPCError'
+  }
+}
+
+/**
+ * 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 const isCapabilityDef = (
+  capability: Capability
+): capability is CapabilityDef =>
+  typeof capability === 'object' &&
+  capability !== null &&
+  typeof (capability as CapabilityDef).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: Capability
+): { execute: CapabilityHandler } & ApprovalPolicy =>
+  isCapabilityDef(capability)
+    ? capability
+    : { execute: capability, needsApproval: true }
+
+/** 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/src/wirings/channel/channel-runner.ts

@@ -13,10 +13,6 @@ import type {
   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 const wireChannel = <
   In,
   Channel extends string,
@@ -32,7 +28,6 @@ export const wireChannel = <
     ChannelFunction
   >
 ) => {
-  // Get the channel metadata
   const channelsMeta = pikkuState(null, 'channel', 'meta')
   const channelMeta = channelsMeta[channel.name]
   if (!channelMeta) {
@@ -42,17 +37,14 @@ export const wireChannel = <
     return
   }
 
-  // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
     addFunction(channelMeta.connect.pikkuFuncId, channel.onConnect as any)
   }
 
-  // Register onDisconnect function if provided
   if (channel.onDisconnect && channelMeta.disconnect) {
     addFunction(channelMeta.disconnect.pikkuFuncId, channel.onDisconnect as any)
   }
 
-  // Register onMessage function if provided
   if (channel.onMessage && channelMeta.message?.pikkuFuncId) {
     addFunction(
       channelMeta.message.pikkuFuncId,
@@ -62,20 +54,15 @@ export const wireChannel = <
     )
   }
 
-  // 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 as any).func instanceof Function
@@ -86,7 +73,6 @@ export const wireChannel = <
     })
   }
 
-  // Store the channel configuration
   pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
 }
 

package/src/wirings/channel/channel-store.ts

@@ -24,16 +24,6 @@ export abstract class ChannelStore<
     | Promise<TypedChannel & { pikkuUserId?: string }>
     | (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.
-   */
   public abstract setState(
     channelId: string,
     state: unknown

package/src/wirings/channel/channel.types.ts

@@ -138,23 +138,34 @@ export type CoreChannel<
   tags?: string[]
 }
 
-export interface PikkuChannel<OpeningData, out Out> {
-  // The channel identifier
+/**
+ * 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
-  // The data the channel was created with. This could be query parameters
-  // or parameters in the url.
+  // Query parameters or url parameters the channel was created with.
   openingData: OpeningData
-  // The data to send. This will fail is the stream has been closed.
+  // Fails once the stream has been closed.
   send(data: Out, isBinary?: boolean): Promise<void> | void
   sendBinary(data: BinaryData): Promise<void> | void
-  // This will close the channel.
   close(): Promise<void> | void
-  // The current state of the channel
   state: 'initial' | 'open' | 'closed'
-  // Per-socket ephemeral state scoped to this channel connection.
   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> {

package/src/wirings/channel/define-channel-routes.ts

@@ -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<T extends Record<string, any>>(
   routes: T
 ): T {

package/src/wirings/channel/eventhub-service.ts

@@ -1,30 +1,12 @@
-/**
- * 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,

package/src/wirings/channel/index.ts

@@ -18,7 +18,42 @@ export type {
   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/src/wirings/channel/local/local-channel-handler.ts

@@ -64,7 +64,9 @@ export class PikkuLocalChannelHandler<
       return
     }
     super.close()
-    const results = await Promise.allSettled(this.closeCallbacks.map((cb) => cb()))
+    const results = await Promise.allSettled(
+      this.closeCallbacks.map((cb) => cb())
+    )
     for (const result of results) {
       if (result.status === 'rejected') {
         this.logger?.error('Error in channel close callback:', result.reason)

package/src/wirings/channel/local/local-channel-runner.test.ts

@@ -14,11 +14,6 @@ import type { SerializeOptions } from 'cookie'
 import { httpRouter } from '../../http/routers/http-router.js'
 import { pikkuMiddleware } from '../../../types/core.types.js'
 
-/**
- * Minimal stubs for dependencies that runChannel expects.
- * In a real test setup, you may provide more comprehensive mocks
- * or refactor your code to allow dependency injection.
- */
 const mockLogger = {
   info: () => {},
   error: () => {},
@@ -30,7 +25,6 @@ const mockSingletonServices = {
   logger: mockLogger,
 } as any
 
-// Mock request and response objects
 export class PikkuMockRequest implements PikkuHTTPRequest {
   private _params: Record<string, string | string[] | undefined> = {}
 
@@ -93,7 +87,6 @@ export class PikkuMockResponse implements PikkuHTTPResponse {
     throw new Error('Method not implemented.')
   }
   json(data: unknown): this {
-    // We don't need to implement this for our test
     return this
   }
   redirect(location: string, status?: number): this {
@@ -134,7 +127,6 @@ test('runChannel should return undefined and 404 if no matching channel is found
     'Should return undefined if no channel matches'
   )
   assert.equal(mockResponse._status, 404, 'Should set response status to 404')
-  // assert.equal(mockResponse._ended, true, 'Should end the response')
 })
 
 test('runChannel should return a channel handler if channel matches and no auth required', async () => {
@@ -156,7 +148,6 @@ test('runChannel should return a channel handler if channel matches and no auth
     auth: false,
   })
 
-  // Initialize router after adding channel (for tests)
   httpRouter.initialize()
 
   const result = await runLocalChannel({
@@ -168,7 +159,6 @@ test('runChannel should return a channel handler if channel matches and no auth
 
   assert.ok(result, 'Should return a PikkuChannelHandler instance')
 
-  // Simulate opening the channel
   result.open()
 })
 

package/src/wirings/channel/local/local-channel-runner.ts

@@ -40,7 +40,7 @@ const runUpgradeMiddleware = async (
   const wireInheritedMiddleware = httpGroups['*']
     ? [{ type: 'http' as const, route: '*' }]
     : undefined
-  const middleware = combineMiddleware('channel', `upgrade:${request.path()}`, {
+  const middleware = combineMiddleware('channel', 'upgrade', {
     wireInheritedMiddleware,
   })
 
@@ -158,6 +158,7 @@ export const runLocalChannel = async ({
               channel,
               data: openingData,
               channelMiddlewareMeta: meta.channelMiddleware,
+              userSession,
             })
             if (result !== undefined) {
               await channel.send(result)
@@ -186,6 +187,7 @@ export const runLocalChannel = async ({
               services,
               channel,
               channelMiddlewareMeta: meta.channelMiddleware,
+              userSession,
             })
           } catch (e: any) {
             singletonServices.logger.error(`Error handling onDisconnect: ${e}`)

package/src/wirings/channel/local/local-eventhub-service.test.ts

@@ -15,7 +15,6 @@ class MockChannelHandler implements PikkuChannelHandler {
   }
 
   send(data: unknown, isBinary?: boolean) {
-    // Mock send functionality
     console.log(`Sent to ${this.channelId}:`, { data, isBinary })
   }
 }
@@ -23,11 +22,9 @@ class MockChannelHandler implements PikkuChannelHandler {
 test('LocalEventHubService: subscribe and unsubscribe', () => {
   const eventHub = new LocalEventHubService()
 
-  // Subscribe a channel to a topic
   eventHub.subscribe('topic1', 'channel1')
   assert.strictEqual(eventHub['subscriptions'].get('topic1')!.size, 1)
 
-  // Unsubscribe the channel
   eventHub.unsubscribe('topic1', 'channel1')
   assert.strictEqual(eventHub['subscriptions'].has('topic1'), false)
 })
@@ -35,17 +32,14 @@ test('LocalEventHubService: subscribe and unsubscribe', () => {
 test('LocalEventHubService: publish messages', () => {
   const eventHub = new LocalEventHubService()
 
-  // Register mock channels
   const channel1 = new MockChannelHandler('channel1')
   const channel2 = new MockChannelHandler('channel2')
   eventHub.onChannelOpened(channel1)
   eventHub.onChannelOpened(channel2)
 
-  // Subscribe channels to a topic
   eventHub.subscribe('topic1', 'channel1')
   eventHub.subscribe('topic1', 'channel2')
 
-  // Mock `send` method to track calls
   let sendCallCount = 0
   channel1.send = () => {
     sendCallCount++
@@ -54,22 +48,18 @@ test('LocalEventHubService: publish messages', () => {
     sendCallCount++
   }
 
-  // Publish a message
   eventHub.publish('topic1', 'channel1', { message: 'Hello!' })
 
-  // Ensure the message was sent only to channel2
   assert.strictEqual(sendCallCount, 1)
 })
 
 test('LocalEventHubService: onChannelOpened and onChannelClosed', () => {
   const eventHub = new LocalEventHubService()
 
-  // Register and verify channel
   const channel1 = new MockChannelHandler('channel1')
   eventHub.onChannelOpened(channel1)
   assert.strictEqual(eventHub['channels'].has('channel1'), true)
 
-  // Close and verify removal
   eventHub.onChannelClosed('channel1')
   assert.strictEqual(eventHub['channels'].has('channel1'), false)
 })
@@ -77,14 +67,11 @@ test('LocalEventHubService: onChannelOpened and onChannelClosed', () => {
 test('LocalEventHubService: clean up empty topics on channel close', () => {
   const eventHub = new LocalEventHubService()
 
-  // Register and subscribe channels
   const channel1 = new MockChannelHandler('channel1')
   eventHub.onChannelOpened(channel1)
   eventHub.subscribe('topic1', 'channel1')
 
-  // Close channel
   eventHub.onChannelClosed('channel1')
 
-  // Ensure topic1 is removed
   assert.strictEqual(eventHub['subscriptions'].has('topic1'), false)
 })

package/src/wirings/channel/local/local-eventhub-service.ts

@@ -1,26 +1,12 @@
 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 class LocalEventHubService<
   Data extends Record<string, any> = {},
 > implements EventHubService<Data> {
   private channels = new Map<string, PikkuChannelHandler>()
-
-  /**
-   * A map storing topics and their associated connection IDs.
-   */
   private subscriptions: Map<keyof Data, Set<string>> = 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.
-   */
   public subscribe<T extends keyof Data>(
     topic: T,
     channelId: string
@@ -31,12 +17,6 @@ export class LocalEventHubService<
     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.
-   */
   public unsubscribe<T extends keyof Data>(
     topic: T,
     channelId: string
@@ -50,11 +30,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.
-   */
   public publish<T extends keyof Data>(
     topic: T,
     channelId: string | null,
@@ -66,37 +41,27 @@ export class LocalEventHubService<
       return
     }
     for (const toChannelId of subscribedChannelIds) {
-      if (channelId === toChannelId) continue // Skip sending to the sender
+      if (channelId === toChannelId) 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
-   */
   public onChannelOpened(channelHandler: PikkuChannelHandler): void {
     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.
-   */
   public onChannelClosed(channelId: string): void {
     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/src/wirings/channel/log-channels.ts

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