@pikku/core 0.12.78 → 0.12.80

package/src/public-surface.test.ts

@@ -0,0 +1,105 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+const packageRoot = join(srcRoot, '..')
+
+const packageJson = JSON.parse(
+  readFileSync(join(packageRoot, 'package.json'), 'utf-8')
+)
+const expected: Record<string, string[]> = JSON.parse(
+  readFileSync(join(srcRoot, 'public-surface.json'), 'utf-8')
+)
+
+const subpaths = packageJson.exports as Record<string, string>
+
+/**
+ * Every runtime export reachable through an entry point, keyed by subpath.
+ *
+ * Types are absent: they are erased before this can see them, so a type-only
+ * addition is not pinned here.
+ */
+const actualSurface = async () => {
+  const surface: Record<string, string[]> = {}
+  for (const [subpath, dist] of Object.entries(subpaths)) {
+    const src = resolve(packageRoot, dist.replace('./dist/', './src/'))
+    const module = await import(pathToFileURL(src).href)
+    surface[subpath] = Object.keys(module).sort()
+  }
+  return surface
+}
+
+const REGENERATE =
+  'Regenerate with the snippet in public-surface.json.README, and make sure ' +
+  'every added name is one @pikku/core means to publish.'
+
+describe('the published surface is the surface we meant to publish', () => {
+  test('every export subpath resolves to a source file', () => {
+    const missing = Object.entries(subpaths).filter(([, dist]) => {
+      try {
+        readFileSync(
+          resolve(packageRoot, dist.replace('./dist/', './src/')).replace(
+            /\.js$/,
+            '.ts'
+          )
+        )
+        return false
+      } catch {
+        return true
+      }
+    })
+
+    assert.deepEqual(
+      missing.map(([subpath]) => subpath),
+      [],
+      'package.json exports point at files that do not exist in src'
+    )
+  })
+
+  test('no entry point gained or lost a runtime export', async () => {
+    const actual = await actualSurface()
+
+    assert.deepEqual(
+      Object.keys(actual).sort(),
+      Object.keys(expected).sort(),
+      `the set of export subpaths changed. ${REGENERATE}`
+    )
+
+    for (const subpath of Object.keys(expected)) {
+      const added = actual[subpath]!.filter(
+        (name) => !expected[subpath]!.includes(name)
+      )
+      const removed = expected[subpath]!.filter(
+        (name) => !actual[subpath]!.includes(name)
+      )
+
+      assert.deepEqual(
+        { added, removed },
+        { added: [], removed: [] },
+        `'${subpath}' changed its public exports.\n` +
+          (added.length ? `  added:   ${added.join(', ')}\n` : '') +
+          (removed.length ? `  removed: ${removed.join(', ')}\n` : '') +
+          `${REGENERATE}`
+      )
+    }
+  })
+
+  test('the wildcard re-exports have not widened past their barrels', async () => {
+    // `errors/index.ts` and `dev/hot-reload.ts` re-export with `export *`, so a
+    // new export in the wrapped module is published without anyone editing an
+    // entry point. This pins the two that are reachable publicly.
+    const actual = await actualSurface()
+
+    assert.equal(
+      actual['./errors']!.every(
+        (name) => name.endsWith('Error') || name.startsWith('addError')
+      ),
+      true,
+      `'@pikku/core/errors' exports something that is not an error or an error ` +
+        `registrar: ${actual['./errors']!.filter((n) => !n.endsWith('Error') && !n.startsWith('addError')).join(', ')}`
+    )
+  })
+})

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-run-state-service.ts

@@ -10,10 +10,16 @@ export interface AIRunStateService {
   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>

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

@@ -38,7 +38,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 +49,11 @@ export class InMemoryAIRunStateService implements AIRunStateService {
             (a) => a.toolCallId !== toolCallId
           )
           run.updatedAt = new Date()
-          return
+          return true
         }
       }
     }
+    return false
   }
 
   async findRunByToolCallId(

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,
@@ -301,6 +303,29 @@ export class InMemoryWorkflowService
     return newStep
   }
 
+  /**
+   * Safe to opt in despite the pass-through `withStepLock`: this service wires
+   * no queues and runs every step inline in one process, so the relay's
+   * redundant dispatch has no second holder to race with. See
+   * knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+   */
+  protected async findUndispatchedSteps(
+    before: Date,
+    limit: number
+  ): Promise<Array<{ runId: string; stepId: string }>> {
+    const undispatched: Array<{ runId: string; stepId: string }> = []
+    for (const [runId, run] of this.runs) {
+      if (run.status !== 'running') continue
+      for (const step of this.stepHistory.get(runId) ?? []) {
+        if (step.status !== 'pending') continue
+        if (step.updatedAt >= before) continue
+        undispatched.push({ runId, stepId: step.stepId })
+        if (undispatched.length >= limit) return undispatched
+      }
+    }
+    return undispatched
+  }
+
   protected async findStalledRunIds(
     before: Date,
     limit: number

package/src/services/index.ts

@@ -45,10 +45,7 @@ export type {
   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 {

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),
       })