@pikku/core 0.12.64 → 0.12.67

package/src/wirings/ai-agent/ai-agent-stream.test.ts

@@ -1105,6 +1105,109 @@ describe('streamAIAgent', () => {
       },
     ])
   })
+  /**
+   * `send` is synchronous, so the persisting channel cannot await its flush and
+   * calls it fire-and-forget. Any rejection from storage — a dropped connection,
+   * or a model reusing a toolCallId, which is a primary key in AI storage — then
+   * surfaces as an unhandled rejection and takes the whole server process down
+   * with it. A failed persist must fail (or degrade) the run, not the process.
+   */
+  test('a storage failure while streaming does not become an unhandled rejection', async () => {
+    addTestAgent('storage-failure-agent')
+
+    const events: AIStreamEvent[] = []
+    const loggedErrors: unknown[] = []
+
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: (...args: unknown[]) => {
+          loggedErrors.push(args)
+        },
+        debug: () => {},
+      },
+      aiAgentRunner: {
+        // Emits through the channel the way the real runner does: the persisting
+        // channel flushes fire-and-forget on `usage`, which is the path that
+        // cannot await and so cannot catch.
+        stream: async (
+          _params: unknown,
+          channel: AIStreamChannel
+        ): Promise<AIAgentStepResult> => {
+          channel.send({
+            type: 'text-delta',
+            text: 'persisted text',
+          } as AIStreamEvent)
+          channel.send({
+            type: 'usage',
+            tokens: { input: 1, output: 1 },
+            model: 'test/test-model',
+          } as AIStreamEvent)
+          return makeStepResult({ text: 'persisted text' })
+        },
+      },
+      aiRunState: {
+        createRun: async () => 'run-storage-failure',
+        updateRun: async () => {},
+      },
+      aiStorage: {
+        getThread: async () => undefined,
+        createThread: async () => {},
+        getMessages: async () => [],
+        // Fails only on the assistant/tool write the persisting channel makes,
+        // the way a repeated toolCallId collides on its primary key — the
+        // initial user-message save is awaited and must still succeed.
+        saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+          if (messages.some((m) => m.role !== 'user')) {
+            throw new Error('UNIQUE constraint failed: ai_tool_call.id')
+          }
+        },
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    const unhandled: unknown[] = []
+    const onUnhandled = (reason: unknown) => unhandled.push(reason)
+    process.on('unhandledRejection', onUnhandled)
+
+    try {
+      await streamAIAgent(
+        'storage-failure-agent',
+        {
+          message: 'hello',
+          threadId: 'thread-storage-failure',
+          resourceId: 'resource-storage-failure',
+        },
+        {
+          channelId: 'channel-storage-failure',
+          openingData: undefined,
+          state: 'open',
+          send: (event: AIStreamEvent) => {
+            events.push(event)
+          },
+          close: () => {},
+        },
+        {}
+      )
+      // unhandledRejection is emitted on a later macrotask, so the floating
+      // flush promise needs a real timer to settle before asserting.
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+
+    assert.deepEqual(
+      unhandled,
+      [],
+      'a storage failure must not escape as an unhandled rejection'
+    )
+    assert.ok(
+      loggedErrors.length > 0,
+      'the storage failure should be reported rather than swallowed'
+    )
+  })
 })
 
 describe('ai-agent-stream helpers', () => {

package/src/wirings/ai-agent/ai-agent-stream.ts

@@ -37,6 +37,7 @@ import {
   resolveOwnerResourceId,
   agentSessionScope,
   assertResourceOwner,
+  assertAgentAuthorized,
   ToolApprovalRequired,
   ToolCredentialRequired,
   APPROVAL_REQUIRED,
@@ -57,7 +58,8 @@ type PersistingChannel = AIStreamChannel & {
 function createPersistingChannel(
   parent: AIStreamChannel,
   storage: AIStorageService | undefined,
-  threadId: string
+  threadId: string,
+  logger?: { error: (...args: any[]) => void }
 ): PersistingChannel {
   let fullText = ''
   let stepText = ''
@@ -110,6 +112,23 @@ function createPersistingChannel(
     }
   }
 
+  /**
+   * `send` is synchronous and so cannot await the flush. A rejection would have
+   * nothing to propagate to and would take the process down as an unhandled
+   * rejection — a model reusing a toolCallId, which is a primary key in AI
+   * storage, is enough to trigger it. Persistence from inside `send` is
+   * therefore best-effort: the run carries on, and the awaited `flush()` on the
+   * suspend paths still surfaces failures to its caller.
+   */
+  const flushDetached = () => {
+    void flushStep().catch((error) => {
+      logger?.error('Failed to persist agent messages', {
+        threadId,
+        error,
+      })
+    })
+  }
+
   const channel: PersistingChannel = {
     channelId: parent.channelId,
     openingData: parent.openingData,
@@ -156,10 +175,10 @@ function createPersistingChannel(
             totalUsage.inputTokens += event.tokens.input
             totalUsage.outputTokens += event.tokens.output
             if (event.model) totalUsage.model = event.model
-            flushStep()
+            flushDetached()
             break
           case 'done':
-            flushStep()
+            flushDetached()
             break
         }
       }
@@ -730,7 +749,12 @@ export async function streamAIAgent(
     }
   )
 
-  const persistingChannel = createPersistingChannel(channel, storage, threadId)
+  const persistingChannel = createPersistingChannel(
+    channel,
+    storage,
+    threadId,
+    singletonServices.logger
+  )
 
   const wrappedChannel =
     allChannelMiddleware.length > 0
@@ -898,12 +922,19 @@ export async function resumeAIAgent(
     )
   }
 
+  const { agent, packageName, resolvedName } = resolveAgent(run.agentName)
+
+  // Gate before resolving the approval: recording it is a persisted side
+  // effect, so an unauthorized caller must not reach it. Run ownership alone is
+  // not enough — a grant revoked while the run was suspended must stop the
+  // caller from approving its pending tool calls.
+  await assertAgentAuthorized(agent, params, packageName)
+
   await aiRunState.resolveApproval(
     input.toolCallId,
     input.approved ? 'approved' : 'denied'
   )
 
-  const { agent, packageName, resolvedName } = resolveAgent(run.agentName)
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
   const agentRunner = singletonServices.aiAgentRunner
@@ -1229,7 +1260,8 @@ async function continueAfterToolResult(
   const persistingChannel = createPersistingChannel(
     channel,
     storage,
-    run.threadId
+    run.threadId,
+    singletonServices.logger
   )
 
   const wrappedChannel =

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

@@ -226,6 +226,7 @@ export type AIAgentMemoryConfig = {
 export type CoreAIAgent<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
+  Scope extends string = string,
 > = {
   name: string
   description: string
@@ -259,6 +260,23 @@ export type CoreAIAgent<
   middleware?: PikkuMiddleware[]
   channelMiddleware?: CorePikkuChannelMiddleware<any, any>[]
   aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[]
+  /**
+   * Whether a session is required to run this agent. Defaults to `false`, since
+   * agents are commonly invoked from an already-authenticated `pikkuFunc` or
+   * from genuinely sessionless contexts (crons, queue workers). Set `true` to
+   * require a session at the agent itself. `scopes` and `permissions` are
+   * enforced either way.
+   */
+  auth?: boolean
+  /**
+   * Scopes the session must hold to run this agent. All of them are required
+   * (AND), and they are checked before `permissions` — unlike permissions,
+   * which OR together, a scope can only narrow access.
+   *
+   * Narrowed to the generated `ScopeId` union in a project's own
+   * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+   */
+  scopes?: Scope[]
   permissions?: CorePermissionGroup<PikkuPermission>
 }
 
@@ -421,6 +439,17 @@ export interface AgentRunService {
   listThreads(options?: {
     agentName?: string
     resourceId?: string
+    /**
+     * Restrict results to threads owned by one of these session principals. A
+     * thread matches when its `resourceId` is the principal itself or one of its
+     * `principal:` sub-partitions, mirroring the composition
+     * `resolveOwnerResourceId` writes.
+     *
+     * Unlike `resourceId`, which is an optional exact-match filter, this is an
+     * authorization constraint: an empty array matches nothing. Callers exposing
+     * threads over the wire must derive it from the session, never from input.
+     */
+    owners?: string[]
     limit?: number
     offset?: number
   }): Promise<AIThread[]>

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

@@ -14,6 +14,10 @@ export {
   type StreamAIAgentOptions,
   ToolApprovalRequired,
   ToolCredentialRequired,
+  canAccessThread,
+  isOwnedByPrincipal,
+  sessionPrincipals,
+  threadOwnerConstraint,
 } from './ai-agent-prepare.js'
 export {
   addAIAgent,

package/src/wirings/ai-agent/voice-input.test.ts

@@ -0,0 +1,90 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { voiceInput } from './voice-input.js'
+import type { AIContentPart, AIMessage } from './ai-agent.types.js'
+
+/**
+ * A runner whose `transcribe` reads instance state through `this`, mirroring the
+ * real `VercelAIAgentRunner` where `transcribe` calls `this.getModel(...)`. If
+ * the middleware grabs the method as a bare reference the receiver is lost and
+ * `this` is undefined — which is exactly the regression this guards.
+ */
+class ThisDependentRunner {
+  private readonly transcript = 'the transcribed spoken words'
+
+  async transcribe() {
+    return {
+      text: this.transcript,
+      segments: [],
+      language: 'en',
+      durationInSeconds: 1,
+      warnings: [],
+    }
+  }
+}
+
+const audioMessage = (): AIMessage => ({
+  id: 'm1',
+  role: 'user',
+  content: [
+    { type: 'file', mediaType: 'audio/wav', data: 'AAAA' },
+  ] as AIContentPart[],
+  createdAt: new Date(0),
+})
+
+describe('voiceInput', () => {
+  test('transcribes an audio part by calling the runner with its receiver intact', async () => {
+    const mw = voiceInput({ model: 'mock/whisper' })
+    const services = { aiAgentRunner: new ThisDependentRunner() }
+
+    const result = await mw.modifyInput!(services as any, {
+      messages: [audioMessage()],
+      instructions: 'sys',
+    })
+
+    const last = result.messages[result.messages.length - 1]!
+    const parts = last.content as AIContentPart[]
+    assert.equal(parts.length, 1)
+    assert.equal(parts[0]!.type, 'text')
+    assert.equal(
+      (parts[0] as { text: string }).text,
+      'the transcribed spoken words'
+    )
+    assert.ok(!parts.some((p) => p.type === 'file'))
+  })
+
+  test('leaves the message untouched when there is no audio part', async () => {
+    const mw = voiceInput({ model: 'mock/whisper' })
+    const services = { aiAgentRunner: new ThisDependentRunner() }
+    const messages: AIMessage[] = [
+      {
+        id: 'm1',
+        role: 'user',
+        content: 'just text',
+        createdAt: new Date(0),
+      },
+    ]
+
+    const result = await mw.modifyInput!(services as any, {
+      messages,
+      instructions: 'sys',
+    })
+
+    assert.equal(result.messages[0]!.content, 'just text')
+  })
+
+  test('throws when an audio part is present but no model is configured', async () => {
+    const mw = voiceInput({})
+    const services = { aiAgentRunner: new ThisDependentRunner() }
+
+    await assert.rejects(
+      () =>
+        mw.modifyInput!(services as any, {
+          messages: [audioMessage()],
+          instructions: 'sys',
+        }),
+      /voiceInput requires a transcription model/
+    )
+  })
+})

package/src/wirings/ai-agent/voice-input.ts

@@ -18,11 +18,7 @@ async function fetchAsUint8Array(
   url: string,
   allowedAudioHosts?: string[]
 ): Promise<Uint8Array> {
-  const response = await safeFetch(
-    url,
-    {},
-    { allowedHosts: allowedAudioHosts }
-  )
+  const response = await safeFetch(url, {}, { allowedHosts: allowedAudioHosts })
   const contentLength = response.headers.get('content-length')
   if (contentLength && parseInt(contentLength, 10) > MAX_AUDIO_SIZE) {
     throw new Error('Audio file exceeds maximum size')
@@ -41,10 +37,12 @@ export const voiceInput = (config?: {
 }) =>
   pikkuAIMiddleware({
     modifyInput: async (services, { messages, instructions }) => {
-      const transcribeAudio = (services as {
-        aiAgentRunner?: AIAgentRunnerService
-      }).aiAgentRunner?.transcribe
-      if (!transcribeAudio) return { messages, instructions }
+      const aiAgentRunner = (
+        services as {
+          aiAgentRunner?: AIAgentRunnerService
+        }
+      ).aiAgentRunner
+      if (!aiAgentRunner?.transcribe) return { messages, instructions }
 
       const last = messages[messages.length - 1]
       if (!last || last.role !== 'user' || typeof last.content === 'string') {
@@ -76,7 +74,7 @@ export const voiceInput = (config?: {
         const audioData = p.data
           ? base64ToUint8Array(p.data)
           : await fetchAsUint8Array(p.url!, config.allowedAudioHosts)
-        const result = await transcribeAudio({
+        const result = await aiAgentRunner.transcribe({
           model: config.model,
           audio: audioData,
           ...(config.language

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

@@ -490,6 +490,10 @@ export async function executeCLI({
       return
     }
 
+    // Non-fatal diagnostics (unknown options are still accepted) go to stderr
+    // so they never pollute a command's machine-readable stdout.
+    parsed.warnings.forEach((warning) => console.error(`Warning: ${warning}`))
+
     if (parsed.errors.length > 0) {
       // Check if any error is about an unknown command
       const hasUnknownCommand = parsed.errors.some(

package/src/wirings/cli/command-parser.test.ts

@@ -270,6 +270,7 @@ describe('Command Parser', () => {
       // Unknown options are allowed (for forward compatibility)
       // They just won't have defaults or validation
       assert.strictEqual(result.options.unknown, true)
+      assert.strictEqual(result.errors.length, 0)
     })
 
     test('should report error for unknown short flag', () => {
@@ -525,4 +526,133 @@ describe('Command Parser', () => {
       )
     })
   })
+
+  describe('unknown long options', () => {
+    const listMeta: CLIMeta = {
+      programs: {
+        'test-cli': {
+          program: 'test-cli',
+          options: {},
+          commands: {
+            list: {
+              pikkuFuncId: 'listFunc',
+              positionals: [],
+              options: {
+                section: { description: 'Section to list', default: 'all' },
+                autoApply: {
+                  description: 'Apply automatically',
+                  default: false,
+                },
+              },
+            },
+          },
+        },
+      },
+      renderers: {},
+    }
+
+    test('warns (but does not error) on an unknown --opt value option', () => {
+      const result = parseCLIArguments(
+        ['list', '--sektion', 'functions'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.strictEqual(result.errors.length, 0, 'should stay non-fatal')
+      assert.strictEqual(result.warnings.length, 1)
+      assert.ok(
+        result.warnings[0].startsWith('Unknown option: --sektion (ignored)'),
+        `unexpected warning: ${result.warnings[0]}`
+      )
+      // Forward compatibility: the value is still parsed through
+      assert.strictEqual(result.options.sektion, 'functions')
+      // ...and the real option keeps its default
+      assert.strictEqual(result.options.section, 'all')
+    })
+
+    test('warns on an unknown --opt=value option', () => {
+      const result = parseCLIArguments(
+        ['list', '--sektion=functions'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.strictEqual(result.errors.length, 0)
+      assert.strictEqual(result.warnings.length, 1)
+      assert.ok(
+        result.warnings[0].startsWith('Unknown option: --sektion (ignored)'),
+        `unexpected warning: ${result.warnings[0]}`
+      )
+      assert.strictEqual(result.options.sektion, 'functions')
+    })
+
+    test('suggests a near-miss option name', () => {
+      const result = parseCLIArguments(
+        ['list', '--sektion'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.ok(
+        result.warnings[0].includes('Did you mean --section?'),
+        `expected a suggestion, got: ${result.warnings[0]}`
+      )
+    })
+
+    test('suggests the kebab-case rendering of a camelCase option', () => {
+      const result = parseCLIArguments(
+        ['list', '--auto-aply'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.ok(
+        result.warnings[0].includes('Did you mean --auto-apply?'),
+        `expected a suggestion, got: ${result.warnings[0]}`
+      )
+    })
+
+    test('omits the suggestion when nothing is close', () => {
+      const result = parseCLIArguments(
+        ['list', '--completely-different'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.strictEqual(
+        result.warnings[0],
+        'Unknown option: --completely-different (ignored)'
+      )
+    })
+
+    test('does not warn for a known option (either casing)', () => {
+      const kebab = parseCLIArguments(
+        ['list', '--section', 'functions', '--auto-apply'],
+        'test-cli',
+        listMeta
+      )
+      assert.deepStrictEqual(kebab.warnings, [])
+      assert.strictEqual(kebab.options.section, 'functions')
+
+      const camel = parseCLIArguments(
+        ['list', '--autoApply'],
+        'test-cli',
+        listMeta
+      )
+      assert.deepStrictEqual(camel.warnings, [])
+    })
+
+    test('does not warn for --help', () => {
+      const result = parseCLIArguments(['list', '--help'], 'test-cli', listMeta)
+
+      assert.deepStrictEqual(result.warnings, [])
+    })
+
+    test('unknown short flags still error, not warn', () => {
+      const result = parseCLIArguments(['list', '-x'], 'test-cli', listMeta)
+
+      assert.ok(result.errors.some((e) => e.includes('Unknown option: -x')))
+      assert.deepStrictEqual(result.warnings, [])
+    })
+  })
 })

package/src/wirings/cli/command-parser.ts

@@ -18,6 +18,71 @@ function toKebabCase(str: string): string {
   return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
 }
 
+/** Options the runner handles itself — never reported as unknown. */
+const RESERVED_OPTIONS = new Set(['help'])
+
+/** Levenshtein distance, capped-free and dependency-free. Used only to suggest
+ *  a near-miss option name, so the naive O(n*m) implementation is fine. */
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0
+  if (a.length === 0) return b.length
+  if (b.length === 0) return a.length
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      row[j] = Math.min(row[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost)
+    }
+    prev = row
+  }
+  return prev[b.length]
+}
+
+/** Finds the closest declared option (distance <= 2) to what the user typed.
+ *  Compares against the kebab-case rendering, since that is what is typed. */
+function suggestOption(
+  typed: string,
+  availableOptions: Record<string, CLIOption>
+): string | null {
+  let best: string | null = null
+  let bestDistance = 3
+
+  for (const name of Object.keys(availableOptions)) {
+    const kebab = toKebabCase(name)
+    const distance = Math.min(
+      levenshtein(typed, kebab),
+      levenshtein(typed, name)
+    )
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = kebab
+    }
+  }
+
+  return best
+}
+
+/** Records a warning that an unknown long option was accepted but ignored.
+ *  Unknown options stay non-fatal for forward compatibility (a newer command
+ *  version may understand them) — they are just no longer silent. */
+function warnUnknownOption(
+  typed: string,
+  availableOptions: Record<string, CLIOption>,
+  result: ParsedCommand
+) {
+  if (RESERVED_OPTIONS.has(toCamelCase(typed))) {
+    return
+  }
+
+  const suggestion = suggestOption(typed, availableOptions)
+  result.warnings.push(
+    `Unknown option: --${typed} (ignored)` +
+      (suggestion ? ` Did you mean --${suggestion}?` : '')
+  )
+}
+
 /**
  * Result of parsing CLI arguments
  */
@@ -27,6 +92,8 @@ export interface ParsedCommand {
   positionals: Record<string, any>
   options: Record<string, any>
   errors: string[]
+  /** Non-fatal diagnostics (e.g. unknown options that were accepted+ignored) */
+  warnings: string[]
 }
 
 /**
@@ -43,6 +110,7 @@ export function parseCLIArguments(
     positionals: {},
     options: {},
     errors: [],
+    warnings: [],
   }
 
   const meta = allMeta.programs[programName]
@@ -148,7 +216,12 @@ export function parseCLIArguments(
         const key = toCamelCase(arg.slice(2, equalIndex))
         const optionDef = availableOptions[key]
 
-        // Unknown options are allowed for forward compatibility
+        // Unknown options are allowed for forward compatibility, but warned
+        // about so they are not silently dropped by the input schema.
+        if (!optionDef) {
+          warnUnknownOption(arg.slice(2, equalIndex), availableOptions, result)
+        }
+
         const value = arg.slice(equalIndex + 1)
         optionArgs[key] = parseOptionValue(value, optionDef)
       } else {
@@ -156,7 +229,12 @@ export function parseCLIArguments(
         const key = toCamelCase(arg.slice(2))
         const optionDef = availableOptions[key]
 
-        // Unknown options are allowed for forward compatibility
+        // Unknown options are allowed for forward compatibility, but warned
+        // about so they are not silently dropped by the input schema.
+        if (!optionDef) {
+          warnUnknownOption(arg.slice(2), availableOptions, result)
+        }
+
         if (optionDef && optionDef.array) {
           // Array option - collect all following non-flag values
           currentIndex++

package/src/wirings/credential/credential.types.ts

@@ -6,6 +6,13 @@ export type CoreCredential<T = unknown> = {
   description?: string
   type: 'singleton' | 'wire'
   schema: T
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   oauth2?: OAuth2CredentialConfig & {
     appCredentialSecretId: string
   }
@@ -17,6 +24,13 @@ export type CredentialDefinitionMeta = {
   description?: string
   type: 'singleton' | 'wire'
   schema?: Record<string, unknown> | string
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   oauth2?: OAuth2CredentialConfig & {
     appCredentialSecretId: string
   }