@pikku/core 0.12.79 → 0.12.82

package/src/removed-legacy-exports.test.ts

@@ -0,0 +1,62 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+const thisFile = fileURLToPath(import.meta.url)
+
+/**
+ * Names removed from the public surface, each with the entry point that must
+ * no longer carry it.
+ *
+ * They survived as throwing stubs only so the pinned bootstrap CLI could
+ * resolve the import; `@pikku/cli@0.12.96` emits none of them, so the stubs
+ * went too.
+ */
+const REMOVED = [
+  { name: 'addTagPermission', entry: './middleware/index.js' },
+  { name: 'addHTTPPermission', entry: './wirings/http/index.js' },
+  { name: 'ZodLike', entry: './index.js' },
+]
+
+const collectSourceFiles = (directory: string): string[] =>
+  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
+    }
+    return /\.ts$/.test(entry.name) ? [entryPath] : []
+  })
+
+describe('removed legacy exports stay removed', () => {
+  for (const { name, entry } of REMOVED) {
+    test(`${entry} no longer exports ${name}`, async () => {
+      const module = await import(entry)
+      assert.equal(
+        name in module,
+        false,
+        `${entry} exports ${name} again; it was removed in #972`
+      )
+    })
+  }
+
+  test('no source file mentions the removed permission wrappers', () => {
+    const offenders = collectSourceFiles(srcRoot)
+      .filter(
+        (file) =>
+          file !== thisFile &&
+          /\baddTagPermission\b|\baddHTTPPermission\b|\bZodLike\b/.test(
+            readFileSync(file, 'utf-8')
+          )
+      )
+      .map((file) => relative(srcRoot, file))
+
+    assert.deepEqual(
+      offenders,
+      [],
+      `removed names still referenced in:\n${offenders.join('\n')}`
+    )
+  })
+})

package/src/schema.test.ts

@@ -265,6 +265,84 @@ describe('Schema', () => {
       await validateSchema(logger, schemaService, null, {})
     })
 
+    test('strips undefined-valued properties before validating', async () => {
+      addSchema('undefinedProps', {
+        properties: { name: { type: 'string' }, count: { type: 'number' } },
+      })
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      let seen: any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async (_name: string, data: any) => {
+          seen = data
+        },
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, 'undefinedProps', {
+        name: 'ada',
+        count: undefined,
+      })
+      assert.deepStrictEqual(seen, { name: 'ada' })
+      assert.ok(!('count' in seen))
+    })
+
+    test('strips undefined nested in objects and arrays', async () => {
+      addSchema('nestedUndefined', { properties: {} })
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      let seen: any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async (_name: string, data: any) => {
+          seen = data
+        },
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, 'nestedUndefined', {
+        nested: { keep: 1, drop: undefined },
+        list: [{ keep: 2, drop: undefined }],
+      })
+      assert.deepStrictEqual(seen, {
+        nested: { keep: 1 },
+        list: [{ keep: 2 }],
+      })
+    })
+
+    test('leaves Date instances intact while stripping', async () => {
+      addSchema('withDate', { properties: {} })
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const when = new Date('2020-01-01T00:00:00.000Z')
+      let seen: any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async (_name: string, data: any) => {
+          seen = data
+        },
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, 'withDate', {
+        when,
+        drop: undefined,
+      })
+      assert.ok(seen.when instanceof Date)
+      assert.equal(seen.when.getTime(), when.getTime())
+      assert.ok(!('drop' in seen))
+    })
+
     test('should throw MissingSchemaError when schema not found', async () => {
       const logger = {
         info: () => {},

package/src/schema.ts

@@ -135,6 +135,41 @@ export const coerceTopLevelDataFromSchema = (
   }
 }
 
+/**
+ * Drops object properties whose value is literally `undefined`.
+ *
+ * JSON Schema has no way to describe such a property, and the validator refuses
+ * the whole instance rather than reporting it — `{ a: undefined }` throws
+ * "Instances of \"undefined\" type are not supported" instead of validating.
+ *
+ * That matters because whether a payload can contain one depends on how the
+ * call travelled. Over HTTP `JSON.stringify` drops these keys before the
+ * request is built, so they never arrive. Dispatched in-process — an inline
+ * workflow step calling an RPC — the object is handed over as-is, and
+ * `{ retries: data.maybeRetries }` with the field omitted by the caller is
+ * enough to kill the step. Normalising here makes the two paths agree, and an
+ * explicitly-undefined *required* field now reports as the missing property it
+ * is rather than as an internal error.
+ *
+ * Deliberately not a JSON round-trip: `coerceTopLevelDataFromSchema` puts real
+ * `Date` instances on the data first, and stringifying would flatten them back
+ * to strings the validator has never been given.
+ */
+const stripUndefinedValues = <T>(value: T): T => {
+  if (Array.isArray(value)) return value.map(stripUndefinedValues) as T
+  if (value === null || typeof value !== 'object') return value
+  // Only plain objects: a Date, Map or class instance is data, not a bag of
+  // properties to be rewritten.
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) return value
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .map(([key, entry]) => [key, stripUndefinedValues(entry)])
+  ) as T
+}
+
 export const validateSchema = async (
   logger: Logger,
   schemaService: SchemaService | undefined,
@@ -164,6 +199,6 @@ export const validateSchema = async (
       )
     }
     await schemaService.compileSchema(key, schema)
-    await schemaService.validateSchema(key, data ?? {})
+    await schemaService.validateSchema(key, stripUndefinedValues(data ?? {}))
   }
 }

package/src/services/ai-agent-runner-service.ts

@@ -52,7 +52,18 @@ export type AIAgentStepResult = {
   text: string
   object?: unknown
   toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
-  toolResults: { toolCallId: string; toolName: string; result: unknown }[]
+  toolResults: {
+    toolCallId: string
+    toolName: string
+    result: unknown
+    /**
+     * Set when the tool threw rather than returned. Carried as its own field
+     * because `result` is a rendered string by the time anything downstream
+     * reads it, and "did this tool fail" is not answerable by looking for an
+     * `Error:` prefix in text a tool could legitimately have returned.
+     */
+    error?: string
+  }[]
   usage: { inputTokens: number; outputTokens: number }
   finishReason: 'stop' | 'tool-calls' | 'length' | 'error' | 'unknown'
   reasoningContent?: string

package/src/services/ai-run-state-service.ts

@@ -2,19 +2,36 @@ import type {
   AgentRunState,
   PendingApproval,
 } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AIRunScore } from '../wirings/ai-scorer/ai-scorer.types.js'
 
 export type CreateRunInput = Omit<AgentRunState, 'runId'>
 
+export type SaveScoreInput = Omit<AIRunScore, 'createdAt'>
+
 export interface AIRunStateService {
   createRun(run: CreateRunInput): Promise<string>
   updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>
   getRun(runId: string): Promise<AgentRunState | null>
   getRunsByThread(threadId: string): Promise<AgentRunState[]>
+  /**
+   * Claims an approval: removes it from the run's pending list and records the
+   * decision, as one atomic step. Returns whether THIS caller made the claim —
+   * concurrent approvals of the same tool call produce exactly one `true`, and
+   * only that caller may run the tool.
+   */
   resolveApproval(
     toolCallId: string,
     status: 'approved' | 'denied'
-  ): Promise<void>
+  ): Promise<boolean>
   findRunByToolCallId(
     toolCallId: string
   ): Promise<{ run: AgentRunState; approval: PendingApproval } | null>
+  /**
+   * Record one scorer's grade of a finished run. A run accumulates one row per
+   * scorer, and a scorer may grade the same run more than once — a retried job
+   * appends rather than replaces, so a re-grade never silently overwrites the
+   * grade that was acted on.
+   */
+  saveScore(score: SaveScoreInput): Promise<void>
+  getScores(runId: string): Promise<AIRunScore[]>
 }

package/src/services/audit-service.ts

@@ -150,7 +150,7 @@ class DisabledInvocationAudit implements AuditLog {
     if (!this.warned) {
       this.warned = true
       // knowledge: decisions/security/a-dropped-audit-write-is-always-logged.md
-      const logger = (this.wire as any).logger ?? this.logger
+      const logger = this.wire.logger ?? this.logger
       logger?.warn?.(
         `audit.write() dropped for '${this.wire.functionId ?? 'unknown function'}' — the function has no audit config (set audit: true on it)`
       )
@@ -207,7 +207,7 @@ class InvocationAuditLog implements AuditLog {
         await this.service.audit(event)
       }
     } catch (error) {
-      const logger = (this.wire as any).logger ?? this.logger
+      const logger = this.wire.logger ?? this.logger
       logger?.warn?.('best-effort audit flush failed', error)
     }
   }

package/src/services/in-memory-ai-run-state-service.ts

@@ -1,14 +1,17 @@
 import type {
   AIRunStateService,
   CreateRunInput,
+  SaveScoreInput,
 } from './ai-run-state-service.js'
 import type {
   AgentRunState,
   PendingApproval,
 } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AIRunScore } from '../wirings/ai-scorer/ai-scorer.types.js'
 
 export class InMemoryAIRunStateService implements AIRunStateService {
   private runs = new Map<string, AgentRunState>()
+  private scores = new Map<string, AIRunScore[]>()
   private counter = 0
 
   async createRun(run: CreateRunInput): Promise<string> {
@@ -38,7 +41,7 @@ export class InMemoryAIRunStateService implements AIRunStateService {
   async resolveApproval(
     toolCallId: string,
     status: 'approved' | 'denied'
-  ): Promise<void> {
+  ): Promise<boolean> {
     for (const run of this.runs.values()) {
       if (run.pendingApprovals) {
         const approval = run.pendingApprovals.find(
@@ -49,10 +52,11 @@ export class InMemoryAIRunStateService implements AIRunStateService {
             (a) => a.toolCallId !== toolCallId
           )
           run.updatedAt = new Date()
-          return
+          return true
         }
       }
     }
+    return false
   }
 
   async findRunByToolCallId(
@@ -70,4 +74,14 @@ export class InMemoryAIRunStateService implements AIRunStateService {
     }
     return null
   }
+
+  async saveScore(score: SaveScoreInput): Promise<void> {
+    const existing = this.scores.get(score.runId) ?? []
+    existing.push({ ...score, createdAt: new Date() })
+    this.scores.set(score.runId, existing)
+  }
+
+  async getScores(runId: string): Promise<AIRunScore[]> {
+    return [...(this.scores.get(runId) ?? [])]
+  }
 }

package/src/services/in-memory-workflow-service.ts

@@ -142,6 +142,7 @@ export class InMemoryWorkflowService
     const step: StepState & { stepName: string } = {
       stepId,
       status: 'pending',
+      rpcName,
       attemptCount: 1,
       retries: stepOptions?.retries,
       retryDelay: stepOptions?.retryDelay,
@@ -273,6 +274,7 @@ export class InMemoryWorkflowService
     const newStep: StepState & { stepName: string } = {
       stepId: newStepId,
       status,
+      rpcName: failedStep.rpcName,
       attemptCount: failedStep.attemptCount + 1,
       retries: failedStep.retries,
       retryDelay: failedStep.retryDelay,

package/src/services/index.ts

@@ -1,15 +1,13 @@
 export { LogLevel } from './logger.js'
 export { ScopedSecretService } from './scoped-secret-service.js'
+export { ScopedCredentialService } from './scoped-credential-service.js'
 export {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
-  createFunctionSessionWireProps,
 } from './user-session-service.js'
 export { TypedSecretService } from './typed-secret-service.js'
 export {
   PikkuCredentialWireService,
-  createMiddlewareCredentialWireProps,
-  createWireServicesCredentialWireProps,
 } from './credential-wire-service.js'
 export { TypedVariablesService } from './typed-variables-service.js'
 export { LocalSecretService } from './local-secrets.js'
@@ -39,21 +37,14 @@ export type {
 export type {
   ScenarioPersona,
   ResolvedPersona,
-  ScenarioPersonaOf,
   ScenarioPersonas,
-  ScenarioInvokeOptions,
-  ScenarioRpcMap,
   ScenarioHttpResponse,
 } from './personas-service.js'
-// The persona runtime — `HttpPersona`, `createHttpPersonas`,
-// `readScenarioHttpResponse`, `postScenarioJson` — is exported from
-// `@pikku/core/persona`, not from here. Types are free; those are values, and
-// they reach the actor-flow and agent runners, which no production server runs.
+// knowledge: decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md
 export type { HttpPersonasConfig } from './http-personas.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,
-  EmailTemplateReference,
   SendEmailInput,
   SendEmailResult,
   SendHTMLEmailInput,
@@ -62,12 +53,10 @@ export type {
 } from './email-service.js'
 export {
   DEFAULT_WEBHOOK_RETRIES,
-  DEFAULT_WEBHOOK_SIGNATURE_HEADER,
   PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
   WebhookService,
   type SendWebhookInput,
   type SendWebhookResult,
-  type WebhookAttemptRecord,
   type WebhookAttemptResult,
   type WebhookDeliveryRecord,
   type WebhookDeliveryWithAttempts,
@@ -97,52 +86,30 @@ export type {
   AIAgentRunnerParams,
   AIAgentRunnerResult,
   AIAgentStepResult,
-  AIEmbedManyParams,
-  AIEmbedManyResult,
-  AIEmbedParams,
-  AIEmbedResult,
-  AIGenerateImageParams,
-  AIGenerateImagePrompt,
-  AIGenerateImageResult,
-  AIGenerateSpeechParams,
-  AIGenerateSpeechResult,
-  AIProviderOptions,
-  AIRerankParams,
-  AIRerankResult,
-  AITranscriptionParams,
-  AITranscriptionResult,
   AIAgentRunnerService,
 } from './ai-agent-runner-service.js'
 export type { AIEmbeddingService } from './ai-embedding-service.js'
 export type {
   CreateRunInput,
+  SaveScoreInput,
   AIRunStateService,
 } from './ai-run-state-service.js'
 export type {
-  CredentialStatus,
   CredentialMeta,
 } from './typed-secret-service.js'
 export type { CredentialService } from './credential-service.js'
 export { TypedCredentialService } from './typed-credential-service.js'
 export type {
-  CredentialStatusInfo,
   CredentialMetaInfo,
 } from './typed-credential-service.js'
-export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
+export type { VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
 export type { ScopeService, Role } from './scope-service.js'
-export {
-  assertRoleIsMutable,
-  assertRoleNameAvailable,
-  roleLockReason,
-} from './system-role-guard.js'
 export type { IsSystemRole } from './system-role-guard.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditConfig,
-  resolveAuditUserIdentityFromWire,
 } from './audit-service.js'
 export type {
   AuditConfig,
@@ -150,10 +117,7 @@ export type {
   AuditEvent,
   AuditEventBatch,
   AuditLog,
-  AuditLogWriteInput,
-  AuditOutcome,
   AuditService,
-  AuditSource,
   AuditUserIdentity,
   ResolvedAuditConfig,
 } from './audit-service.js'
@@ -177,17 +141,10 @@ export type {
   AgentMeta,
   EmailsMeta,
   EmailTemplateMeta,
-  EmailTemplateLocaleMeta,
-  EmailTemplateAssets,
 } from './meta-service.js'
 export type {
   CoverageService,
-  CoverageSnapshot,
-  LineHits,
   ScriptCoverage,
-  FunctionCoverage,
-  CoverageRange,
-  CoverageStatus,
   FunctionCoverageEntry,
   FunctionCoverageReport,
   CoverageFunctionMeta,

package/src/services/local-content-request-handler.test.ts

@@ -81,11 +81,17 @@ describe('createLocalContentRequestHandler', () => {
   test('refuses an upload whose key escapes the content directory', async () => {
     writeFileSync(join(tmpDir, '..', 'pikku-handler-secret.txt'), 'secret')
     try {
+      // Signed for the escaping path itself, so it clears the signature gate
+      // and the path-escape guard is what rejects it.
+      const signed = await content.signURL({
+        url: '/upload/bucket/..%2f..%2fpikku-handler-secret.txt',
+        dateLessThan: new Date(Date.now() + 60_000),
+      } as any)
       const response = await handler(
-        new Request(
-          'http://localhost/upload/bucket/..%2f..%2fpikku-handler-secret.txt',
-          { method: 'PUT', body: 'overwritten' }
-        )
+        new Request(`http://localhost${signed}`, {
+          method: 'PUT',
+          body: 'overwritten',
+        })
       )
       assert.equal(response?.status, 400)
       assert.equal(
@@ -104,6 +110,33 @@ describe('createLocalContentRequestHandler', () => {
     assert.equal(response?.status, 400)
   })
 
+  test('refuses an unsigned PUT to the upload prefix', async () => {
+    const put = await handler(
+      new Request('http://localhost/upload/bucket/evil.bin', {
+        method: 'PUT',
+        body: 'attacker-controlled',
+      })
+    )
+    assert.equal(put?.status, 403, 'an upload URL must be signed like a read')
+  })
+
+  test('refuses a PUT whose signature was minted for a different key', async () => {
+    const { uploadUrl } = await content.getUploadURL({
+      bucket: 'bucket',
+      fileKey: 'legit/one.bin',
+      contentType: 'application/octet-stream',
+    } as any)
+    const query = uploadUrl.slice(uploadUrl.indexOf('?'))
+    // Same signature, a different target path.
+    const put = await handler(
+      new Request(`http://localhost/upload/bucket/other.bin${query}`, {
+        method: 'PUT',
+        body: 'payload',
+      })
+    )
+    assert.equal(put?.status, 403)
+  })
+
   test('round-trips an upload and a signed read', async () => {
     const { uploadUrl } = await content.getUploadURL({
       bucket: 'bucket',
@@ -188,8 +221,13 @@ describe('createLocalContentRequestHandler', () => {
   })
 
   test('rejects a body over the size limit without writing it', async () => {
+    const { uploadUrl } = await content.getUploadURL({
+      bucket: 'bucket',
+      fileKey: 'big.bin',
+      contentType: 'application/octet-stream',
+    } as any)
     const response = await handler(
-      new Request('http://localhost/upload/bucket/big.bin', {
+      new Request(`http://localhost${uploadUrl}`, {
         method: 'PUT',
         body: Buffer.alloc(1024 * 1024 + 1),
       })