@pikku/core 0.12.63 → 0.12.66

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

@@ -8,11 +8,14 @@ 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 { checkAuthPermissions, runPermissions } from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
+import { ForbiddenError } from '../../errors/errors.js'
+import { verifyScopes } from '../../scopes.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 +26,7 @@ import {
   resolveNamespace,
   ContextAwareRPCService,
 } from '../../wirings/rpc/rpc-runner.js'
+import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js'
 import {
   resolveMemoryServices,
   loadContextMessages,
@@ -36,10 +40,157 @@ 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}`)
+  }
+}
+
+/** A session's trusted principals, in the order they may be read as. */
+export function sessionPrincipals(
+  session: { userId?: string; orgId?: string } | undefined
+): string[] {
+  return [session?.userId, session?.orgId].filter(
+    (principal): principal is string => Boolean(principal)
+  )
+}
+
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export function isOwnedByPrincipal(
+  storedResourceId: string,
+  principal: string
+): boolean {
+  return (
+    storedResourceId === principal ||
+    storedResourceId.startsWith(`${principal}:`)
+  )
+}
+
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export function threadOwnerConstraint(
+  session: { userId?: string; orgId?: string } | undefined
+): string[] | undefined {
+  const principals = sessionPrincipals(session)
+  return principals.length > 0 ? principals : undefined
+}
+
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export function canAccessThread(
+  storedResourceId: string,
+  session: { userId?: string; orgId?: string } | undefined
+): boolean {
+  const principals = sessionPrincipals(session)
+  if (principals.length === 0) return true
+  return principals.some((principal) =>
+    isOwnedByPrincipal(storedResourceId, principal)
+  )
+}
+
 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
@@ -182,6 +333,56 @@ export const resolveAgent = (
   throw new Error(`AI agent not found: ${agentName}`)
 }
 
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export async function assertAgentAuthorized(
+  agent: CoreAIAgent,
+  params: RunAIAgentParams,
+  packageName: string | null
+): Promise<void> {
+  const session = params.sessionService
+    ? await params.sessionService.get()
+    : undefined
+
+  if (agent.auth === true && !session) {
+    throw new ForbiddenError('Authentication required')
+  }
+
+  verifyScopes(agent.scopes, session)
+
+  const singletonServices = getSingletonServices()
+  const wire = params.sessionService
+    ? createMiddlewareSessionWireProps(params.sessionService)
+    : { session: undefined }
+
+  await runPermissions({
+    funcPermissions: agent.permissions,
+    services: singletonServices as any,
+    wire: wire as any,
+    data: {},
+    packageName,
+    label: 'agent',
+  })
+}
+
 export async function buildInstructions(
   agentName: string,
   packageName: string | null
@@ -193,7 +394,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 +420,7 @@ export type ScopedChannel = AIStreamChannel & {
     toolCallId: string
     toolName: string
     args: unknown
+    reason?: string
     runId: string
   }>
 }
@@ -248,6 +450,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
@@ -333,11 +536,17 @@ export async function buildToolDefs(
         continue
       }
 
-      // Filter out tools the user doesn't have auth for
+      // Filter out tools the user doesn't have auth for. The `pikkuAuth` brand
+      // only survives on the live permission objects in the function config, so
+      // the check reads those rather than the metadata (whose by-name registry
+      // is never populated, which would let every gated tool through).
       if (fnMeta.permissions?.length) {
         if (!session) continue
+        const funcConfig = pikkuFuncId
+          ? pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId)
+          : undefined
         const allowed = await checkAuthPermissions(
-          fnMeta.permissions,
+          funcConfig?.permissions,
           session,
           singletonServices,
           resolvedPkg
@@ -373,17 +582,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)
           }
@@ -423,11 +642,13 @@ export async function buildToolDefs(
         continue
       }
 
-      // Filter out sub-agents the user doesn't have auth for
+      // Filter out sub-agents the user doesn't have auth for, reading the live
+      // agent config for the same reason the tool path does.
       if (subMeta.permissions?.length) {
         if (!session) continue
+        const subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName)
         const allowed = await checkAuthPermissions(
-          subMeta.permissions,
+          subAgent?.permissions,
           session,
           singletonServices
         )
@@ -437,6 +658,7 @@ export async function buildToolDefs(
       tools.push({
         name: subAgentName,
         description: subMeta.description,
+        forwardsApproval: true,
         inputSchema: {
           type: 'object',
           properties: {
@@ -502,6 +724,7 @@ export async function buildToolDefs(
             )
             if (subChannel.approvals.length > 0) {
               return {
+                [APPROVAL_REQUIRED]: true,
                 __approvalRequired: true,
                 toolName: subAgentName,
                 args: toolInput,
@@ -530,6 +753,7 @@ export async function buildToolDefs(
             result.pendingApprovals?.length
           ) {
             return {
+              [APPROVAL_REQUIRED]: true,
               __approvalRequired: true,
               toolName: subAgentName,
               args: toolInput,
@@ -538,6 +762,7 @@ export async function buildToolDefs(
                 toolCallId: a.toolCallId,
                 toolName: a.toolName,
                 args: a.args,
+                reason: a.reason,
                 runId: a.runId,
               })),
             }
@@ -548,6 +773,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
   )
@@ -618,6 +921,8 @@ export async function prepareAgentRun(
   const singletonServices = getSingletonServices()
   const { agent, packageName, resolvedName } = resolveAgent(agentName)
 
+  await assertAgentAuthorized(agent, params, packageName)
+
   let agentRunner = singletonServices.aiAgentRunner
   if (!agentRunner) {
     throw new AIProviderNotConfiguredError()
@@ -649,9 +954,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 })
     }
   }

package/src/wirings/ai-agent/ai-agent-resume-authorization.test.ts

@@ -0,0 +1,207 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  resetPikkuState,
+  pikkuState,
+  setSingletonServices,
+} from '../../pikku-state.js'
+import { resumeAIAgentSync } from './ai-agent-runner.js'
+import { resumeAIAgent } from './ai-agent-stream.js'
+import { clearPermissionsCache } from '../../permissions.js'
+import { ForbiddenError, MissingScopeError } from '../../errors/errors.js'
+import type { CoreAIAgent } from './ai-agent.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as any
+
+const RUN_ID = 'run-1'
+const TOOL_CALL_ID = 'tc-1'
+
+const suspendedRun = (agentName: string, resourceId: string) => ({
+  id: RUN_ID,
+  agentName,
+  resourceId,
+  threadId: 'thread-1',
+  status: 'suspended',
+  pendingApprovals: [
+    { toolCallId: TOOL_CALL_ID, toolName: 'refund', args: {}, runId: RUN_ID },
+  ],
+  messages: [],
+})
+
+const setup = (agentName: string, resourceId = 'u1') => {
+  const resolved: string[] = []
+  setSingletonServices({
+    logger,
+    aiRunState: {
+      getRun: async () => suspendedRun(agentName, resourceId),
+      resolveApproval: async (toolCallId: string) => {
+        resolved.push(toolCallId)
+      },
+    },
+  } as any)
+  return resolved
+}
+
+const addAgent = (
+  agentName: string,
+  overrides: Partial<CoreAIAgent> = {}
+): CoreAIAgent => {
+  const agent: CoreAIAgent = {
+    name: agentName,
+    description: `${agentName} description`,
+    goal: `${agentName} goal`,
+    model: 'test/test-model',
+    ...overrides,
+  } as CoreAIAgent
+
+  pikkuState(null, 'agent', 'agents').set(agentName, agent)
+  return agent
+}
+
+const sessionService = (session: CoreUserSession | undefined) =>
+  ({
+    get: () => session,
+    setInitial: () => {},
+    sessionChanged: false,
+  }) as any
+
+beforeEach(() => {
+  resetPikkuState()
+  clearPermissionsCache()
+})
+
+describe('resumeAIAgentSync authorization', () => {
+  test('rejects when the agent permissions deny', async () => {
+    const resolved = setup('denied-agent')
+    addAgent('denied-agent', {
+      permissions: { denied: async () => false },
+    } as Partial<CoreAIAgent>)
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          { sessionService: sessionService({ userId: 'u1' }) } as any
+        ),
+      ForbiddenError
+    )
+    assert.deepEqual(
+      resolved,
+      [],
+      'approvals must not be resolved when authorization fails'
+    )
+  })
+
+  test('rejects when a required scope is no longer held', async () => {
+    const resolved = setup('scoped-agent')
+    addAgent('scoped-agent', { scopes: ['admin:refund'] })
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['support'],
+            }),
+          } as any
+        ),
+      MissingScopeError
+    )
+    assert.deepEqual(resolved, [], 'a revoked scope must block resumption')
+  })
+
+  test('passes the gate when the session still holds the scope', async () => {
+    setup('scoped-agent-ok')
+    addAgent('scoped-agent-ok', { scopes: ['admin:refund'] })
+
+    // Gets past authorization and fails later on the unconfigured provider,
+    // which is how we know the gate admitted it.
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['admin:refund'],
+            }),
+          } as any
+        ),
+      (error: Error) =>
+        !(error instanceof ForbiddenError) &&
+        !(error instanceof MissingScopeError)
+    )
+  })
+
+  test('rejects when auth is required and the session is gone', async () => {
+    setup('auth-agent')
+    addAgent('auth-agent', { auth: true })
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          { sessionService: sessionService(undefined) } as any
+        ),
+      ForbiddenError
+    )
+  })
+})
+
+describe('resumeAIAgent (streaming) authorization', () => {
+  const channel = {
+    send: async () => {},
+    close: async () => {},
+  } as any
+
+  test('rejects when the agent permissions deny', async () => {
+    const resolved = setup('stream-denied')
+    addAgent('stream-denied', {
+      permissions: { denied: async () => false },
+    } as Partial<CoreAIAgent>)
+
+    await assert.rejects(
+      () =>
+        resumeAIAgent(
+          { runId: RUN_ID, toolCallId: TOOL_CALL_ID, approved: true },
+          channel,
+          { sessionService: sessionService({ userId: 'u1' }) } as any
+        ),
+      ForbiddenError
+    )
+    assert.deepEqual(resolved, [])
+  })
+
+  test('rejects when a required scope is no longer held', async () => {
+    setup('stream-scoped')
+    addAgent('stream-scoped', { scopes: ['admin:refund'] })
+
+    await assert.rejects(
+      () =>
+        resumeAIAgent(
+          { runId: RUN_ID, toolCallId: TOOL_CALL_ID, approved: true },
+          channel,
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['support'],
+            }),
+          } as any
+        ),
+      MissingScopeError
+    )
+  })
+})