@pikku/core 0.12.71 → 0.12.74

package/src/wirings/channel/channel-host-rpc.ts

@@ -0,0 +1,69 @@
+import {
+  ChannelDeploymentService,
+  createChannelRPCInputValidator,
+  createChannelRPCResultValidator,
+} from './channel-rpc.js'
+import type { ChannelRPCValidator } from './channel-rpc.js'
+import type { PikkuChannel } from './channel.types.js'
+import { getSingletonServices } from '../../pikku-state.js'
+
+/** Reverse-RPC transports, one per open connection. */
+const hostRPCByChannel = new Map<string, ChannelDeploymentService>()
+
+/**
+ * The transport for a connection, created on first use. `options` apply only
+ * to the call that creates it — one connection has one transport, so the first
+ * caller's timeout and validators become the connection's.
+ */
+export const getChannelHostRPC = (
+  channel: PikkuChannel<unknown, any>,
+  options: {
+    timeoutMs?: number
+    validateInput?: ChannelRPCValidator
+    validateResult?: ChannelRPCValidator
+  } = {}
+): ChannelDeploymentService => {
+  let service = hostRPCByChannel.get(channel.channelId)
+  if (!service) {
+    service = new ChannelDeploymentService(
+      (data) => channel.send(data),
+      options
+    )
+    hostRPCByChannel.set(channel.channelId, service)
+  }
+  return service
+}
+
+/**
+ * Kept out of the channel handler so a channel nobody calls back on pays for no
+ * registry, and because a handler has no services to build a validator with.
+ */
+export const channelRemote = async (
+  channel: PikkuChannel<unknown, any, any>,
+  funcName: string,
+  data?: unknown
+): Promise<unknown> =>
+  getChannelHostRPC(channel, {
+    validateInput: createChannelRPCInputValidator(getSingletonServices()),
+    validateResult: createChannelRPCResultValidator(getSingletonServices()),
+  }).invoke(funcName, data)
+
+/** False for an unknown connection or id, so a stray frame is dropped. */
+export const handleChannelRPCResponse = (
+  channelId: string,
+  message: unknown
+): boolean => hostRPCByChannel.get(channelId)?.handleResponse(message) ?? false
+
+/**
+ * Must run on disconnect: without it a caller waits out the full timeout on a
+ * dead socket, and the map grows for the life of the process.
+ */
+export const releaseChannelHostRPC = async (
+  channelId: string
+): Promise<void> => {
+  const service = hostRPCByChannel.get(channelId)
+  if (service) {
+    hostRPCByChannel.delete(channelId)
+    await service.stop()
+  }
+}

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

@@ -79,7 +79,6 @@ describe('combineChannelMiddleware', () => {
 
     assert.deepEqual(first, [shared])
 
-    // Re-registering after the first resolve does not change the cached result.
     addChannelMiddleware('chat:outbound', [async () => {}])
 
     const cached = combineChannelMiddleware('channel', 'cached-1', {

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

@@ -36,18 +36,6 @@ export const clearChannelMiddlewareCache = () => {
   }
 }
 
-/**
- * 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: string,
   uid: string,

package/src/wirings/channel/channel-rpc-registry.ts

@@ -0,0 +1,116 @@
+import {
+  ChannelRPCError,
+  type ChannelRPCResponse,
+} from './channel-rpc.types.js'
+
+interface PendingCall {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer?: ReturnType<typeof setTimeout>
+  awaitingHuman?: boolean
+}
+
+/**
+ * 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 {
+  private pending = new Map<string, PendingCall>()
+  private nextId = 0
+  private closed = false
+
+  constructor(private readonly timeoutMs: number = 30_000) {}
+
+  public get inFlight(): number {
+    return this.pending.size
+  }
+
+  public register(): { id: string; promise: Promise<unknown> } {
+    if (this.closed) {
+      return {
+        id: '',
+        promise: Promise.reject(
+          new ChannelRPCError('Channel is closed', 'closed')
+        ),
+      }
+    }
+
+    const id = `${++this.nextId}`
+    const promise = new Promise<unknown>((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.
+   */
+  public hold(id: string): boolean {
+    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. */
+  public settle(response: ChannelRPCResponse): boolean {
+    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. */
+  public rejectAll(reason: string = 'Channel closed'): void {
+    this.closed = true
+    for (const [, call] of this.pending) {
+      clearTimeout(call.timer)
+      call.reject(new ChannelRPCError(reason, 'closed'))
+    }
+    this.pending.clear()
+  }
+}

package/src/wirings/channel/channel-rpc-responder.ts

@@ -0,0 +1,117 @@
+import {
+  CHANNEL_RPC_PENDING,
+  CHANNEL_RPC_RESPONSE,
+  isCapabilityDef,
+  isChannelRPCRequest,
+  resolveCapability,
+  type ApprovalRequester,
+  type Capabilities,
+  type ChannelRPCPending,
+  type ChannelRPCResponse,
+} 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,
+}: {
+  capabilities: Capabilities
+  send: (data: unknown) => Promise<void> | void
+  /** Omitted means there is nobody to ask, which refuses rather than runs. */
+  approve?: ApprovalRequester
+}) => {
+  return async (message: unknown): Promise<boolean> => {
+    if (!isChannelRPCRequest(message)) {
+      return false
+    }
+
+    const refuse = (name: string, why: string): ChannelRPCResponse => ({
+      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: ChannelRPCResponse
+    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}`,
+        } satisfies ChannelRPCPending)
+
+        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: unknown) {
+      const error = e as Error
+      response = refuse(error?.name ?? 'Error', error?.message ?? String(e))
+    }
+
+    await send(response)
+    return true
+  }
+}

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

@@ -0,0 +1,146 @@
+import type { DeploymentService } from '../../services/deployment-service.js'
+import { ChannelRPCRegistry } from './channel-rpc-registry.js'
+import {
+  CHANNEL_RPC_REQUEST,
+  CHANNEL_RPC_RESPONSE,
+  ChannelRPCError,
+  isChannelRPCPending,
+  isChannelRPCResponse,
+  type ChannelRPCRequest,
+  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 const unsupportedChannelRemote = async (
+  funcName: string
+): Promise<never> => {
+  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 implements DeploymentService {
+  public readonly registry: ChannelRPCRegistry
+  private readonly validateInput?: ChannelRPCValidator
+  private readonly validateResult?: ChannelRPCValidator
+
+  constructor(
+    private readonly send: (data: unknown) => Promise<void> | void,
+    options: {
+      timeoutMs?: number
+      validateInput?: ChannelRPCValidator
+      validateResult?: ChannelRPCValidator
+    } = {}
+  ) {
+    this.registry = new ChannelRPCRegistry(options.timeoutMs)
+    this.validateInput = options.validateInput
+    this.validateResult = options.validateResult
+  }
+
+  public async init(): Promise<void> {}
+
+  public async start(): Promise<void> {}
+
+  public async stop(): Promise<void> {
+    this.registry.rejectAll('Deployment service stopped')
+  }
+
+  /** The channel owner must call this — the service has no read side. */
+  public handleResponse(message: unknown): boolean {
+    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.
+   */
+  public async invoke(
+    funcName: string,
+    data: unknown,
+    _session?: unknown,
+    traceId?: string
+  ): Promise<unknown> {
+    // 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: unknown) {
+        throw new ChannelRPCError(
+          `Invalid arguments for "${funcName}": ${(e as Error)?.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: ChannelRPCRequest = {
+      action: CHANNEL_RPC_REQUEST,
+      id,
+      funcName,
+      data,
+      traceId,
+    }
+
+    try {
+      await this.send(request)
+    } catch (e: unknown) {
+      // 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 as Error)?.name ?? 'Error',
+          message: (e as Error)?.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: unknown) {
+      throw new ChannelRPCError(
+        `Invalid result from "${funcName}": ${(e as Error)?.message ?? String(e)}`,
+        'invalid'
+      )
+    }
+    return result
+  }
+}

package/src/wirings/channel/channel-rpc-validators.ts

@@ -0,0 +1,65 @@
+import type { CoreSingletonServices } from '../../types/core.types.js'
+import { pikkuState } from '../../pikku-state.js'
+import { validateSchema } from '../../schema.js'
+import type { ChannelRPCValidator } from './channel-rpc.types.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: 'inputSchemaName' | 'outputSchemaName',
+    singletonServices: Pick<CoreSingletonServices, 'logger' | 'schema'>,
+    packageName: string | null = null
+  ): ChannelRPCValidator =>
+  async (funcName: string, value: unknown): Promise<void> => {
+    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: Pick<CoreSingletonServices, 'logger' | 'schema'>,
+  packageName: string | null = null
+): ChannelRPCValidator =>
+  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: Pick<CoreSingletonServices, 'logger' | 'schema'>,
+  packageName: string | null = null
+): ChannelRPCValidator =>
+  createChannelRPCSchemaValidator(
+    'inputSchemaName',
+    singletonServices,
+    packageName
+  )