@pikku/core 0.12.107 → 0.12.112

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

@@ -1,280 +0,0 @@
-import type {
-  ActorFlowApprovalPolicy,
-  ActorFlowVerdict,
-  TargetAgentDriver,
-  TargetPendingApproval,
-} from './actor-flow.types.js'
-import type { ResolvedPersona } from '../../services/personas-service.js'
-import type { AgentMessage } from '../agent/agent.types.js'
-import type {
-  AgentRunnerParams,
-  AgentStepResult,
-} from '../../services/agent-runner-service.js'
-
-/** One turn the actor takes: the message to send and whether it's finished. */
-const ACTOR_TURN_SCHEMA = {
-  type: 'object',
-  properties: {
-    message: { type: 'string' },
-    done: { type: 'boolean' },
-  },
-  required: ['message', 'done'],
-} as const
-
-/** The actor's approve/deny decision for each pending tool request. */
-const APPROVAL_DECISION_SCHEMA = {
-  type: 'object',
-  properties: {
-    decisions: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          toolCallId: { type: 'string' },
-          approved: { type: 'boolean' },
-          reason: { type: 'string' },
-        },
-        required: ['toolCallId', 'approved'],
-      },
-    },
-  },
-  required: ['decisions'],
-} as const
-
-/** The actor's final verdict on whether the task was accomplished. */
-const EVALUATION_SCHEMA = {
-  type: 'object',
-  properties: {
-    passed: { type: 'boolean' },
-    reasoning: { type: 'string' },
-  },
-  required: ['passed', 'reasoning'],
-} as const
-
-const DEFAULT_MAX_TURNS = 12
-
-const DEFAULT_MAX_APPROVAL_ROUNDS = 16
-
-/** The LLM call the actor uses for its own turns/decisions/evaluation. */
-export type ActorLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>
-
-export interface RunConversationParams {
-  /** The person being played — name, job title, personality. */
-  persona: ResolvedPersona
-  /** The id they were declared under (for transcript labelling). */
-  personaId: string
-  /** What the actor is trying to get the target agent to accomplish. */
-  task: string
-  /** Natural-language success criterion the actor evaluates at the end. */
-  evaluate: string
-  /** How the actor answers the target agent's tool-approval requests. */
-  approvals?: ActorFlowApprovalPolicy
-  /** Model the actor uses for its own turns/decisions. */
-  model: string
-  /** Hard cap on conversation turns. Default 12. */
-  maxTurns?: number
-  /** Hard cap on tool-approval rounds within a single target turn. Default 16. */
-  maxApprovalRounds?: number
-  /** Transport that drives the target agent (HTTP in production). */
-  target: TargetAgentDriver
-  /** The actor's own LLM. */
-  llm: ActorLLM
-  /** Display name of the target agent (transcript labelling). */
-  agentName: string
-}
-
-function msg(role: AgentMessage['role'], content: string): AgentMessage {
-  return {
-    id: globalThis.crypto.randomUUID(),
-    role,
-    content,
-    createdAt: new Date(),
-  }
-}
-
-/** Read a structured `run` result, falling back to parsing JSON from text. */
-function readObject<T>(result: { object?: unknown; text?: string }): T | null {
-  if (result.object && typeof result.object === 'object') {
-    return result.object as T
-  }
-  if (result.text) {
-    try {
-      return JSON.parse(result.text) as T
-    } catch {
-      return null
-    }
-  }
-  return null
-}
-
-function actorInstructions(persona: ResolvedPersona, task: string): string {
-  return [
-    `You are role-playing a real user interacting with an AI assistant. Stay in character at all times — you are the user, not the assistant.`,
-    `Your name is ${persona.name}.`,
-    persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
-    persona.personality
-      ? `Your personality and communication style: ${persona.personality}. Match this tone, vocabulary, and level of detail exactly.`
-      : '',
-    `Your goal in this conversation: ${task}.`,
-    `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
-    // knowledge: decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md
-    `Reply with json matching the schema you are given, and nothing else.`,
-  ]
-    .filter(Boolean)
-    .join('\n')
-}
-
-/** Route the target agent's pending tool approvals through the actor. */
-async function decideApprovals(
-  params: RunConversationParams,
-  instructions: string,
-  pending: TargetPendingApproval[]
-): Promise<{ toolCallId: string; approved: boolean }[]> {
-  const policy = params.approvals ?? 'in-persona'
-  if (policy === 'always') {
-    return pending.map((p) => ({ toolCallId: p.toolCallId, approved: true }))
-  }
-  if (policy === 'never') {
-    return pending.map((p) => ({ toolCallId: p.toolCallId, approved: false }))
-  }
-
-  const summary = pending
-    .map(
-      (p) =>
-        `- toolCallId "${p.toolCallId}": ${p.toolName}(${JSON.stringify(p.args)})${p.reason ? ` — ${p.reason}` : ''}`
-    )
-    .join('\n')
-
-  const result = await params.llm({
-    model: params.model,
-    instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this actor, would allow each one.`,
-    messages: [
-      msg(
-        'user',
-        `The assistant wants to run these tools:\n${summary}\nApprove or deny each toolCallId.`
-      ),
-    ],
-    tools: [],
-    maxSteps: 1,
-    toolChoice: 'none',
-    outputSchema: APPROVAL_DECISION_SCHEMA as unknown as Record<
-      string,
-      unknown
-    >,
-  })
-
-  const decided =
-    readObject<{
-      decisions?: { toolCallId: string; approved: boolean }[]
-    }>(result)?.decisions ?? []
-
-  // Every pending call must get a decision; a missing one defaults to denied.
-  return pending.map((p) => {
-    const match = decided.find((d) => d.toolCallId === p.toolCallId)
-    return { toolCallId: p.toolCallId, approved: match?.approved ?? false }
-  })
-}
-
-/** Drive the target to a non-suspended reply, routing approvals to the actor. */
-async function converseWithTarget(
-  params: RunConversationParams,
-  instructions: string,
-  message: string
-) {
-  const maxRounds = params.maxApprovalRounds ?? DEFAULT_MAX_APPROVAL_ROUNDS
-  let reply = await params.target.run(message)
-  let rounds = 0
-  while (
-    reply.status === 'suspended' &&
-    reply.pendingApprovals &&
-    reply.pendingApprovals.length > 0
-  ) {
-    if (rounds >= maxRounds) {
-      throw new Error(
-        `Target agent "${params.agentName}" stayed suspended after ${maxRounds} approval rounds (runId ${reply.runId}); aborting to avoid an unbounded approve loop.`
-      )
-    }
-    rounds++
-    const decisions = await decideApprovals(
-      params,
-      instructions,
-      reply.pendingApprovals
-    )
-    reply = await params.target.approve(reply.runId, decisions)
-  }
-  return reply
-}
-
-/**
- * Run a conversation: an LLM-driven actor holds a real multi-turn exchange
- * with a target agent (driven via the injected transport), answers the target's
- * tool-approval requests in-persona, then evaluates whether the task was met.
- * Deterministic checks are the caller's responsibility.
- */
-export async function runConversation(
-  params: RunConversationParams
-): Promise<ActorFlowVerdict> {
-  const maxTurns = params.maxTurns ?? DEFAULT_MAX_TURNS
-  const instructions = actorInstructions(params.persona, params.task)
-  // Seed a kickoff so the very first actor turn has a non-empty message list
-  // (providers reject an empty prompt). It's an instruction TO the actor, so
-  // it never appears in the transcript.
-  const actorMessages: AgentMessage[] = [
-    msg(
-      'user',
-      'Begin the conversation now — send your first message to the assistant to work towards your goal.'
-    ),
-  ]
-  const transcript: string[] = []
-
-  for (let turn = 0; turn < maxTurns; turn++) {
-    const actorResult = await params.llm({
-      model: params.model,
-      instructions,
-      messages: actorMessages,
-      tools: [],
-      maxSteps: 1,
-      toolChoice: 'none',
-      outputSchema: ACTOR_TURN_SCHEMA as unknown as Record<string, unknown>,
-    })
-
-    const turnData = readObject<{ message: string; done: boolean }>(actorResult)
-    const actorMessage = turnData?.message?.trim()
-    if (!actorMessage) {
-      break
-    }
-
-    actorMessages.push(msg('assistant', actorMessage))
-    transcript.push(`${params.persona.name}: ${actorMessage}`)
-
-    const reply = await converseWithTarget(params, instructions, actorMessage)
-    actorMessages.push(msg('user', reply.text ?? ''))
-    transcript.push(`${params.agentName}: ${reply.text ?? ''}`)
-
-    if (turnData?.done) {
-      break
-    }
-  }
-
-  const evalResult = await params.llm({
-    model: params.model,
-    instructions: `${instructions}\nThe conversation has ended. Judge honestly whether your goal was accomplished.`,
-    messages: [
-      msg(
-        'user',
-        `Here is the full conversation:\n\n${transcript.join('\n')}\n\nSuccess criterion: ${params.evaluate}\n\nWas it met?`
-      ),
-    ],
-    tools: [],
-    maxSteps: 1,
-    toolChoice: 'none',
-    outputSchema: EVALUATION_SCHEMA as unknown as Record<string, unknown>,
-  })
-
-  const verdict = readObject<{ passed: boolean; reasoning: string }>(evalResult)
-  return {
-    passed: verdict?.passed ?? false,
-    reasoning: verdict?.reasoning ?? 'No evaluation produced.',
-    transcript,
-  }
-}

package/src/wirings/addon/addon-auth-tags.test.ts

@@ -1,219 +0,0 @@
-import { beforeEach, describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-import {
-  addTagMiddleware,
-  clearMiddlewareCache,
-} from '../../middleware-runner.js'
-import { ForbiddenError, MissingSessionError } from '../../errors/errors.js'
-import { resolveAddonAuth, resolveAddonTags, wireAddon } from './wire-addon.js'
-
-const ADDON_PACKAGE = '@addon/console'
-
-const createServices = () =>
-  ({
-    logger: {
-      debug: () => {},
-      info: () => {},
-      warn: () => {},
-      error: () => {},
-    },
-  }) as never
-
-const registerAddonFunction = (funcName: string) => {
-  addFunction(funcName, { func: async () => 'ok' } as never, ADDON_PACKAGE)
-  pikkuState(ADDON_PACKAGE, 'function', 'meta')[funcName] = {
-    name: funcName,
-    sessionless: true,
-    permissions: [],
-  } as never
-}
-
-const session = () => ({ userId: 'u1' }) as never
-
-/**
- * How an addon function is reached over a directly-wired route: the inspector
- * records the addon package on the wiring meta and the runner hands it to
- * `runPikkuFunc`, never passing through namespace resolution.
- */
-const callOverDirectWiring = (
-  funcName: string,
-  {
-    wireType = 'http',
-    withSession = false,
-    auth,
-  }: {
-    wireType?: string
-    withSession?: boolean
-    auth?: boolean
-  } = {}
-) =>
-  runPikkuFunc(wireType as never, `${wireType}:/console/thing`, funcName, {
-    singletonServices: createServices(),
-    data: () => ({}),
-    auth,
-    packageName: ADDON_PACKAGE,
-    wire: (withSession ? { session: session() } : {}) as never,
-  })
-
-beforeEach(() => {
-  resetPikkuState()
-  // resetPikkuState deliberately leaves runtime caches alone; combineMiddleware
-  // keys its cache on wireType/wireId, which these tests reuse.
-  clearMiddlewareCache()
-  pikkuState(null, 'package', 'singletonServices', createServices())
-})
-
-describe('resolveAddonAuth', () => {
-  test('is false for a non-addon package', () => {
-    assert.equal(resolveAddonAuth(null), false)
-    assert.equal(resolveAddonAuth('@addon/other'), false)
-  })
-
-  test('reads the named instance when one is resolved', () => {
-    wireAddon({ name: 'live', package: ADDON_PACKAGE, auth: true })
-    wireAddon({ name: 'test', package: ADDON_PACKAGE, auth: false })
-
-    assert.equal(resolveAddonAuth(ADDON_PACKAGE, 'live'), true)
-    assert.equal(resolveAddonAuth(ADDON_PACKAGE, 'test'), false)
-  })
-
-  test('takes the stricter reading across namespaces on the unnamed path', () => {
-    wireAddon({ name: 'live', package: ADDON_PACKAGE, auth: true })
-    wireAddon({ name: 'test', package: ADDON_PACKAGE, auth: false })
-
-    assert.equal(resolveAddonAuth(ADDON_PACKAGE), true)
-  })
-})
-
-describe('resolveAddonTags', () => {
-  test('unions tags across every namespace the package is wired under', () => {
-    wireAddon({ name: 'live', package: ADDON_PACKAGE, tags: ['admin'] })
-    wireAddon({ name: 'test', package: ADDON_PACKAGE, tags: ['sandbox'] })
-
-    assert.deepEqual(resolveAddonTags(ADDON_PACKAGE).sort(), [
-      'admin',
-      'sandbox',
-    ])
-  })
-
-  test('reads the named instance exactly when one is resolved', () => {
-    wireAddon({ name: 'live', package: ADDON_PACKAGE, tags: ['admin'] })
-    wireAddon({ name: 'test', package: ADDON_PACKAGE, tags: ['sandbox'] })
-
-    assert.deepEqual(resolveAddonTags(ADDON_PACKAGE, 'live'), ['admin'])
-  })
-})
-
-describe('wireAddon auth on direct wirings', () => {
-  test('requires a session for a sessionless addon function', async () => {
-    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: true })
-    registerAddonFunction('credentialGet')
-
-    await assert.rejects(
-      () => callOverDirectWiring('credentialGet'),
-      MissingSessionError
-    )
-  })
-
-  test('allows the call once a session is present', async () => {
-    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: true })
-    registerAddonFunction('credentialGet')
-
-    assert.equal(
-      await callOverDirectWiring('credentialGet', { withSession: true }),
-      'ok'
-    )
-  })
-
-  test('leaves an addon wired without auth ungated', async () => {
-    wireAddon({ name: 'console', package: ADDON_PACKAGE })
-    registerAddonFunction('credentialGet')
-
-    assert.equal(await callOverDirectWiring('credentialGet'), 'ok')
-  })
-
-  test('does not weaken a wiring that already requires auth', async () => {
-    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: false })
-    registerAddonFunction('credentialGet')
-
-    await assert.rejects(
-      () => callOverDirectWiring('credentialGet', { auth: true }),
-      MissingSessionError
-    )
-  })
-
-  test('gates every wiring kind, not just http', async () => {
-    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: true })
-    registerAddonFunction('credentialGet')
-
-    for (const wireType of [
-      'http',
-      'channel',
-      'queue',
-      'scheduler',
-      'cli',
-      'mcp',
-      'trigger',
-      'gateway',
-    ]) {
-      await assert.rejects(
-        () => callOverDirectWiring('credentialGet', { wireType }),
-        MissingSessionError,
-        `${wireType} should have been gated`
-      )
-    }
-  })
-})
-
-describe('wireAddon tags on direct wirings', () => {
-  test('runs middleware the app registered for the addon tag', async () => {
-    const seen: string[] = []
-    addTagMiddleware('admin', [
-      (async (_services: never, _wire: never, next: () => Promise<void>) => {
-        seen.push('admin')
-        await next()
-      }) as never,
-    ])
-
-    wireAddon({ name: 'console', package: ADDON_PACKAGE, tags: ['admin'] })
-    registerAddonFunction('credentialGet')
-
-    assert.equal(await callOverDirectWiring('credentialGet'), 'ok')
-    assert.deepEqual(seen, ['admin'])
-  })
-
-  test('lets that middleware reject the call', async () => {
-    addTagMiddleware('admin', [
-      (async () => {
-        throw new ForbiddenError('nope')
-      }) as never,
-    ])
-
-    wireAddon({ name: 'console', package: ADDON_PACKAGE, tags: ['admin'] })
-    registerAddonFunction('credentialGet')
-
-    await assert.rejects(
-      () => callOverDirectWiring('credentialGet'),
-      ForbiddenError
-    )
-  })
-
-  test('leaves an addon wired without tags alone', async () => {
-    const seen: string[] = []
-    addTagMiddleware('admin', [
-      (async (_services: never, _wire: never, next: () => Promise<void>) => {
-        seen.push('admin')
-        await next()
-      }) as never,
-    ])
-
-    wireAddon({ name: 'console', package: ADDON_PACKAGE })
-    registerAddonFunction('credentialGet')
-
-    assert.equal(await callOverDirectWiring('credentialGet'), 'ok')
-    assert.deepEqual(seen, [])
-  })
-})