@pikku/core 0.12.63 → 0.12.64

package/src/wirings/ai-agent/ai-agent-prepare.test.ts

@@ -3,12 +3,16 @@ import assert from 'node:assert/strict'
 
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
 import {
+  agentSessionScope,
+  assertResourceOwner,
   buildInstructions,
   buildToolDefs,
   createScopedChannel,
   getAddonCredentialRequirements,
   resolveAgent,
+  resolveOwnerResourceId,
 } from './ai-agent-prepare.js'
+import { ForbiddenError } from '../../errors/errors.js'
 import type {
   AIStreamChannel,
   AIStreamEvent,
@@ -150,6 +154,7 @@ describe('ai-agent-prepare', () => {
       toolCallId: 'tc-1',
       toolName: 'tool-a',
       args: { x: 1 },
+      reason: 'Delete todo "x"',
       runId: 'run-1',
     } as AIStreamEvent)
     channel.send({ type: 'done' } as AIStreamEvent)
@@ -161,6 +166,7 @@ describe('ai-agent-prepare', () => {
         toolCallId: 'tc-1',
         toolName: 'tool-a',
         args: { x: 1 },
+        reason: 'Delete todo "x"',
         runId: 'run-1',
       },
     ])
@@ -237,6 +243,106 @@ describe('ai-agent-prepare', () => {
     assert.equal(afterCalls.length, 1)
   })
 
+  test('buildToolDefs resolves addon-scoped services for approvalDescription on a cold services cache', async () => {
+    addAgent('todo-agent')
+    pikkuState(null, 'agent', 'agentsMeta')['todo-agent'] = {
+      ...pikkuState(null, 'agent', 'agentsMeta')['todo-agent'],
+      tools: ['todos:deleteTodo'],
+    } as any
+    pikkuState(null, 'addons', 'packages').set('todos', {
+      package: '@test/todos-addon',
+    })
+    pikkuState('@test/todos-addon', 'function', 'meta').deleteTodo = {
+      description: 'Deletes a todo by ID',
+      approvalRequired: true,
+      inputSchemaName: 'DeleteTodoInput',
+      sessionless: true,
+    } as any
+    pikkuState('@test/todos-addon', 'misc', 'schemas').set('DeleteTodoInput', {
+      type: 'object',
+    })
+    pikkuState('@test/todos-addon', 'function', 'functions').set('deleteTodo', {
+      func: async ({ todoStore }: any, { id }: any) => todoStore.delete(id),
+      approvalDescription: async ({ todoStore }: any, { id }: any) =>
+        `Delete the todo called "${todoStore.get(id)?.title ?? id}"`,
+    })
+
+    // The addon builds `todoStore` in its own singleton services, which are NOT
+    // in the root services and are only cached the first time the addon runs.
+    // The approval is raised before the tool executes, so the cache is cold.
+    pikkuState('@test/todos-addon', 'package', 'factories', {
+      createSingletonServices: async () => ({
+        todoStore: {
+          get: (id: string) =>
+            id === '1' ? { id: '1', title: 'Buy groceries' } : undefined,
+          delete: () => true,
+        },
+      }),
+    } as any)
+
+    const singletonServices = {
+      logger: { warn: () => {} },
+    } as any
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
+
+    const { tools } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'todo-agent',
+      null
+    )
+
+    assert.equal(tools.length, 1)
+    assert.equal(tools[0].needsApproval, true)
+    assert.equal(
+      await tools[0].approvalDescriptionFn?.({ id: '1' }),
+      'Delete the todo called "Buy groceries"'
+    )
+  })
+
+  test('buildToolDefs logs a tool execute() failure even without aiMiddleware hooks, then rethrows', async () => {
+    addAgent('ops-agent')
+    pikkuState(null, 'agent', 'agentsMeta')['ops-agent'] = {
+      ...pikkuState(null, 'agent', 'agentsMeta')['ops-agent'],
+      tools: ['searchInventory'],
+    } as any
+    pikkuState(null, 'rpc', 'meta').searchInventory = 'searchInventory'
+    pikkuState(null, 'function', 'meta').searchInventory = {
+      description: 'Search inventory',
+      inputSchemaName: 'SearchInput',
+      sessionless: true,
+    }
+    pikkuState(null, 'misc', 'schemas').set('SearchInput', { type: 'object' })
+    pikkuState(null, 'function', 'functions').set('searchInventory', {
+      func: async () => {
+        throw new Error('db unreachable')
+      },
+    })
+
+    const errorCalls: unknown[][] = []
+    const singletonServices = {
+      logger: {
+        warn: () => {},
+        error: (...args: unknown[]) => errorCalls.push(args),
+      },
+    } as any
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
+
+    const { tools } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'ops-agent',
+      null
+    )
+
+    assert.equal(tools.length, 1)
+    await assert.rejects(() => tools[0].execute({}), /db unreachable/)
+    assert.equal(errorCalls.length, 1)
+    assert.match(String(errorCalls[0][0]), /searchInventory.*execute/)
+  })
+
   test('buildToolDefs skips permissioned tools without a session and adds sub-agent tools', async () => {
     addAgent('manager', {
       agents: ['assistant'],
@@ -291,4 +397,206 @@ describe('ai-agent-prepare', () => {
       required: ['message', 'session'],
     })
   })
+
+  test('buildToolDefs adds a workflow tool that runs the workflow and returns its output', async () => {
+    addAgent('planner', { workflows: ['buildReport'] } as any)
+    pikkuState(null, 'agent', 'agentsMeta').planner = {
+      ...pikkuState(null, 'agent', 'agentsMeta').planner,
+      workflows: ['buildReport'],
+    } as any
+
+    pikkuState(null, 'workflows', 'meta').buildReport = {
+      name: 'buildReport',
+      pikkuFuncId: 'buildReport',
+      source: 'graph',
+      description: 'Build a report for a country',
+    } as any
+    pikkuState(null, 'function', 'meta').buildReport = {
+      inputSchemaName: 'BuildReportInput',
+      sessionless: true,
+    } as any
+    pikkuState(null, 'misc', 'schemas').set('BuildReportInput', {
+      type: 'object',
+      properties: { country: { type: 'string' } },
+      required: ['country'],
+    })
+
+    const runCalls: Array<{ name: string; input: unknown }> = []
+    const workflowService = {
+      runToCompletion: async (name: string, input: unknown) => {
+        runCalls.push({ name, input })
+        return { capital: 'Paris' }
+      },
+    }
+    const singletonServices = {
+      logger: { warn: () => {} },
+      workflowService,
+    } as any
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
+
+    const { tools, missingRpcs } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'planner',
+      null
+    )
+
+    assert.deepEqual(missingRpcs, [])
+    assert.equal(tools.length, 1)
+    assert.equal(tools[0].name, 'buildReport')
+    assert.equal(tools[0].description, 'Build a report for a country')
+    assert.deepEqual(tools[0].inputSchema, {
+      type: 'object',
+      properties: { country: { type: 'string' } },
+      required: ['country'],
+    })
+
+    const result = await tools[0].execute({ country: 'France' })
+    assert.deepEqual(result, { capital: 'Paris' })
+    assert.deepEqual(runCalls, [
+      { name: 'buildReport', input: { country: 'France' } },
+    ])
+  })
+
+  test('buildToolDefs reports an unknown workflow tool as missing', async () => {
+    addAgent('planner2', { workflows: ['ghost'] } as any)
+    pikkuState(null, 'agent', 'agentsMeta').planner2 = {
+      ...pikkuState(null, 'agent', 'agentsMeta').planner2,
+      workflows: ['ghost'],
+    } as any
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { warn: () => {} },
+      workflowService: { runToCompletion: async () => ({}) },
+    } as any)
+
+    const { tools, missingRpcs } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'planner2',
+      null
+    )
+
+    assert.equal(tools.length, 0)
+    assert.deepEqual(missingRpcs, ['ghost'])
+  })
+})
+
+describe('C2 thread/run ownership + sessionScope', () => {
+  const params = (session?: Record<string, unknown>) => ({
+    sessionService: { get: () => session } as never,
+  })
+
+  test('user scope composes the trusted userId with the requested resourceId', () => {
+    assert.equal(
+      resolveOwnerResourceId(params({ userId: 'user-a' }), 'user', 'default'),
+      'user-a:default'
+    )
+  })
+
+  test('user scope is the default when sessionScope is undefined', () => {
+    assert.equal(
+      resolveOwnerResourceId(params({ userId: 'user-a' }), undefined, 'p1'),
+      'user-a:p1'
+    )
+  })
+
+  test('user scope sub-partitions within the owner (client resourceId regains meaning)', () => {
+    assert.equal(
+      resolveOwnerResourceId(params({ userId: 'alice' }), 'user', 'project-1'),
+      'alice:project-1'
+    )
+    assert.equal(
+      resolveOwnerResourceId(params({ userId: 'alice' }), 'user', 'project-2'),
+      'alice:project-2'
+    )
+  })
+
+  test('is idempotent: re-normalizing an already-owned key does not double-compose', () => {
+    assert.equal(
+      resolveOwnerResourceId(
+        params({ userId: 'alice' }),
+        'user',
+        'alice:project-1'
+      ),
+      'alice:project-1'
+    )
+  })
+
+  test('a client cannot forge another owner: a foreign prefix is re-scoped, not trusted', () => {
+    assert.equal(
+      resolveOwnerResourceId(params({ userId: 'bob' }), 'user', 'alice:secret'),
+      'bob:alice:secret'
+    )
+  })
+
+  test('user scope falls back to the bare requested resourceId when sessionless', () => {
+    assert.equal(resolveOwnerResourceId({}, 'user', 'resource-1'), 'resource-1')
+    assert.equal(
+      resolveOwnerResourceId(params(undefined), 'user', 'resource-1'),
+      'resource-1'
+    )
+  })
+
+  test('org scope composes the trusted orgId with the requested resourceId', () => {
+    assert.equal(
+      resolveOwnerResourceId(
+        params({ userId: 'user-a', orgId: 'org-x' }),
+        'org',
+        'default'
+      ),
+      'org-x:default'
+    )
+  })
+
+  test('org scope denies (ForbiddenError) when the session has no org', () => {
+    assert.throws(
+      () =>
+        resolveOwnerResourceId(params({ userId: 'user-a' }), 'org', 'default'),
+      (e: unknown) => e instanceof ForbiddenError
+    )
+    assert.throws(
+      () => resolveOwnerResourceId({}, 'org', 'default'),
+      (e: unknown) => e instanceof ForbiddenError
+    )
+  })
+
+  test('assertResourceOwner throws ForbiddenError on an owner mismatch', () => {
+    assert.throws(
+      () => assertResourceOwner('user-a:d', 'user-b:d', 'thread'),
+      (e: unknown) =>
+        e instanceof ForbiddenError && !/user-a|user-b/.test(e.message)
+    )
+    assert.doesNotThrow(() =>
+      assertResourceOwner('user-a:d', 'user-a:d', 'run')
+    )
+  })
+
+  test('agentSessionScope reads the declared scope and defaults to user', () => {
+    addAgent('scoped-user')
+    addAgent('scoped-org', { sessionScope: 'org' })
+    assert.equal(agentSessionScope('scoped-user'), 'user')
+    assert.equal(agentSessionScope('scoped-org'), 'org')
+  })
+
+  test('resume ownership: owner passes, a different user is rejected (via idempotent recompose)', () => {
+    const stored = 'alice:default'
+    assert.doesNotThrow(() =>
+      assertResourceOwner(
+        resolveOwnerResourceId(params({ userId: 'alice' }), 'user', stored),
+        stored,
+        'run'
+      )
+    )
+    assert.throws(
+      () =>
+        assertResourceOwner(
+          resolveOwnerResourceId(params({ userId: 'bob' }), 'user', stored),
+          stored,
+          'run'
+        ),
+      (e: unknown) => e instanceof ForbiddenError
+    )
+  })
 })

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -8,11 +8,13 @@ import type {
   AIStreamChannel,
   AIStreamEvent,
   PikkuAIMiddlewareHooks,
+  SessionScope,
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
 import { checkAuthPermissions } from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
+import { ForbiddenError } from '../../errors/errors.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
@@ -23,6 +25,7 @@ import {
   resolveNamespace,
   ContextAwareRPCService,
 } from '../../wirings/rpc/rpc-runner.js'
+import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js'
 import {
   resolveMemoryServices,
   loadContextMessages,
@@ -36,10 +39,91 @@ export type RunAIAgentParams = {
   getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>
 }
 
+/**
+ * The ownership key for a thread/run: the trusted principal (the authenticated
+ * `session.userId` for `'user'` scope, or `session.orgId` for `'org'` scope)
+ * composed with the client-supplied `resourceId` as a sub-partition —
+ * `principal:resourceId`. Because the principal is always the prefix, a client
+ * `resourceId` can sub-divide within the caller's own boundary but can never
+ * widen access to another user's or org's threads.
+ *
+ * Idempotent: a value that is already within the caller's namespace (top-level
+ * re-entry, sub-agent recursion, or resume, which all pass an already-composite
+ * `resourceId`) is returned unchanged rather than double-composed.
+ *
+ * `'org'` scope with no session org throws {@link ForbiddenError} — falling back
+ * to a bare/shared key would leak across organizations. Sessionless `'user'`
+ * wirings have no trusted principal and fall back to the requested `resourceId`
+ * as a best-effort partition key.
+ */
+export function resolveOwnerResourceId(
+  params: RunAIAgentParams,
+  sessionScope: SessionScope | undefined,
+  requestedResourceId: string
+): string {
+  const session = params.sessionService?.get()
+  let principal: string | undefined
+  if ((sessionScope ?? 'user') === 'org') {
+    if (!session?.orgId) {
+      throw new ForbiddenError(
+        'This agent is org-scoped but the session has no organization'
+      )
+    }
+    principal = session.orgId
+  } else {
+    principal = session?.userId
+  }
+
+  if (!principal) return requestedResourceId
+  if (
+    requestedResourceId === principal ||
+    requestedResourceId.startsWith(`${principal}:`)
+  ) {
+    return requestedResourceId
+  }
+  return `${principal}:${requestedResourceId}`
+}
+
+/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export function agentSessionScope(agentName: string): SessionScope {
+  return resolveAgent(agentName).agent.sessionScope ?? 'user'
+}
+
+/**
+ * Enforce that a stored thread/run belongs to the caller's owner resource,
+ * throwing {@link ForbiddenError} (without echoing the id, to avoid an
+ * existence oracle) on a mismatch.
+ */
+export function assertResourceOwner(
+  ownerResourceId: string,
+  storedResourceId: string,
+  kind: 'thread' | 'run'
+): void {
+  if (storedResourceId !== ownerResourceId) {
+    throw new ForbiddenError(`Not authorized to access this ${kind}`)
+  }
+}
+
 export type StreamAIAgentOptions = {
   requiresToolApproval?: 'all' | 'explicit' | false
+  /**
+   * Invoked as soon as the run's AIRunStateService id exists, so transport
+   * wrappers (e.g. the AG-UI bridge) can stamp the real runId on RUN_STARTED.
+   */
+  onRunCreated?: (runId: string) => void
 }
 
+/**
+ * Non-forgeable brand for the sub-agent approval marker. Only framework code
+ * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
+ * sub-agent's LLM-shaped `result.object` — plain JSON — cannot carry a Symbol,
+ * so `checkForApprovals` trusts the brand rather than the `__approvalRequired`
+ * string key to decide an approval must be surfaced.
+ */
+export const APPROVAL_REQUIRED: unique symbol = Symbol(
+  'pikku.ai.approvalRequired'
+)
+
 export class ToolApprovalRequired extends PikkuError {
   public readonly toolCallId: string
   public readonly toolName: string
@@ -193,7 +277,7 @@ export async function buildInstructions(
   if (meta?.goal) parts.push(meta.goal)
   let instructions = parts.join('\n\n')
 
-  if (meta?.tools?.length) {
+  if (meta?.tools?.length || meta?.workflows?.length) {
     instructions +=
       '\n\nTool usage rules:\n' +
       '- Act immediately with the information given. Do NOT ask clarifying questions unless a required field is truly missing.\n' +
@@ -219,6 +303,7 @@ export type ScopedChannel = AIStreamChannel & {
     toolCallId: string
     toolName: string
     args: unknown
+    reason?: string
     runId: string
   }>
 }
@@ -248,6 +333,7 @@ export function createScopedChannel(
           toolCallId: event.toolCallId,
           toolName: event.toolName,
           args: event.args,
+          ...(event.reason !== undefined ? { reason: event.reason } : {}),
           runId: (event as any).runId,
         })
         return
@@ -373,17 +459,27 @@ export async function buildToolDefs(
         if (funcConfig?.approvalDescription) {
           const descFn = funcConfig.approvalDescription
           const capturedPkg = resolvedPkg
+          const capturedAddonConfig = resolved?.addonConfig
+          const capturedNamespace = toolName.includes(':')
+            ? toolName.slice(0, toolName.indexOf(':'))
+            : null
           approvalDescriptionFn = async (input: unknown) => {
             let services = singletonServices
             if (capturedPkg) {
-              const pkgServices = pikkuState(
+              const addonInstance = capturedNamespace
+                ? {
+                    namespace: capturedNamespace,
+                    secretOverrides: capturedAddonConfig?.secretOverrides,
+                    variableOverrides: capturedAddonConfig?.variableOverrides,
+                    credentialOverrides:
+                      capturedAddonConfig?.credentialOverrides,
+                  }
+                : undefined
+              services = await getOrCreatePackageSingletonServices(
                 capturedPkg,
-                'package',
-                'singletonServices'
+                singletonServices,
+                addonInstance
               )
-              if (pkgServices) {
-                services = pkgServices
-              }
             }
             return descFn(services, input)
           }
@@ -437,6 +533,7 @@ export async function buildToolDefs(
       tools.push({
         name: subAgentName,
         description: subMeta.description,
+        forwardsApproval: true,
         inputSchema: {
           type: 'object',
           properties: {
@@ -502,6 +599,7 @@ export async function buildToolDefs(
             )
             if (subChannel.approvals.length > 0) {
               return {
+                [APPROVAL_REQUIRED]: true,
                 __approvalRequired: true,
                 toolName: subAgentName,
                 args: toolInput,
@@ -530,6 +628,7 @@ export async function buildToolDefs(
             result.pendingApprovals?.length
           ) {
             return {
+              [APPROVAL_REQUIRED]: true,
               __approvalRequired: true,
               toolName: subAgentName,
               args: toolInput,
@@ -538,6 +637,7 @@ export async function buildToolDefs(
                 toolCallId: a.toolCallId,
                 toolName: a.toolName,
                 args: a.args,
+                reason: a.reason,
                 runId: a.runId,
               })),
             }
@@ -548,6 +648,84 @@ export async function buildToolDefs(
     }
   }
 
+  const metaWorkflows = meta.workflows
+  if (metaWorkflows?.length) {
+    const workflowMetaMap = pikkuState(null, 'workflows', 'meta')
+    const functionMeta = pikkuState(null, 'function', 'meta')
+    const schemas = pikkuState(null, 'misc', 'schemas')
+
+    for (const workflowName of metaWorkflows) {
+      const wfMeta = workflowMetaMap[workflowName]
+      if (!wfMeta) {
+        missingRpcs.push(workflowName)
+        continue
+      }
+
+      const inputSchemaName = wfMeta.pikkuFuncId
+        ? functionMeta[wfMeta.pikkuFuncId]?.inputSchemaName
+        : undefined
+      let inputSchema = inputSchemaName
+        ? schemas.get(inputSchemaName)
+        : undefined
+      if (
+        !inputSchema ||
+        (typeof inputSchema === 'object' &&
+          inputSchema.type === 'object' &&
+          !inputSchema.properties)
+      ) {
+        inputSchema = { type: 'object', properties: {} }
+      }
+
+      tools.push({
+        name: workflowName,
+        description: wfMeta.description || workflowName,
+        inputSchema,
+        execute: async (toolInput: unknown) => {
+          const workflowService = singletonServices.workflowService
+          if (!workflowService) {
+            throw new Error(
+              `workflowService is not configured — cannot run workflow tool '${workflowName}'`
+            )
+          }
+          const wire: PikkuRawWire = params.sessionService
+            ? { ...createMiddlewareSessionWireProps(params.sessionService) }
+            : {}
+          const rpcService = new ContextAwareRPCService(
+            singletonServices,
+            wire,
+            { sessionService: params.sessionService }
+          )
+          return workflowService.runToCompletion(
+            workflowName,
+            toolInput,
+            rpcService,
+            { wire: { type: 'internal' } }
+          )
+        },
+      })
+    }
+  }
+
+  // A tool's execute() can throw (bad input, RPC failure, DB error, ...). The AI
+  // SDK catches that at the tool-call boundary and turns it into a conversational
+  // "tool error" reply — without this, the exception never reaches pikku's own
+  // logger, so a failing tool is undiagnosable server-side. Log unconditionally,
+  // even when no aiMiddleware afterToolCall hook is registered to see it.
+  for (const tool of tools) {
+    const originalExecute = tool.execute
+    tool.execute = async (toolInput: unknown) => {
+      try {
+        return await originalExecute(toolInput)
+      } catch (err) {
+        singletonServices.logger.error(
+          `AI agent tool '${tool.name}' threw during execute()`,
+          err
+        )
+        throw err
+      }
+    }
+  }
+
   const hasToolHooks = aiMiddlewares?.some(
     (mw) => mw.beforeToolCall || mw.afterToolCall
   )
@@ -649,9 +827,15 @@ export async function prepareAgentRun(
     : undefined
 
   if (storage) {
+    let thread: Awaited<ReturnType<typeof storage.getThread>> | null = null
     try {
-      await storage.getThread(threadId)
+      thread = await storage.getThread(threadId)
     } catch {
+      thread = null
+    }
+    if (thread) {
+      assertResourceOwner(input.resourceId, thread.resourceId, 'thread')
+    } else {
       await storage.createThread(input.resourceId, { threadId })
     }
   }