@pikku/core 0.12.82 → 0.12.84

package/src/wirings/rpc/rpc-runner.ts

@@ -13,7 +13,7 @@ import { PikkuError, addError } from '../../errors/error-handler.js'
 import type { PikkuRPC, ResolvedFunction } from './rpc-types.js'
 import { parseVersionedId } from '../../version.js'
 import { resolveRemoteAddonToken } from './remote-addon-auth.js'
-import { createAgentRPC } from '../ai-agent/agent-rpc.js'
+import { createAgentRPC } from '../agent/agent-rpc.js'
 
 /**
  * The session for a wire: read through `getSession` when a runner attached one,
@@ -284,6 +284,8 @@ export class ContextAwareRPCService {
         secretOverrides: resolved.addonConfig?.secretOverrides,
         variableOverrides: resolved.addonConfig?.variableOverrides,
         credentialOverrides: resolved.addonConfig?.credentialOverrides,
+        secretGrants: resolved.addonConfig?.secretGrants,
+        credentialGrants: resolved.addonConfig?.credentialGrants,
         globalSecrets: resolved.addonConfig?.globalSecrets,
         globalCredentials: resolved.addonConfig?.globalCredentials,
       },
@@ -459,7 +461,7 @@ export class ContextAwareRPCService {
   /**
    * The agent facade, built on access.
    *
-   * The implementation lives in `ai-agent/agent-rpc.ts` so the agent surface is
+   * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
    * one file rather than a wing of this one; a getter rather than a field so a
    * request that never touches an agent never builds it.
    */

package/src/wirings/rpc/rpc-types.ts

@@ -1,5 +1,5 @@
 import type { PikkuRawWire } from '../../types/core.types.js'
-import type { AgentInterruptResult } from '../ai-agent/ai-agent-interrupt.js'
+import type { AgentInterruptResult } from '../agent/agent-interrupt.js'
 
 export type PikkuRPC<
   Invoke extends (...args: any[]) => any = (...args: any[]) => any,
@@ -67,6 +67,10 @@ export interface ResolvedFunction {
     secretOverrides?: Record<string, string>
     variableOverrides?: Record<string, string>
     credentialOverrides?: Record<string, string>
+    /** Set by the consuming app: secrets it lends this instance, as the addon names them */
+    secretGrants?: string[]
+    /** Set by the consuming app: credentials it lends this instance, as the addon names them */
+    credentialGrants?: string[]
     /** Set by the consuming app: hand this instance the unscoped `SecretService` */
     globalSecrets?: string
     /** Set by the consuming app: hand this instance the unscoped `CredentialService` */

package/src/wirings/rpc/wire-addon.ts

@@ -14,6 +14,18 @@ export type WireAddonConfig = {
   secretOverrides?: Record<string, string>
   variableOverrides?: Record<string, string>
   credentialOverrides?: Record<string, string>
+  /**
+   * Secrets this instance may read on top of the ones it declared, named as the
+   * addon reads them — the scope check runs before `secretOverrides` renames
+   * them, so an overridden secret is named here by its addon-side key. Listing
+   * one in `secretOverrides` grants it too.
+   *
+   * For an addon whose secret names come off its input rather than its own
+   * source, this is how the host lends names the addon could not declare.
+   */
+  secretGrants?: string[]
+  /** Credentials this instance may read on top of the ones it declared. */
+  credentialGrants?: string[]
   /**
    * Hands this instance the whole `SecretService` instead of one scoped to the
    * secrets it declared. The value is the reason, recorded in the deploy
@@ -45,6 +57,10 @@ export const wireAddon = (config: WireAddonConfig): void => {
     ...(config.credentialOverrides
       ? { credentialOverrides: config.credentialOverrides }
       : {}),
+    ...(config.secretGrants ? { secretGrants: config.secretGrants } : {}),
+    ...(config.credentialGrants
+      ? { credentialGrants: config.credentialGrants }
+      : {}),
     ...(config.globalSecrets ? { globalSecrets: config.globalSecrets } : {}),
     ...(config.globalCredentials
       ? { globalCredentials: config.globalCredentials }

package/src/wirings/virtual-user/prepare-virtual-user-run.ts

@@ -87,7 +87,7 @@ export const prepareVirtualUserRun = (input: {
   const scopes = personaScopes(input.persona, roleScopes)
 
   // Gated by the same scopes as the RPCs, because an agent is reached rather
-  // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+  // than declared: `CoreAgent.scopes` is checked against the session, so a
   // persona finds the specialists its roles unlock and no others.
   const agents = reachableAgents(input.agentsMeta ?? {}, scopes)
 

package/src/wirings/virtual-user/run-virtual-user.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 
 import { rememberIds, runVirtualUser } from './run-virtual-user.js'
 import type { ActorLLM } from '../actor-flow/run-conversation.js'
-import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+import type { AgentStepResult } from '../../services/agent-runner-service.js'
 import type { ScenarioHttpResponse } from '../../services/personas-service.js'
 import type {
   ApiCatalogueEntry,
@@ -83,7 +83,7 @@ const scripted = (
       toolResults: [],
       usage: { inputTokens: 10, outputTokens: 4 },
       finishReason: 'stop',
-    } satisfies AIAgentStepResult
+    } satisfies AgentStepResult
   }
   return { llm, turns: () => turn }
 }

package/src/wirings/virtual-user/run-virtual-user.ts

@@ -1,5 +1,5 @@
 import type { ResolvedPersona } from '../../services/personas-service.js'
-import type { AIMessage } from '../ai-agent/ai-agent.types.js'
+import type { AgentMessage } from '../agent/agent.types.js'
 import type { ActorLLM } from '../actor-flow/run-conversation.js'
 import { getDurationInMilliseconds } from '../../time-utils.js'
 import {
@@ -135,7 +135,7 @@ export interface RunVirtualUserParams {
   maxStepsPerIntent?: number
 }
 
-const msg = (role: AIMessage['role'], content: string): AIMessage => ({
+const msg = (role: AgentMessage['role'], content: string): AgentMessage => ({
   id: globalThis.crypto.randomUUID(),
   role,
   content,
@@ -318,7 +318,7 @@ export const runVirtualUser = async (
   const described = new Set<string>()
   const findings: VirtualUserFinding[] = []
   const steps: StepRecord[] = []
-  const history = new Map<string, AIMessage[]>()
+  const history = new Map<string, AgentMessage[]>()
 
   const tally: VirtualUserTally = {
     steps: 0,

package/src/wirings/virtual-user/virtual-user-agents.ts

@@ -4,7 +4,7 @@ import { hasScopes } from '../../scopes.js'
  * Which of the product's agents a persona can actually talk to.
  *
  * An agent is not something a persona declares. It is something a persona
- * *reaches*, under exactly the rule an RPC is reached by: `CoreAIAgent.scopes`
+ * *reaches*, under exactly the rule an RPC is reached by: `CoreAgent.scopes`
  * is checked against the session, so a persona holding the scopes an agent
  * requires finds it in front of them, and one that does not, does not.
  *

package/src/wirings/workflow/feature.ts

@@ -1,9 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
-import type {
-  CoreFeature,
-  CoreWorkflow,
-  FeaturePlanEntry,
-} from './workflow.types.js'
+import type { CoreWorkflow } from './workflow.types.js'
+import type { CoreFeature, FeaturePlanEntry } from './scenario.types.js'
 
 export const addFeature = (
   featureId: string,

package/src/wirings/workflow/index.ts

@@ -28,13 +28,9 @@ export {
   reconstructStateAt,
   reconstructFinalState,
 } from './run-timeline.js'
-export type {
-  RunTimeline,
-  ReconstructedRunState,
-} from './run-timeline.js'
+export type { RunTimeline, ReconstructedRunState } from './run-timeline.js'
 
 export { addWorkflow } from './dsl/workflow-runner.js'
-export { addFeature, resolveFeatureScenarios } from './feature.js'
 
 export { template, type TemplateString } from './graph/template.js'
 export {
@@ -63,10 +59,6 @@ export type {
   WorkflowRunService,
   WorkflowRunMirror,
   CoreWorkflow,
-  CoreFeature,
-  FeatureMeta,
-  FeaturesMeta,
-  FeaturePlanEntry,
   PikkuWorkflow,
   ContextVariable,
   WorkflowContext,
@@ -97,47 +89,7 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuScenarioWire,
 } from './workflow.types.js'
-
-export type {
-  ScenarioStepPhase,
-  ScenarioStepKind,
-  ScenarioStepOptions,
-  PikkuScenarioStepWire,
-  ScenarioEnvironment,
-  ScenarioSurface,
-  ScenarioSurfaceResolution,
-} from './scenario-step.types.js'
-export { SCENARIO_SURFACES } from './scenario-step.types.js'
-
-// Which of a step's bindings run: one for an action, every witness for a `then`
-export { resolveScenarioSurfaces } from './scenario-surface.js'
-
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
-
-export { pollUntil, type PollOptions } from './scenario-poll.js'
-
-export { createCookieJar } from './scenario-cookie-jar.js'
-export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
-
-export type {
-  ScenarioHttpResponse,
-  ScenarioJsonRequest,
-} from '../../services/personas-service.js'
-// The readers themselves live on `@pikku/core/persona`; workflow is a production
-// wiring and must not pull scenario runtime in behind it.
-
-export type {
-  PikkuBrowserWire,
-  TestIdSelector,
-  ScenarioBrowserProvider,
-  ScenarioBrowserFailure,
-} from './scenario-step.types.js'
-
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js'

package/src/wirings/workflow/pikku-scenario-service.ts

@@ -27,10 +27,10 @@ import type {
 } from './scenario-step.types.js'
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
 import type {
-  PikkuScenarioWire,
   PikkuWorkflowWire,
   WorkflowQueueOptions,
 } from './workflow.types.js'
+import type { PikkuScenarioWire } from './scenario.types.js'
 import type {
   WorkflowExpectEventuallyOptions,
   WorkflowExpectErrorOptions,
@@ -38,6 +38,26 @@ import type {
   WorkflowExpectServiceOptions,
 } from './dsl/workflow-dsl.types.js'
 
+export { addFeature, resolveFeatureScenarios } from './feature.js'
+export type * from './scenario.types.js'
+export { SCENARIO_SURFACES } from './scenario-step.types.js'
+
+// Which of a step's bindings run: one for an action, every witness for a `then`
+export { resolveScenarioSurfaces } from './scenario-surface.js'
+
+export { pollUntil, type PollOptions } from './scenario-poll.js'
+export { createCookieJar } from './scenario-cookie-jar.js'
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js'
+
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
+
+export type {
+  ScenarioHttpResponse,
+  ScenarioJsonRequest,
+} from '../../services/personas-service.js'
+// The readers themselves live on `@pikku/core/persona`
+
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the

package/src/wirings/workflow/run-timeline.ts

@@ -17,7 +17,7 @@ export interface RunTimelineEvent {
 
 export type RunTimeline = RunTimelineEvent[]
 
-type HistoryEntry = StepState & { stepName: string }
+export type HistoryEntry = StepState & { stepName: string }
 
 const LIFECYCLE_ORDER: Record<RunTimelineEvent['type'], number> = {
   pending: 0,

package/src/wirings/workflow/scenario.types.ts

@@ -0,0 +1,63 @@
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
+} from '../../function/functions.types.js'
+
+export type {
+  ScenarioStepInvocation,
+  ScenarioStepMeta,
+  PikkuScenarioWire,
+} from './dsl/workflow-dsl.types.js'
+
+export type {
+  ScenarioStepPhase,
+  ScenarioStepKind,
+  ScenarioStepOptions,
+  PikkuScenarioStepWire,
+  ScenarioEnvironment,
+  ScenarioSurface,
+  ScenarioSurfaceResolution,
+  PikkuBrowserWire,
+  TestIdSelector,
+  ScenarioBrowserProvider,
+  ScenarioBrowserFailure,
+} from './scenario-step.types.js'
+
+export type CoreFeatureScenario =
+  | CorePikkuFunctionConfig<any, any, any>
+  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
+
+export type CoreFeature = {
+  name: string
+  description?: string
+  tags?: string[]
+  scenarios: readonly CoreFeatureScenario[]
+  before?: CorePikkuFunctionHook
+  after?: CorePikkuFunctionHook
+}
+
+export type FeatureMetaEntry = {
+  scenario: string
+  data?: unknown
+}
+
+export type FeatureMeta = {
+  id: string
+  name: string
+  description?: string
+  tags: string[]
+  entries: FeatureMetaEntry[]
+  unresolvedEntries: number
+  hasBefore: boolean
+  hasAfter: boolean
+}
+
+export type FeaturesMeta = Record<string, FeatureMeta>
+
+export type FeaturePlanEntry = {
+  featureId: string
+  featureName: string
+  scenarioName: string
+  data?: unknown
+  tags: string[]
+}

package/src/wirings/workflow/workflow.types.ts

@@ -1,8 +1,5 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionHook,
-} from '../../function/functions.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
 
 export type { WorkflowService } from '../../services/workflow-service.js'
@@ -30,22 +27,11 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuScenarioWire,
 } from './dsl/workflow-dsl.types.js'
 
-export type {
-  ScenarioStepPhase,
-  ScenarioStepOptions,
-  PikkuScenarioStepWire,
-  PikkuBrowserWire,
-  ScenarioBrowserProvider,
-} from './scenario-step.types.js'
-
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
 
 export interface WorkflowRunWire {
@@ -238,45 +224,6 @@ export type CoreWorkflow<
   tags?: string[]
 }
 
-export type CoreFeatureScenario =
-  | CorePikkuFunctionConfig<any, any, any>
-  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
-
-export type CoreFeature = {
-  name: string
-  description?: string
-  tags?: string[]
-  scenarios: readonly CoreFeatureScenario[]
-  before?: CorePikkuFunctionHook
-  after?: CorePikkuFunctionHook
-}
-
-export type FeatureMetaEntry = {
-  scenario: string
-  data?: unknown
-}
-
-export type FeatureMeta = {
-  id: string
-  name: string
-  description?: string
-  tags: string[]
-  entries: FeatureMetaEntry[]
-  unresolvedEntries: number
-  hasBefore: boolean
-  hasAfter: boolean
-}
-
-export type FeaturesMeta = Record<string, FeatureMeta>
-
-export type FeaturePlanEntry = {
-  featureId: string
-  featureName: string
-  scenarioName: string
-  data?: unknown
-  tags: string[]
-}
-
 export interface PikkuWorkflow {
   start: <I>(input: I) => Promise<{ runId: string }>
   getRun: (runId: string) => Promise<WorkflowRun>

package/src/wirings-stay-decoupled.test.ts

@@ -26,12 +26,12 @@ const ALLOWED: Record<string, string[]> = {
   cli: ['channel'],
   // An agent streams over a channel and is invoked over rpc, and grades itself
   // as the last thing a finished run does.
-  'ai-agent': ['channel', 'rpc', 'ai-scorer'],
+  agent: ['channel', 'rpc', 'agent-scorer'],
   // A judge is a degenerate agent — it builds agent messages and runs them —
   // and a grade is dispatched to a queue.
-  'ai-scorer': ['ai-agent', 'queue'],
+  'agent-scorer': ['agent', 'queue'],
   // `wire.rpc.agent` — the facade lives with the agent runtime it delegates to.
-  rpc: ['ai-agent'],
+  rpc: ['agent'],
   gateway: ['http'],
   mcp: ['rpc'],
   trigger: ['rpc'],