@pikku/core 0.12.79 → 0.12.80

package/src/services/local-content.ts

@@ -48,6 +48,9 @@ export const signedContentPath = (urlOrPath: string): string => {
   }
 }
 
+/** How long a presigned upload URL stays valid. Short, like an S3 PUT URL. */
+const UPLOAD_URL_TTL_MS = 15 * 60 * 1000
+
 export class LocalContent implements ContentService {
   constructor(
     private config: LocalContentConfig,
@@ -137,13 +140,24 @@ export class LocalContent implements ContentService {
     })
   }
 
+  /**
+   * Presigned upload, mirroring the read side: the URL carries a short-lived,
+   * path-bound signature that {@link createLocalContentRequestHandler} verifies
+   * before writing. An unsigned upload URL cannot be verified, and the handler
+   * now refuses one — so this must sign, or every upload 403s.
+   */
   public async getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult> {
     void args.visibility
     const fullKey = this.joinKey(args.bucket, args.fileKey)
     this.logger.debug(`Going to upload with key: ${fullKey}`)
+    const uploadUrl = await this.signURL({
+      url: `${this.config.uploadUrlPrefix}/${fullKey}`,
+      dateLessThan: new Date(Date.now() + UPLOAD_URL_TTL_MS),
+    })
     return {
-      uploadUrl: `${this.config.uploadUrlPrefix}/${fullKey}`,
+      uploadUrl,
       assetKey: fullKey,
+      uploadMethod: 'PUT',
     }
   }
 

package/src/services/local-email-service.ts

@@ -1,4 +1,8 @@
-import type { EmailService, SendEmailInput, SendEmailResult } from './email-service.js'
+import type {
+  EmailService,
+  SendEmailInput,
+  SendEmailResult,
+} from './email-service.js'
 
 export class LocalEmailService implements EmailService {
   async send(input: SendEmailInput): Promise<SendEmailResult> {

package/src/services/system-role-guard.test.ts

@@ -11,7 +11,10 @@ import {
   SystemRoleShadowedError,
 } from '../errors/errors.js'
 
-const system = (...names: string[]) => (name: string) => names.includes(name)
+const system =
+  (...names: string[]) =>
+  (name: string) =>
+    names.includes(name)
 
 describe('mutating a role', () => {
   test('a declared role refuses to be deleted or re-scoped', async () => {

package/src/services/workflow-service.ts

@@ -1,4 +1,4 @@
-import type { SerializedError } from '../types/core.types.js'
+import type { CoreUserSession, SerializedError } from '../types/core.types.js'
 import type {
   WorkflowRun,
   WorkflowPlannedStep,
@@ -47,8 +47,15 @@ export interface WorkflowService {
   /**
    * The payload is stored as given and validated on replay inside the workflow
    * body, so an invalid one re-closes the gate rather than failing the run.
+   *
+   * The session must belong to the run's owner — see `assertWorkflowRunOwner`.
    */
-  approveStep(runId: string, reason: string, decision: unknown): Promise<void>
+  approveStep(
+    runId: string,
+    reason: string,
+    decision: unknown,
+    session?: CoreUserSession
+  ): Promise<void>
   startWorkflow<I>(
     name: string,
     input: I,

package/src/side-effects-are-declared.test.ts

@@ -0,0 +1,84 @@
+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 packageRoot = join(srcRoot, '..')
+
+/**
+ * A statement that runs when the module is imported, rather than when
+ * something in it is called. Today every one is an `addError(...)` registering
+ * an error class in the runtime registry.
+ */
+const TOP_LEVEL_CALL = /^[a-zA-Z_$][\w.$]*\(/
+
+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 entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')
+      ? [entryPath]
+      : []
+  })
+
+/** Source modules that do something merely by being imported. */
+const modulesWithSideEffects = (): string[] =>
+  collectSourceFiles(srcRoot)
+    .filter((file) =>
+      readFileSync(file, 'utf-8')
+        .split('\n')
+        .some((line) => TOP_LEVEL_CALL.test(line))
+    )
+    .map((file) => `./dist/${relative(srcRoot, file).replace(/\.ts$/, '.js')}`)
+    .sort()
+
+const declared = (): string[] => {
+  const pkg = JSON.parse(
+    readFileSync(join(packageRoot, 'package.json'), 'utf-8')
+  )
+  return [...(pkg.sideEffects ?? [])].sort()
+}
+
+/**
+ * `sideEffects` tells a bundler which modules it may not drop. Claiming
+ * `false` outright would be untrue — the error registry is built by
+ * `addError(...)` calls that run on import, and a bundler that dropped
+ * `errors/errors.js` would leave `getErrorResponse` unable to find any of
+ * them. Naming the modules exactly lets everything else be tree-shaken.
+ *
+ * knowledge: decisions/internals/side-effects-are-an-allowlist-not-a-boolean.md
+ */
+describe('every module with import-time side effects is declared', () => {
+  test('the allowlist matches the modules that actually have them', () => {
+    const actual = modulesWithSideEffects()
+    const listed = declared()
+
+    assert.deepEqual(
+      { missing: actual.filter((m) => !listed.includes(m)) },
+      { missing: [] },
+      'a module runs code on import but is not in package.json sideEffects. ' +
+        'A bundler may drop it, and whatever it registered will be absent at ' +
+        'runtime.'
+    )
+
+    assert.deepEqual(
+      { stale: listed.filter((m) => !actual.includes(m)) },
+      { stale: [] },
+      'package.json sideEffects names a module that no longer has any — ' +
+        'remove it so bundlers can tree-shake it.'
+    )
+  })
+
+  test('the detector finds a known side effect', () => {
+    // Guards the test above: a detector matching nothing would pass whatever
+    // package.json claimed.
+    assert.ok(
+      modulesWithSideEffects().includes('./dist/errors/errors.js'),
+      'errors/errors.js registers every error class at import and must match'
+    )
+  })
+})

package/src/source-files-stay-composable.test.ts

@@ -0,0 +1,41 @@
+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))
+
+/**
+ * The ceiling a single module may reach before it has to be composed out of
+ * smaller ones.
+ */
+const MAX_LINES = 2000
+
+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 entry.name.endsWith('.ts') ? [entryPath] : []
+  })
+
+describe('source files stay composable', () => {
+  test(`no module in @pikku/core exceeds ${MAX_LINES} lines`, () => {
+    const offenders = collectSourceFiles(srcRoot)
+      .map((file) => ({
+        file: relative(srcRoot, file),
+        lines: readFileSync(file, 'utf-8').split('\n').length,
+      }))
+      .filter(({ lines }) => lines > MAX_LINES)
+      .sort((a, b) => b.lines - a.lines)
+
+    assert.deepEqual(
+      offenders,
+      [],
+      `modules over ${MAX_LINES} lines:\n` +
+        offenders.map(({ file, lines }) => `  ${lines}  ${file}`).join('\n')
+    )
+  })
+})

package/src/testing/service-tests/agent-run-service-tests.ts

@@ -0,0 +1,98 @@
+import { describe, test, before } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { AgentRunService } from '../../wirings/ai-agent/ai-agent.types.js'
+import type { ServiceTestConfig } from '../service-tests.js'
+
+/** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
+export const defineAgentRunServiceTests = (
+  name: string,
+  agentRunService: NonNullable<
+    ServiceTestConfig['services']['agentRunService']
+  >,
+  /**
+   * Thread-ownership is a property of the two services together — the run
+   * service lists what the storage service owns — so that half of the suite
+   * only runs when a backend supplies both. Passed explicitly rather than
+   * closed over, so the dependency is visible in the signature.
+   */
+  aiStorageService?: ServiceTestConfig['services']['aiStorageService']
+): void => {
+  const factory = agentRunService
+  describe(`AgentRunService [${name}]`, () => {
+    let agentService: AgentRunService
+
+    before(async () => {
+      agentService = await factory()
+    })
+
+    test('listThreads', async () => {
+      const threads = await agentService.listThreads()
+      assert.ok(Array.isArray(threads))
+    })
+
+    if (aiStorageService) {
+      const storageFactory = aiStorageService
+
+      // The `owners` constraint is what keeps the generated thread-management
+      // functions from leaking across tenants: a caller may only list threads
+      // owned by one of their session principals, matching the
+      // `principal:sub-partition` composition resolveOwnerResourceId writes.
+      test('listThreads scopes to the given owners, including sub-partitions', async () => {
+        const storage = await storageFactory()
+        await storage.createThread('owner-alice')
+        await storage.createThread('owner-alice:project-1')
+        await storage.createThread('owner-bob:secret')
+
+        const threads = await agentService.listThreads({
+          owners: ['owner-alice'],
+        })
+        const ids = threads.map((t) => t.resourceId)
+
+        assert.ok(ids.includes('owner-alice'))
+        assert.ok(ids.includes('owner-alice:project-1'))
+        assert.ok(
+          !ids.some((id) => id.startsWith('owner-bob')),
+          "another owner's threads must not be listed"
+        )
+      })
+
+      test('listThreads with an owner does not match a lookalike prefix', async () => {
+        const storage = await storageFactory()
+        await storage.createThread('owner-al')
+        await storage.createThread('owner-alice-evil:p')
+
+        const threads = await agentService.listThreads({
+          owners: ['owner-al'],
+        })
+        const ids = threads.map((t) => t.resourceId)
+
+        assert.ok(ids.includes('owner-al'))
+        assert.ok(!ids.includes('owner-alice-evil:p'))
+      })
+
+      test('listThreads with an empty owners list returns nothing', async () => {
+        const storage = await storageFactory()
+        await storage.createThread('owner-empty-check')
+
+        const threads = await agentService.listThreads({ owners: [] })
+        assert.deepEqual(threads, [])
+      })
+    }
+
+    test('getThread returns null for missing', async () => {
+      const thread = await agentService.getThread('missing-thread')
+      assert.equal(thread, null)
+    })
+
+    test('getDistinctAgentNames', async () => {
+      const names = await agentService.getDistinctAgentNames()
+      assert.ok(Array.isArray(names))
+    })
+
+    test('deleteThread returns false for missing', async () => {
+      const result = await agentService.deleteThread('missing-thread')
+      assert.equal(result, false)
+    })
+  })
+}

package/src/testing/service-tests/ai-storage-service-tests.ts

@@ -0,0 +1,286 @@
+import { describe, test, before } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { AIStorageService } from '../../services/ai-storage-service.js'
+import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+import type { ServiceTestConfig } from '../service-tests.js'
+
+/** Conformance suite for `aiStorageService`. Runs only when a backend supplies one. */
+export const defineAiStorageServiceTests = (
+  name: string,
+  aiStorageService: NonNullable<
+    ServiceTestConfig['services']['aiStorageService']
+  >
+): void => {
+  const factory = aiStorageService
+  describe(`AIStorageService [${name}]`, () => {
+    let storage: AIStorageService & AIRunStateService
+
+    before(async () => {
+      storage = await factory()
+    })
+
+    test('createThread and getThread', async () => {
+      const thread = await storage.createThread('resource-1', {
+        title: 'Test Thread',
+        metadata: { key: 'val' },
+      })
+
+      assert.ok(thread.id)
+      assert.equal(thread.resourceId, 'resource-1')
+      assert.equal(thread.title, 'Test Thread')
+      assert.deepEqual(thread.metadata, { key: 'val' })
+
+      const fetched = await storage.getThread(thread.id)
+      assert.equal(fetched.id, thread.id)
+      assert.equal(fetched.title, 'Test Thread')
+    })
+
+    test('getThreads', async () => {
+      const threads = await storage.getThreads('resource-1')
+      assert.ok(threads.length >= 1)
+      assert.ok(threads.every((t) => t.resourceId === 'resource-1'))
+    })
+
+    test('getThread throws for missing', async () => {
+      await assert.rejects(() => storage.getThread('missing-thread'))
+    })
+
+    test('saveMessages and getMessages', async () => {
+      const thread = await storage.createThread('resource-2')
+      const now = new Date()
+
+      await storage.saveMessages(thread.id, [
+        { id: 'msg-1', role: 'user', content: 'Hello', createdAt: now },
+        {
+          id: 'msg-2',
+          role: 'assistant',
+          content: 'Hi there',
+          createdAt: new Date(now.getTime() + 1000),
+        },
+      ])
+
+      const messages = await storage.getMessages(thread.id)
+      assert.equal(messages.length, 2)
+      assert.equal(messages[0]!.role, 'user')
+      assert.equal(messages[0]!.content, 'Hello')
+      assert.equal(messages[1]!.role, 'assistant')
+      assert.equal(messages[1]!.content, 'Hi there')
+    })
+
+    test('saveMessages with tool calls and results', async () => {
+      const thread = await storage.createThread('resource-3')
+      const now = new Date()
+
+      await storage.saveMessages(thread.id, [
+        {
+          id: 'msg-tc',
+          role: 'assistant',
+          content: 'Let me call a tool',
+          toolCalls: [{ id: 'tc-1', name: 'search', args: { query: 'test' } }],
+          createdAt: now,
+        },
+      ])
+
+      await storage.saveMessages(thread.id, [
+        {
+          id: 'tool-results-msg-tc',
+          role: 'tool',
+          toolResults: [{ id: 'tc-1', name: 'search', result: 'found it' }],
+          createdAt: new Date(now.getTime() + 1000),
+        },
+      ])
+
+      const messages = await storage.getMessages(thread.id)
+      assert.equal(messages.length, 2)
+
+      const assistantMsg = messages[0]!
+      assert.equal(assistantMsg.role, 'assistant')
+      assert.ok(assistantMsg.toolCalls)
+      assert.equal(assistantMsg.toolCalls[0]!.name, 'search')
+
+      const toolMsg = messages[1]!
+      assert.equal(toolMsg.role, 'tool')
+      assert.ok(toolMsg.toolResults)
+      assert.equal(toolMsg.toolResults[0]!.result, 'found it')
+    })
+
+    test('getMessages with lastN', async () => {
+      const thread = await storage.createThread('resource-4')
+      const base = Date.now()
+
+      await storage.saveMessages(
+        thread.id,
+        Array.from({ length: 5 }, (_, i) => ({
+          id: `bulk-msg-${i}`,
+          role: 'user' as const,
+          content: `Message ${i}`,
+          createdAt: new Date(base + i * 1000),
+        }))
+      )
+
+      const messages = await storage.getMessages(thread.id, { lastN: 2 })
+      assert.equal(messages.length, 2)
+      assert.equal(messages[0]!.content, 'Message 3')
+      assert.equal(messages[1]!.content, 'Message 4')
+    })
+
+    test('working memory: save and get', async () => {
+      await storage.saveWorkingMemory('res-1', 'resource', {
+        key: 'value',
+      })
+
+      const mem = await storage.getWorkingMemory('res-1', 'resource')
+      assert.deepEqual(mem, { key: 'value' })
+    })
+
+    test('working memory: upsert overwrites', async () => {
+      await storage.saveWorkingMemory('res-1', 'resource', {
+        key: 'updated',
+      })
+
+      const mem = await storage.getWorkingMemory('res-1', 'resource')
+      assert.deepEqual(mem, { key: 'updated' })
+    })
+
+    test('working memory: returns null for missing', async () => {
+      const mem = await storage.getWorkingMemory('missing', 'thread')
+      assert.equal(mem, null)
+    })
+
+    test('createRun and getRun', async () => {
+      const thread = await storage.createThread('resource-5')
+      const now = new Date()
+
+      const runId = await storage.createRun({
+        agentName: 'test-agent',
+        threadId: thread.id,
+        resourceId: 'resource-5',
+        status: 'running',
+        usage: { inputTokens: 100, outputTokens: 50, model: 'test-model' },
+        createdAt: now,
+        updatedAt: now,
+      })
+
+      assert.ok(runId)
+
+      const run = await storage.getRun(runId)
+      assert.ok(run)
+      assert.equal(run.agentName, 'test-agent')
+      assert.equal(run.status, 'running')
+      assert.equal(run.usage.inputTokens, 100)
+    })
+
+    test('updateRun', async () => {
+      const thread = await storage.createThread('resource-6')
+      const now = new Date()
+
+      const runId = await storage.createRun({
+        agentName: 'update-agent',
+        threadId: thread.id,
+        resourceId: 'resource-6',
+        status: 'running',
+        usage: { inputTokens: 0, outputTokens: 0, model: 'test' },
+        createdAt: now,
+        updatedAt: now,
+      })
+
+      await storage.updateRun(runId, {
+        status: 'completed',
+        usage: { inputTokens: 200, outputTokens: 100, model: 'test-v2' },
+      })
+
+      const run = await storage.getRun(runId)
+      assert.ok(run)
+      assert.equal(run.status, 'completed')
+      assert.equal(run.usage.inputTokens, 200)
+      assert.equal(run.usage.model, 'test-v2')
+    })
+
+    test('getRunsByThread', async () => {
+      const thread = await storage.createThread('resource-7')
+      const now = new Date()
+
+      await storage.createRun({
+        agentName: 'multi-agent',
+        threadId: thread.id,
+        resourceId: 'resource-7',
+        status: 'completed',
+        usage: { inputTokens: 10, outputTokens: 5, model: 'test' },
+        createdAt: now,
+        updatedAt: now,
+      })
+
+      const runs = await storage.getRunsByThread(thread.id)
+      assert.ok(runs.length >= 1)
+      assert.ok(runs.every((r) => r.threadId === thread.id))
+    })
+
+    test('resolveApproval', async () => {
+      const thread = await storage.createThread('resource-8')
+      const now = new Date()
+
+      await storage.saveMessages(thread.id, [
+        {
+          id: 'approval-msg',
+          role: 'assistant',
+          toolCalls: [{ id: 'approval-tc', name: 'dangerous-tool', args: {} }],
+          createdAt: now,
+        },
+      ])
+
+      const runId = await storage.createRun({
+        agentName: 'approval-agent',
+        threadId: thread.id,
+        resourceId: 'resource-8',
+        status: 'suspended',
+        suspendReason: 'approval',
+        pendingApprovals: [
+          {
+            type: 'tool-call',
+            toolCallId: 'approval-tc',
+            toolName: 'dangerous-tool',
+            args: {},
+          },
+        ],
+        usage: { inputTokens: 0, outputTokens: 0, model: 'test' },
+        createdAt: now,
+        updatedAt: now,
+      })
+
+      let run = await storage.getRun(runId)
+      assert.ok(run)
+      assert.ok(run.pendingApprovals)
+      assert.equal(run.pendingApprovals.length, 1)
+
+      const claimed = await storage.resolveApproval('approval-tc', 'approved')
+      assert.equal(claimed, true, 'the first approver claims the approval')
+
+      run = await storage.getRun(runId)
+      assert.ok(run)
+      assert.equal(run.pendingApprovals, undefined)
+
+      const second = await storage.resolveApproval('approval-tc', 'approved')
+      assert.equal(
+        second,
+        false,
+        'a second approver of the same tool call claims nothing'
+      )
+    })
+
+    test('deleteThread cascades', async () => {
+      const thread = await storage.createThread('resource-del')
+      await storage.saveMessages(thread.id, [
+        {
+          id: 'del-msg',
+          role: 'user',
+          content: 'goodbye',
+          createdAt: new Date(),
+        },
+      ])
+
+      await storage.deleteThread(thread.id)
+      await assert.rejects(() => storage.getThread(thread.id))
+    })
+  })
+}

package/src/testing/service-tests/channel-store-tests.ts

@@ -0,0 +1,98 @@
+import { describe, test, before } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { ChannelStore } from '../../wirings/channel/channel-store.js'
+import type { ServiceTestConfig } from '../service-tests.js'
+
+/** Conformance suite for `channelStore`. Runs only when a backend supplies one. */
+export const defineChannelStoreTests = (
+  name: string,
+  channelStore: NonNullable<ServiceTestConfig['services']['channelStore']>
+): void => {
+  const factory = channelStore
+  describe(`ChannelStore [${name}]`, () => {
+    let store: ChannelStore
+
+    before(async () => {
+      store = await factory()
+    })
+
+    test('addChannel and getChannel', async () => {
+      await store.addChannel({
+        channelId: 'ch-1',
+        channelName: 'test-channel',
+        openingData: { foo: 'bar' },
+      })
+
+      const result = await store.getChannel('ch-1')
+      assert.equal(result.channelId, 'ch-1')
+      assert.equal(result.channelName, 'test-channel')
+      assert.deepEqual(result.openingData, { foo: 'bar' })
+      assert.equal(result.pikkuUserId, undefined)
+    })
+
+    test('setPikkuUserId', async () => {
+      await store.setPikkuUserId('ch-1', 'user-1')
+
+      const result = await store.getChannel('ch-1')
+      assert.equal(result.pikkuUserId, 'user-1')
+    })
+
+    test('setPikkuUserId to null', async () => {
+      await store.setPikkuUserId('ch-1', null)
+
+      const result = await store.getChannel('ch-1')
+      assert.equal(result.pikkuUserId, undefined)
+    })
+
+    test('getChannel throws for missing channel', async () => {
+      await assert.rejects(
+        async () => {
+          await store.getChannel('missing')
+        },
+        { message: 'Channel not found: missing' }
+      )
+    })
+
+    test('removeChannels', async () => {
+      await store.addChannel({
+        channelId: 'ch-2',
+        channelName: 'temp-channel',
+      })
+      await store.removeChannels(['ch-2'])
+      await assert.rejects(async () => {
+        await store.getChannel('ch-2')
+      })
+    })
+
+    test('removeChannels with empty array is no-op', async () => {
+      await store.removeChannels([])
+    })
+
+    test('session round-trip — set / get / clear', async () => {
+      await store.addChannel({
+        channelId: 'ch-state',
+        channelName: 'test-channel',
+      })
+
+      const empty = await store.getState('ch-state')
+      assert.equal(empty, undefined)
+
+      const payload = { userId: 'u-7', meta: { foo: 1 } }
+      await store.setState('ch-state', payload)
+      const got = await store.getState('ch-state')
+      assert.deepEqual(got, payload)
+
+      const next = { userId: 'u-8' }
+      await store.setState('ch-state', next)
+      const got2 = await store.getState('ch-state')
+      assert.deepEqual(got2, next)
+
+      await store.clearState('ch-state')
+      const after = await store.getState('ch-state')
+      assert.equal(after, undefined)
+
+      await store.removeChannels(['ch-state'])
+    })
+  })
+}