@pikku/core 0.12.80 → 0.12.82

package/src/wirings/ai-scorer/ai-scorer.ts

@@ -0,0 +1,76 @@
+import type {
+  PikkuAIScorer,
+  ScorerInput,
+  ScorerOutput,
+} from './ai-scorer.types.js'
+
+const assertSampleRate = (name: string, sampleRate: number | undefined) => {
+  if (sampleRate === undefined) return 1
+  if (sampleRate < 0 || sampleRate > 1) {
+    throw new Error(
+      `Scorer '${name}' has a sampleRate of ${sampleRate} — it is a fraction of live runs to grade, so it must be between 0 and 1`
+    )
+  }
+  return sampleRate
+}
+
+/**
+ * A heuristic scorer: pure code over the finished run, no model call, so it
+ * grades on the fast lane.
+ */
+export const pikkuAIScorer = <Services = any>(config: {
+  name: string
+  description: string
+  /** 0..1 fraction of live runs to grade. Defaults to all of them. */
+  sampleRate?: number
+  /**
+   * Grades against a known-correct answer. Such a scorer is test-only — live
+   * traffic has no answer key, so the runtime never samples it.
+   */
+  requiresReference?: boolean
+  score: (
+    input: ScorerInput,
+    services: Services
+  ) => ScorerOutput | Promise<ScorerOutput>
+}): PikkuAIScorer<Services> => ({
+  name: config.name,
+  description: config.description,
+  lane: 'fast',
+  sampleRate: assertSampleRate(config.name, config.sampleRate),
+  requiresReference: config.requiresReference ?? false,
+  score: config.score,
+})
+
+/**
+ * An LLM-judge scorer: the runtime makes the model call and forces a structured
+ * `{ score, reason }`, so a judge is a rubric rather than a prompt to parse.
+ *
+ * The rubric field is `goal`, matching `pikkuAIAgent`'s prompt vocabulary — a
+ * judge is a degenerate agent, and should use the same word for the same thing.
+ * `prompt` is the escape hatch for non-standard framing.
+ */
+export const pikkuAIJudge = <Services = any>(config: {
+  name: string
+  description: string
+  /** 0..1 fraction of live runs to grade. Defaults to all of them. */
+  sampleRate?: number
+  /**
+   * Grades against a known-correct answer. Such a judge is test-only — live
+   * traffic has no answer key, so the runtime never samples it.
+   */
+  requiresReference?: boolean
+  model: string
+  goal: string
+  prompt?: (input: ScorerInput) => string
+}): PikkuAIScorer<Services> => ({
+  name: config.name,
+  description: config.description,
+  lane: 'slow',
+  sampleRate: assertSampleRate(config.name, config.sampleRate),
+  requiresReference: config.requiresReference ?? false,
+  judge: {
+    model: config.model,
+    goal: config.goal,
+    ...(config.prompt ? { prompt: config.prompt } : {}),
+  },
+})

package/src/wirings/ai-scorer/ai-scorer.types.ts

@@ -0,0 +1,107 @@
+/**
+ * What a scorer is shown about a finished run.
+ *
+ * One snapshot, taken after the output middleware has resolved, so a scorer and
+ * the persisted run record see the same thing — including the redactions.
+ */
+export interface ScorerInput {
+  runId: string
+  agentName: string
+  threadId?: string
+  resourceId?: string
+  /** The user prompt the run answered. */
+  input: string
+  /** The agent's final text answer. */
+  output: string
+  /**
+   * The known-correct answer. Supplied by a scenario for a reference-based
+   * judge; never set on live traffic, which has no answer key.
+   */
+  reference?: string
+  toolCalls: {
+    name: string
+    args: unknown
+    result?: unknown
+    error?: string
+  }[]
+  usage: {
+    inputTokens: number
+    outputTokens: number
+    model?: string
+  }
+}
+
+export interface ScorerOutput {
+  /** 0..1, so grades are comparable across scorers. */
+  score: number
+  reason?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * The queue a scorer's jobs go to. Two lanes exist only so a flood of slow
+ * LLM-judge jobs cannot starve the cheap heuristic ones; within a lane it is
+ * plain FIFO.
+ */
+export type ScorerLane = 'fast' | 'slow'
+
+export const SCORER_LANE_QUEUES: Record<ScorerLane, string> = {
+  fast: 'ai-score-fast',
+  slow: 'ai-score-slow',
+}
+
+/**
+ * A judge's model call. Present only on a scorer built with `pikkuAIJudge`;
+ * `score` is present only on one built with `pikkuAIScorer`. Exactly one of the
+ * two is set, which is what the two constructors exist to guarantee.
+ */
+export type ScorerJudgeConfig = {
+  model: string
+  goal: string
+  prompt?: (input: ScorerInput) => string
+}
+
+export type PikkuAIScorer<Services = any> = {
+  name: string
+  description: string
+  lane: ScorerLane
+  /** 0..1 fraction of live runs to grade. */
+  sampleRate: number
+  /**
+   * Grades against a known-correct answer, so it is test-only: live traffic has
+   * no answer key and the runtime never samples it.
+   */
+  requiresReference: boolean
+  score?: (
+    input: ScorerInput,
+    services: Services
+  ) => ScorerOutput | Promise<ScorerOutput>
+  judge?: ScorerJudgeConfig
+}
+
+export type ScorerMeta = Record<
+  string,
+  {
+    name: string
+    description: string
+    lane: ScorerLane
+    sampleRate: number
+    requiresReference: boolean
+    sourceFile?: string
+    exportedName?: string
+  }
+>
+
+/** A single scorer's job on a lane queue. */
+export type ScoreJob = ScorerInput & {
+  scorerName: string
+}
+
+export type AIRunScore = {
+  runId: string
+  scorerName: string
+  score: number
+  reason?: string
+  metadata?: Record<string, unknown>
+  createdAt: Date
+}

package/src/wirings/ai-scorer/index.ts

@@ -0,0 +1,24 @@
+export { pikkuAIScorer, pikkuAIJudge } from './ai-scorer.js'
+export {
+  addAIScorer,
+  getAIScorers,
+  getAIScorersMeta,
+} from './ai-scorer-registry.js'
+export { gradeRun } from './ai-scorer-grade.js'
+export {
+  enableScoreSnapshots,
+  getScoreSnapshot,
+} from './ai-scorer-snapshots.js'
+export {
+  wireAIScorerQueueWorkers,
+} from './ai-scorer-worker.js'
+export type {
+  AIRunScore,
+  PikkuAIScorer,
+  ScoreJob,
+  ScorerInput,
+  ScorerJudgeConfig,
+  ScorerLane,
+  ScorerMeta,
+  ScorerOutput,
+} from './ai-scorer.types.js'

package/src/wirings/channel/index.ts

@@ -1,8 +1,7 @@
-export { wireChannel, openChannel } from './channel-runner.js'
+export { wireChannel } from './channel-runner.js'
 export {
   addChannelMiddleware,
   combineChannelMiddleware,
-  wrapChannelWithMiddleware,
 } from './channel-middleware-runner.js'
 export { logChannels } from './log-channels.js'
 export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
@@ -18,25 +17,14 @@ 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 {
@@ -44,16 +32,9 @@ export type {
   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-runner.test.ts

@@ -3,6 +3,7 @@ import * as assert from 'node:assert/strict'
 import { runLocalChannel } from './local-channel-runner.js'
 import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
 import { wireChannel } from '../channel-runner.js'
+import { addFunction } from '../../../function/function-runner.js'
 import { addHTTPMiddleware } from '../../http/http-runner.js'
 import type {
   HTTPMethod,
@@ -270,3 +271,70 @@ test('runChannel should run HTTP middleware on websocket upgrade and establish s
   await result.message(JSON.stringify({ action: 'ping' }))
   assert.deepEqual(sent, { action: 'ping' })
 })
+
+test('a message handler that returns nothing does not attempt to send', async () => {
+  // The connect path already guards this; the message path did not, so a handler
+  // with nothing to say produced `send requires a non-empty message` on every
+  // message. Gateway websockets hit it every time — their generated message
+  // handler returns undefined by design — which is why a chat gateway could
+  // accept a connection and never deliver anything to its handler.
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
+
+  const sent: unknown[] = []
+  let handled = 0
+
+  pikkuState(null, 'channel', 'meta', {
+    quiet: {
+      name: 'quiet',
+      route: '/quiet-channel',
+      message: { pikkuFuncId: 'quietMessage' },
+      messageWirings: {},
+    },
+  } as any)
+  pikkuState(null, 'function', 'meta')['quietMessage'] = {
+    pikkuFuncId: 'quietMessage',
+    inputSchemaName: null,
+    outputSchemaName: null,
+    sessionless: true,
+  } as any
+  const quietMessage = {
+    auth: false,
+    func: async () => {
+      handled++
+      return undefined
+    },
+  }
+  wireChannel({
+    name: 'quiet',
+    route: '/quiet-channel',
+    auth: false,
+    onMessage: quietMessage as any,
+  } as any)
+
+  httpRouter.initialize()
+
+  const handler = await runLocalChannel({
+    channelId: 'quiet-channel-id',
+    request: new PikkuMockRequest('/quiet-channel', 'get'),
+    response: new PikkuMockResponse(),
+    route: '/quiet-channel',
+  })
+  assert.ok(handler)
+  handler.registerOnSend(async (message: unknown) => {
+    sent.push(message)
+  })
+  handler.open()
+
+  await handler.message(JSON.stringify({ text: 'hello' }))
+
+  assert.equal(handled, 1, 'the handler should have run')
+  assert.deepEqual(
+    sent,
+    [],
+    'nothing should have been sent for an empty result'
+  )
+})

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

@@ -213,7 +213,14 @@ export const runLocalChannel = async ({
       channelHandler.registerOnMessage(async (data) => {
         try {
           const result = await onMessage(data)
-          await channel.send(result)
+          // Guarded exactly as the connect path above is. A handler with nothing
+          // to say is normal — a gateway websocket's generated message handler
+          // always returns undefined — and sending that raised `send requires a
+          // non-empty message`, which surfaced as a channel that accepted a
+          // connection and then silently delivered nothing.
+          if (result !== undefined) {
+            await channel.send(result)
+          }
         } catch (e: any) {
           singletonServices.logger.error(e)
           const errorResponse = getErrorResponse(e)

package/src/wirings/cli/channel/cli-raw-channel-runner.test.ts

@@ -103,6 +103,29 @@ describe('handleRawCLI', () => {
     assert.match(result.error!, /deploy plan is red/)
   })
 
+  test('masks the raw error message to the client in production', async () => {
+    const prior = process.env.NODE_ENV
+    process.env.NODE_ENV = 'production'
+    try {
+      wireTestCLI(() => {
+        throw new Error('connection to internal-db:5432 failed: bad password')
+      })
+
+      const result = await handleRawCLI({
+        programName: 'fabric',
+        args: ['deploy'],
+        singletonServices,
+      })
+
+      assert.equal(result.exitCode, 1)
+      assert.equal(result.error, 'Command failed')
+      assert.doesNotMatch(result.error!, /internal-db|password/)
+    } finally {
+      if (prior === undefined) delete process.env.NODE_ENV
+      else process.env.NODE_ENV = prior
+    }
+  })
+
   test('exits 0 on help and 1 on an unknown command', async () => {
     wireTestCLI(() => ({}))
 

package/src/wirings/cli/channel/cli-raw-channel-runner.ts

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../../pikku-state.js'
+import { isProduction } from '../../../env.js'
 import type { CLIMeta } from '../cli.types.js'
 import { parseCLIArguments, generateCommandHelp } from '../command-parser.js'
 import { runCLICommand } from '../cli-runner.js'
@@ -132,6 +133,16 @@ export async function handleRawCLI({
     // A command can throw anything; `.message` off a string is undefined, and
     // the run would then exit 1 saying nothing at all.
     const message = e instanceof Error ? e.message : String(e)
-    return { error: message || 'Command failed', exitCode: 1, commandId }
+    // The raw message can carry internals (a stack, a DB error, a path). This
+    // runs over a channel that may be remote, so return a generic error in
+    // production and keep the detail server-side. Dev keeps the message inline.
+    singletonServices.logger.error?.(
+      `CLI channel command failed: ${message}`,
+      e
+    )
+    const clientError = isProduction()
+      ? 'Command failed'
+      : message || 'Command failed'
+    return { error: clientError, exitCode: 1, commandId }
   }
 }

package/src/wirings/cli/channel/index.ts

@@ -3,13 +3,6 @@ export { handleRawCLI } from './cli-raw-channel-runner.js'
 export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js'
 export { executeRawCLIViaChannel } from './cli-raw-client-runner.js'
 export type {
-  ClientCLIRenderServices,
   CorePikkuCLIClientRender,
 } from './cli-raw-client-runner.js'
-export {
-  APPROVAL_FLAGS,
-  approverForMode,
-  createTerminalApprover,
-  takeApprovalFlags,
-} from './cli-approval.js'
 export type { ApprovalMode } from './cli-approval.js'

package/src/wirings/cli/cli-runner.test.ts

@@ -396,6 +396,74 @@ describe('CLI Runner', () => {
       const programs = pikkuState(null, 'cli', 'programs')
       assert.strictEqual(programs['nonexistent'], undefined)
     })
+
+    test('enforces command-level permissions declared on a CLI command', async () => {
+      let functionRan = false
+
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'sec-cli': {
+            program: 'sec-cli',
+            commands: {
+              secret: {
+                command: 'secret',
+                pikkuFuncId: 'secretFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+      pikkuState(null, 'function', 'meta', {
+        secretFunc: {
+          pikkuFuncId: 'secretFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+          sessionless: true,
+        },
+      })
+
+      wireCLI({
+        program: 'sec-cli',
+        commands: {
+          // command.func is a function-config object, so unwrapFunc reads the
+          // inner func's auth/permissions and previously dropped the
+          // command-level ones — the branch this fix restores.
+          secret: {
+            func: {
+              func: async () => {
+                functionRan = true
+                return {}
+              },
+            },
+            // A permission that always denies.
+            permissions: { deny: async () => false },
+          } as any,
+        },
+      })
+
+      const result = await runCLICommand({
+        program: 'sec-cli',
+        commandPath: ['secret'],
+        data: {},
+        singletonServices,
+        createWireServices,
+      }).catch((error) => ({ success: false, error }))
+
+      assert.equal(
+        functionRan,
+        false,
+        'the function must not run when a declared permission denies'
+      )
+      assert.notEqual(
+        (result as any).success,
+        true,
+        'the command must not report success when permission is denied'
+      )
+    })
   })
 
   describe('pikkuCLIRender', () => {

package/src/wirings/cli/cli-runner.ts

@@ -169,7 +169,24 @@ function registerCLICommands(
       }
     }
 
-    addFunction(funcName, unwrapFunc(command), currentMeta?.packageName)
+    // Merge the command-level auth/permissions into the registered config so
+    // they are actually enforced by the function runner. They were accepted by
+    // the types but dropped here, making a command's declared access control a
+    // silent no-op. Command-level wins over the handler's own, then falls back
+    // to it.
+    const unwrapped = unwrapFunc(command)
+    const commandAuth = typeof command === 'object' ? command.auth : undefined
+    const commandPermissions =
+      typeof command === 'object' ? command.permissions : undefined
+    addFunction(
+      funcName,
+      {
+        ...unwrapped,
+        auth: commandAuth ?? unwrapped.auth,
+        permissions: commandPermissions ?? unwrapped.permissions,
+      },
+      currentMeta?.packageName
+    )
 
     if (typeof command === 'object' && command.render) {
       if (programs[program]) {

package/src/wirings/credential/index.ts

@@ -2,7 +2,6 @@ export { defineCredential } from './define-credential.js'
 export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js'
 export type {
   CoreCredential,
-  CredentialDefinitionMeta,
   CredentialDefinitionsMeta,
   CredentialDefinitions,
 } from './credential.types.js'

package/src/wirings/gateway/index.ts

@@ -6,13 +6,10 @@ export {
 export type {
   GatewayAdapter,
   GatewayAdapterFactory,
-  GatewayAttachment,
   GatewayInboundMessage,
   GatewayOutboundMessage,
-  GatewayMeta,
   GatewaysMeta,
   GatewayTransportType,
   CoreGateway,
-  PikkuGateway,
   WebhookVerificationResult,
 } from './gateway.types.js'

package/src/wirings/http/http-runner.test.ts

@@ -70,6 +70,11 @@ class TestResponse extends PikkuMockResponse {
     return this
   }
 
+  redirect(location: string, status: number = 302): this {
+    this.status(status)
+    return this.header('Location', location)
+  }
+
   setMode(mode: 'stream') {
     this.mode = mode
   }
@@ -365,6 +370,67 @@ describe('http-runner helpers', () => {
     assert.equal(response.statusCode, 204)
   })
 
+  test('fetchData keeps a redirect status when the route returns undefined', async () => {
+    setRouteMeta('/redirect')
+    addFunction('pikku_func_name', {
+      func: async (_services: any, _data: any, { http }: any) => {
+        http?.response?.redirect('https://example.com/done', 302)
+      },
+    })
+    wireHTTP({
+      route: '/redirect',
+      method: 'get',
+      auth: false,
+      func: {
+        func: async (_services: any, _data: any, { http }: any) => {
+          http?.response?.redirect('https://example.com/done', 302)
+        },
+      },
+    })
+    httpRouter.initialize()
+
+    const request = new TestRequest('/redirect', 'get')
+    const response = new TestResponse()
+
+    await fetchData(request, response)
+
+    assert.equal(response.statusCode, 302)
+    assert.equal(
+      response.headersMap.get('Location'),
+      'https://example.com/done'
+    )
+  })
+
+  test('fetchData keeps a status the route set alongside a body', async () => {
+    setRouteMeta('/created')
+    addFunction('pikku_func_name', {
+      func: async (_services: any, _data: any, { http }: any) => {
+        http?.response?.status(201)
+        return { id: 'thing-1' }
+      },
+    })
+    wireHTTP({
+      route: '/created',
+      method: 'get',
+      auth: false,
+      func: {
+        func: async (_services: any, _data: any, { http }: any) => {
+          http?.response?.status(201)
+          return { id: 'thing-1' }
+        },
+      },
+    })
+    httpRouter.initialize()
+
+    const request = new TestRequest('/created', 'get')
+    const response = new TestResponse()
+
+    await fetchData(request, response)
+
+    assert.equal(response.statusCode, 201)
+    assert.deepEqual(response.jsonBody, { id: 'thing-1' })
+  })
+
   test('fetchData writes binary responses when returnsJSON is false', async () => {
     setRouteMeta('/binary')
     wireHTTP({

package/src/wirings/http/http-runner.ts

@@ -283,6 +283,8 @@ const executeRoute = async (
     hasSessionChanged: () => userSession.sessionChanged,
   }
 
+  const statusBeforeRoute = http?.response?.statusCode
+
   try {
     result = await runPikkuFunc(
       'http',
@@ -323,14 +325,20 @@ const executeRoute = async (
   if (matchedRoute.route.sse) {
     http?.response?.flushHeaders?.()
   } else {
+    const statusSetByRoute = http?.response?.statusCode !== statusBeforeRoute
+
     if (result instanceof Response) {
       await applyWebResponse(http!.response!, result)
     } else if (result === undefined || result === null) {
-      http?.response?.status(204)
+      if (!statusSetByRoute) {
+        http?.response?.status(204)
+      }
     } else if (route.returnsJSON === false) {
       http?.response?.arrayBuffer(result)
     } else {
-      http?.response?.status(200)
+      if (!statusSetByRoute) {
+        http?.response?.status(200)
+      }
       http?.response?.json(result)
     }
   }

package/src/wirings/http/index.ts

@@ -2,7 +2,6 @@ export {
   PikkuFetchHTTPRequest,
   DEFAULT_MAX_BODY_SIZE,
 } from './pikku-fetch-http-request.js'
-export type { PikkuFetchHTTPRequestOptions } from './pikku-fetch-http-request.js'
 export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 export { logRoutes } from './log-http-routes.js'
 
@@ -19,6 +18,7 @@ export type {
   HTTPRouteContract,
   HTTPRouteMap,
   HTTPWiringsMeta,
+  PikkuHTTP,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
   PikkuQuery,

package/src/wirings/mcp/index.ts

@@ -16,7 +16,6 @@ export type {
   AssertMCPResourceURIParams,
   CoreMCPPrompt,
   CoreMCPResource,
-  CoreMCPTool,
   MCPPromptResponse,
   MCPResourceMeta,
   MCPResourceResponse,