@pikku/core 0.12.106 → 0.12.111

package/src/utils.ts

@@ -1,165 +0,0 @@
-import type { Logger } from './services/logger.js'
-import type {
-  CoreSingletonServices,
-  ServerLifecycle,
-  WireServices,
-} from './types/core.types.js'
-import { getSingletonServices, getAllPackageStates } from './pikku-state.js'
-
-export const closeWireServices = async (
-  logger: Logger,
-  wireServices: WireServices
-) => {
-  await Promise.all(
-    Object.values(wireServices).map(async (service: any) => {
-      if (service?.close) {
-        try {
-          await service.close()
-        } catch (e: any) {
-          logger.error(e)
-        }
-      }
-    })
-  )
-}
-
-let _uidPrefix: string | undefined
-let _uidCounter = 0
-export const createWeakUID = () => {
-  _uidPrefix ??= globalThis.crypto.randomUUID().slice(0, 8)
-  return `${_uidPrefix}-${++_uidCounter}`
-}
-
-export const isSerializable = (data: any): boolean => {
-  return !(
-    typeof data === 'string' ||
-    data instanceof ArrayBuffer ||
-    data instanceof Uint8Array ||
-    data instanceof Int8Array ||
-    data instanceof Uint16Array ||
-    data instanceof Int16Array ||
-    data instanceof Uint32Array ||
-    data instanceof Int32Array ||
-    data instanceof Float32Array ||
-    data instanceof Float64Array
-  )
-}
-
-export const getTagGroups = <T>(
-  tagGroups: Record<string, T>,
-  tag: string
-): T[] => {
-  const results: T[] = []
-  const exact = tagGroups[tag]
-  if (exact) results.push(exact)
-  let colonIdx = tag.lastIndexOf(':')
-  while (colonIdx !== -1) {
-    const parent = tag.slice(0, colonIdx)
-    const group = tagGroups[parent]
-    if (group) results.push(group)
-    colonIdx = parent.lastIndexOf(':')
-  }
-  return results
-}
-
-const EMPTY_ARRAY = Object.freeze([])
-
-export const freezeDedupe = <T>(
-  arr?: readonly T[] | T[] | undefined
-): readonly T[] => {
-  if (!arr || arr.length === 0) return EMPTY_ARRAY
-  if (arr.length === 1) return Object.freeze([arr[0]!])
-  const seen = new Set<T>()
-  const out: T[] = []
-  for (let i = 0; i < arr.length; i++) {
-    const fn = arr[i]!
-    if (!seen.has(fn)) {
-      seen.add(fn)
-      out.push(fn)
-    }
-  }
-  return Object.freeze(out)
-}
-
-const stopService = async (
-  logger: Logger,
-  name: string,
-  service: any
-): Promise<void> => {
-  const stop = service?.stop
-  if (stop) {
-    logger.info(`Stopping singleton service: ${name}`)
-    try {
-      await stop.call(service)
-    } catch (e: any) {
-      logger.error(`Error stopping service ${name}:`, e)
-    }
-  }
-}
-
-/** Stops addon package services first, then the parent singleton services. */
-export const stopSingletonServices = async (): Promise<void> => {
-  const singletonServices = getSingletonServices()
-  const logger = singletonServices.logger
-
-  const stateMap = getAllPackageStates()
-  if (stateMap.size > 0) {
-    for (const [packageName, packageState] of stateMap) {
-      if (packageName === '__main__') continue
-
-      const packageServices = packageState.package?.singletonServices
-      if (packageServices) {
-        logger.info(`Stopping singleton services for package: ${packageName}`)
-        for (const [name, service] of Object.entries(packageServices)) {
-          await stopService(logger, `${packageName}/${name}`, service)
-        }
-        packageState.package.singletonServices = null
-      }
-    }
-  }
-
-  for (const [name, service] of Object.entries(singletonServices)) {
-    await stopService(logger, name, service)
-  }
-}
-
-/** Wrap server lifecycle hooks so the inspector can discover them. */
-export const pikkuServerLifecycle = <
-  SS extends CoreSingletonServices = CoreSingletonServices,
->(
-  lifecycle: ServerLifecycle<SS>
-): ServerLifecycle<SS> => lifecycle
-
-export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
-  Required<Pick<T, K>>
-
-export type JSONPrimitive = string | number | boolean | null | undefined
-
-export type JSONValue =
-  | JSONPrimitive
-  | JSONValue[]
-  | {
-      [key: string]: JSONValue
-    }
-
-export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>
-
-export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>
-
-export type RequireAtLeastOne<T> = {
-  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
-}[keyof T]
-
-export {
-  getDurationInMilliseconds,
-  getRelativeTimeOffset,
-  getRelativeTimeOffsetFromNow,
-  parseDurationString,
-} from './time-utils.js'
-export type { RelativeTimeInput } from './time-utils.js'
-
-export {
-  formatVersionedId,
-  isVersionedId,
-  parseVersionedId,
-} from './version.js'

package/src/version.test.ts

@@ -1,80 +0,0 @@
-import { strict as assert } from 'assert'
-import { describe, test } from 'node:test'
-import {
-  formatVersionedId,
-  parseVersionedId,
-  isVersionedId,
-} from './version.js'
-
-describe('formatVersionedId', () => {
-  test('formats base name with version', () => {
-    assert.strictEqual(formatVersionedId('createUser', 1), 'createUser@v1')
-    assert.strictEqual(formatVersionedId('createUser', 2), 'createUser@v2')
-    assert.strictEqual(formatVersionedId('createUser', 10), 'createUser@v10')
-  })
-
-  test('handles namespaced base names', () => {
-    assert.strictEqual(
-      formatVersionedId('pkg:createUser', 3),
-      'pkg:createUser@v3'
-    )
-  })
-})
-
-describe('parseVersionedId', () => {
-  test('parses versioned IDs', () => {
-    assert.deepStrictEqual(parseVersionedId('createUser@v1'), {
-      baseName: 'createUser',
-      version: 1,
-    })
-    assert.deepStrictEqual(parseVersionedId('createUser@v2'), {
-      baseName: 'createUser',
-      version: 2,
-    })
-    assert.deepStrictEqual(parseVersionedId('createUser@v10'), {
-      baseName: 'createUser',
-      version: 10,
-    })
-  })
-
-  test('returns null version for unversioned IDs', () => {
-    assert.deepStrictEqual(parseVersionedId('createUser'), {
-      baseName: 'createUser',
-      version: null,
-    })
-  })
-
-  test('returns null version for invalid version suffix', () => {
-    assert.deepStrictEqual(parseVersionedId('createUser@vx'), {
-      baseName: 'createUser@vx',
-      version: null,
-    })
-    assert.deepStrictEqual(parseVersionedId('createUser@v0'), {
-      baseName: 'createUser@v0',
-      version: null,
-    })
-    assert.deepStrictEqual(parseVersionedId('createUser@v-1'), {
-      baseName: 'createUser@v-1',
-      version: null,
-    })
-  })
-
-  test('handles namespaced versioned IDs', () => {
-    assert.deepStrictEqual(parseVersionedId('pkg:createUser@v3'), {
-      baseName: 'pkg:createUser',
-      version: 3,
-    })
-  })
-})
-
-describe('isVersionedId', () => {
-  test('returns true for versioned IDs', () => {
-    assert.strictEqual(isVersionedId('createUser@v1'), true)
-    assert.strictEqual(isVersionedId('createUser@v99'), true)
-  })
-
-  test('returns false for unversioned IDs', () => {
-    assert.strictEqual(isVersionedId('createUser'), false)
-    assert.strictEqual(isVersionedId('createUser@vx'), false)
-  })
-})

package/src/version.ts

@@ -1,25 +0,0 @@
-const VERSION_SEPARATOR = '@v'
-
-export function formatVersionedId(baseName: string, version: number): string {
-  return `${baseName}${VERSION_SEPARATOR}${version}`
-}
-
-export function parseVersionedId(id: string): {
-  baseName: string
-  version: number | null
-} {
-  const idx = id.lastIndexOf(VERSION_SEPARATOR)
-  if (idx === -1) {
-    return { baseName: id, version: null }
-  }
-  const versionStr = id.slice(idx + VERSION_SEPARATOR.length)
-  const version = Number(versionStr)
-  if (!Number.isInteger(version) || version < 1) {
-    return { baseName: id, version: null }
-  }
-  return { baseName: id.slice(0, idx), version }
-}
-
-export function isVersionedId(id: string): boolean {
-  return parseVersionedId(id).version !== null
-}

package/src/wirings/actor-flow/actor-flow.types.ts

@@ -1,40 +0,0 @@
-export type ActorFlowApprovalPolicy = 'in-persona' | 'always' | 'never'
-
-export interface ConverseOptions<TAgentName extends string = string> {
-  agent: TAgentName
-  /** What the actor is trying to get the agent to accomplish. */
-  task: string
-  /** Natural-language success criterion the actor judges the conversation against. */
-  evaluate: string
-  approvals?: ActorFlowApprovalPolicy
-  model?: string
-  maxTurns?: number
-}
-
-export interface ActorFlowVerdict {
-  passed: boolean
-  reasoning: string
-  transcript: string[]
-}
-
-export interface TargetPendingApproval {
-  toolCallId: string
-  toolName: string
-  args: unknown
-  reason?: string
-}
-
-export interface TargetAgentReply {
-  text: string
-  runId: string
-  status?: 'completed' | 'suspended'
-  pendingApprovals?: TargetPendingApproval[]
-}
-
-export interface TargetAgentDriver {
-  run(message: string): Promise<TargetAgentReply>
-  approve(
-    runId: string,
-    decisions: { toolCallId: string; approved: boolean }[]
-  ): Promise<TargetAgentReply>
-}

package/src/wirings/actor-flow/index.ts

@@ -1,10 +0,0 @@
-export type {
-  ActorFlowVerdict,
-  ConverseOptions,
-  TargetAgentDriver,
-} from './actor-flow.types.js'
-export {
-  runConversation,
-  type RunConversationParams,
-  type ActorLLM,
-} from './run-conversation.js'

package/src/wirings/actor-flow/run-conversation.test.ts

@@ -1,187 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { runConversation, type ActorLLM } from './run-conversation.js'
-import type {
-  TargetAgentDriver,
-  TargetAgentReply,
-  ActorFlowApprovalPolicy,
-} from './actor-flow.types.js'
-import type { AgentStepResult } from '../../services/agent-runner-service.js'
-
-const stepResult = (object: unknown): AgentStepResult => ({
-  text: '',
-  object,
-  toolCalls: [],
-  toolResults: [],
-  usage: { inputTokens: 0, outputTokens: 0 },
-  finishReason: 'stop',
-})
-
-const scriptedLLM = (script: {
-  turns: Array<{ message: string; done: boolean }>
-  decisions: Array<{ toolCallId: string; approved: boolean }>
-  evaluation: { passed: boolean; reasoning: string }
-}): { llm: ActorLLM; calls: string[] } => {
-  let turn = 0
-  const calls: string[] = []
-  const llm: ActorLLM = async (params) => {
-    const props =
-      (params.outputSchema as { properties?: Record<string, unknown> })
-        ?.properties ?? {}
-    if ('message' in props) {
-      assert.ok(
-        params.messages.length > 0,
-        'persona turn requested with empty messages'
-      )
-      const t = script.turns[turn] ?? script.turns[script.turns.length - 1]
-      turn++
-      calls.push('turn')
-      return stepResult(t)
-    }
-    if ('decisions' in props) {
-      calls.push('approval')
-      return stepResult({ decisions: script.decisions })
-    }
-    if ('passed' in props) {
-      calls.push('eval')
-      return stepResult(script.evaluation)
-    }
-    throw new Error('unexpected schema')
-  }
-  return { llm, calls }
-}
-
-const suspendingTarget = (): {
-  target: TargetAgentDriver
-  approvedWith: Array<{ toolCallId: string; approved: boolean }[]>
-} => {
-  let runs = 0
-  const approvedWith: Array<{ toolCallId: string; approved: boolean }[]> = []
-  const target: TargetAgentDriver = {
-    run: async (): Promise<TargetAgentReply> => {
-      runs++
-      if (runs === 1) {
-        return {
-          text: 'Let me do that.',
-          runId: 'run-1',
-          status: 'suspended',
-          pendingApprovals: [
-            { toolCallId: 'tc1', toolName: 'createTodo', args: { title: 'x' } },
-          ],
-        }
-      }
-      return { text: 'All set.', runId: `run-${runs}`, status: 'completed' }
-    },
-    approve: async (runId, decisions): Promise<TargetAgentReply> => {
-      approvedWith.push(decisions)
-      return { text: 'Created it.', runId, status: 'completed' }
-    },
-  }
-  return { target, approvedWith }
-}
-
-const alwaysSuspendingTarget = (): {
-  target: TargetAgentDriver
-  approveCalls: () => number
-} => {
-  let approveCalls = 0
-  const suspended: TargetAgentReply = {
-    text: 'working on it',
-    runId: 'run-stuck',
-    status: 'suspended',
-    pendingApprovals: [
-      { toolCallId: 'tc1', toolName: 'createTodo', args: { title: 'x' } },
-    ],
-  }
-  const target: TargetAgentDriver = {
-    run: async () => suspended,
-    approve: async () => {
-      approveCalls++
-      return suspended
-    },
-  }
-  return { target, approveCalls: () => approveCalls }
-}
-
-const base = {
-  persona: {
-    id: 'priya',
-    email: 'priya@personas.local',
-    name: 'Priya',
-    personality: 'concise',
-    roles: [],
-    goals: [],
-    tags: [],
-    runnable: true,
-  },
-  personaId: 'priya',
-  agentName: 'todoBot',
-  task: 'Get a todo created',
-  evaluate: 'A todo now exists',
-  model: 'test/test-model',
-}
-
-describe('runConversation', () => {
-  test('drives turns, approves in-persona, evaluates', async () => {
-    const { llm, calls } = scriptedLLM({
-      turns: [
-        { message: 'please make a todo', done: false },
-        { message: 'thanks', done: true },
-      ],
-      decisions: [{ toolCallId: 'tc1', approved: true }],
-      evaluation: { passed: true, reasoning: 'todo created' },
-    })
-    const { target, approvedWith } = suspendingTarget()
-
-    const verdict = await runConversation({ ...base, llm, target })
-
-    assert.equal(verdict.passed, true)
-    assert.match(verdict.reasoning, /todo/i)
-    assert.ok(verdict.transcript.length >= 2)
-    assert.deepEqual(approvedWith, [[{ toolCallId: 'tc1', approved: true }]])
-    assert.ok(calls.includes('approval'))
-    assert.ok(calls.includes('eval'))
-  })
-
-  test("approvals policy 'never' denies without asking the persona", async () => {
-    const { llm, calls } = scriptedLLM({
-      turns: [{ message: 'make a todo', done: true }],
-      decisions: [{ toolCallId: 'tc1', approved: true }],
-      evaluation: { passed: false, reasoning: 'blocked' },
-    })
-    const { target, approvedWith } = suspendingTarget()
-
-    const verdict = await runConversation({
-      ...base,
-      approvals: 'never' as ActorFlowApprovalPolicy,
-      llm,
-      target,
-    })
-
-    assert.deepEqual(approvedWith, [[{ toolCallId: 'tc1', approved: false }]])
-    assert.ok(!calls.includes('approval'))
-    assert.equal(verdict.passed, false)
-  })
-
-  test('caps the approval loop when the target never stops suspending', async () => {
-    const { llm } = scriptedLLM({
-      turns: [{ message: 'please make a todo', done: false }],
-      decisions: [{ toolCallId: 'tc1', approved: true }],
-      evaluation: { passed: false, reasoning: 'never got there' },
-    })
-    const { target, approveCalls } = alwaysSuspendingTarget()
-
-    await assert.rejects(
-      runConversation({
-        ...base,
-        approvals: 'always',
-        maxApprovalRounds: 3,
-        llm,
-        target,
-      }),
-      /approval rounds/
-    )
-    assert.equal(approveCalls(), 3)
-  })
-})