@pikku/core 0.12.82 → 0.12.84

package/src/services/http-personas.ts

@@ -43,7 +43,7 @@ export interface HttpPersonasConfig {
   /**
    * Default model a persona thinks with when `converse(...)` is called without
    * an explicit `model`. Its own turns/approvals/evaluation run in-process via
-   * the configured `aiAgentRunner`.
+   * the configured `agentRunner`.
    */
   model?: string
 }
@@ -107,8 +107,8 @@ export class HttpPersona implements ScenarioPersona {
   }
 
   async converse(options: ConverseOptions): Promise<ActorFlowVerdict> {
-    const { aiAgentRunner } = getSingletonServices()
-    if (!aiAgentRunner) {
+    const { agentRunner } = getSingletonServices()
+    if (!agentRunner) {
       throw new AIProviderNotConfiguredError()
     }
     const model = options.model ?? this.config.model
@@ -129,7 +129,7 @@ export class HttpPersona implements ScenarioPersona {
       approvals: options.approvals,
       model,
       maxTurns: options.maxTurns,
-      llm: (params) => aiAgentRunner.run(params),
+      llm: (params) => agentRunner.run(params),
       target: {
         run: (message) =>
           this.agentRun(options.agent, message, threadId, resourceId),

package/src/services/{in-memory-ai-run-state-service.ts → in-memory-agent-run-state-service.ts}

@@ -1,17 +1,17 @@
 import type {
-  AIRunStateService,
+  AgentRunStateService,
   CreateRunInput,
   SaveScoreInput,
-} from './ai-run-state-service.js'
+} from './agent-run-state-service.js'
 import type {
   AgentRunState,
   PendingApproval,
-} from '../wirings/ai-agent/ai-agent.types.js'
-import type { AIRunScore } from '../wirings/ai-scorer/ai-scorer.types.js'
+} from '../wirings/agent/agent.types.js'
+import type { AgentRunScore } from '../wirings/agent-scorer/agent-scorer.types.js'
 
-export class InMemoryAIRunStateService implements AIRunStateService {
+export class InMemoryAgentRunStateService implements AgentRunStateService {
   private runs = new Map<string, AgentRunState>()
-  private scores = new Map<string, AIRunScore[]>()
+  private scores = new Map<string, AgentRunScore[]>()
   private counter = 0
 
   async createRun(run: CreateRunInput): Promise<string> {
@@ -81,7 +81,7 @@ export class InMemoryAIRunStateService implements AIRunStateService {
     this.scores.set(score.runId, existing)
   }
 
-  async getScores(runId: string): Promise<AIRunScore[]> {
+  async getScores(runId: string): Promise<AgentRunScore[]> {
     return [...(this.scores.get(runId) ?? [])]
   }
 }

package/src/services/index.ts

@@ -6,9 +6,7 @@ export {
   createMiddlewareSessionWireProps,
 } from './user-session-service.js'
 export { TypedSecretService } from './typed-secret-service.js'
-export {
-  PikkuCredentialWireService,
-} from './credential-wire-service.js'
+export { PikkuCredentialWireService } from './credential-wire-service.js'
 export { TypedVariablesService } from './typed-variables-service.js'
 export { LocalSecretService } from './local-secrets.js'
 export { LocalEmailService } from './local-email-service.js'
@@ -22,7 +20,7 @@ export {
 } from './queue-webhook-service.js'
 export { InMemoryQueueService } from './in-memory-queue-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
-export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
+export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js'
 export { LocalGatewayService } from './local-gateway-service.js'
 export type {
   ContentService,
@@ -38,10 +36,8 @@ export type {
   ScenarioPersona,
   ResolvedPersona,
   ScenarioPersonas,
-  ScenarioHttpResponse,
 } from './personas-service.js'
 // knowledge: decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md
-export type { HttpPersonasConfig } from './http-personas.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,
@@ -81,36 +77,29 @@ export type {
   DeploymentInfo,
   DeploymentServiceConfig,
 } from './deployment-service.js'
-export type { AIStorageService } from './ai-storage-service.js'
+export type { AgentStorageService } from './agent-storage-service.js'
 export type {
-  AIAgentRunnerParams,
-  AIAgentRunnerResult,
-  AIAgentStepResult,
-  AIAgentRunnerService,
-} from './ai-agent-runner-service.js'
+  AgentRunnerParams,
+  AgentRunnerResult,
+  AgentStepResult,
+  AgentRunnerService,
+} from './agent-runner-service.js'
 export type { AIEmbeddingService } from './ai-embedding-service.js'
 export type {
   CreateRunInput,
   SaveScoreInput,
-  AIRunStateService,
-} from './ai-run-state-service.js'
-export type {
-  CredentialMeta,
-} from './typed-secret-service.js'
+  AgentRunStateService,
+} from './agent-run-state-service.js'
+export type { CredentialMeta } from './typed-secret-service.js'
 export type { CredentialService } from './credential-service.js'
 export { TypedCredentialService } from './typed-credential-service.js'
-export type {
-  CredentialMetaInfo,
-} from './typed-credential-service.js'
+export type { CredentialMetaInfo } from './typed-credential-service.js'
 export type { VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
 export type { ScopeService, Role } from './scope-service.js'
 export type { IsSystemRole } from './system-role-guard.js'
-export {
-  NoopAuditService,
-  createInvocationAudit,
-} from './audit-service.js'
+export { NoopAuditService, createInvocationAudit } from './audit-service.js'
 export type {
   AuditConfig,
   AuditDurability,

package/src/services/meta-service.ts

@@ -13,10 +13,8 @@ import type {
   MCPToolMeta,
   MCPPromptMeta,
 } from '../wirings/mcp/mcp.types.js'
-import type {
-  FeaturesMeta,
-  WorkflowsMeta,
-} from '../wirings/workflow/workflow.types.js'
+import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js'
+import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js'
 import type { ResolvedPersona } from './personas-service.js'
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js'
 import type {
@@ -32,7 +30,7 @@ import type {
   MiddlewareMetadata,
   PermissionMetadata,
 } from '../types/core.types.js'
-import type { AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AgentsMeta } from '../wirings/agent/agent.types.js'
 import type { GatewaysMeta } from '../wirings/gateway/gateway.types.js'
 
 export type {
@@ -41,8 +39,8 @@ export type {
   MiddlewareMetadata as MiddlewareMeta,
   PermissionMetadata as PermissionMeta,
 }
-export type AgentsMeta = AIAgentMeta
-export type AgentMeta = AIAgentMeta[string]
+export type { AgentsMeta }
+export type AgentMeta = AgentsMeta[string]
 
 export interface MCPMeta {
   resources: MCPResourceMeta

package/src/testing/service-tests/agent-run-service-tests.ts

@@ -1,7 +1,7 @@
 import { describe, test, before } from 'node:test'
 import assert from 'node:assert/strict'
 
-import type { AgentRunService } from '../../wirings/ai-agent/ai-agent.types.js'
+import type { AgentRunService } from '../../wirings/agent/agent.types.js'
 import type { ServiceTestConfig } from '../service-tests.js'
 
 /** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
@@ -16,7 +16,7 @@ export const defineAgentRunServiceTests = (
    * only runs when a backend supplies both. Passed explicitly rather than
    * closed over, so the dependency is visible in the signature.
    */
-  aiStorageService?: ServiceTestConfig['services']['aiStorageService']
+  agentStorageService?: ServiceTestConfig['services']['agentStorageService']
 ): void => {
   const factory = agentRunService
   describe(`AgentRunService [${name}]`, () => {
@@ -31,8 +31,8 @@ export const defineAgentRunServiceTests = (
       assert.ok(Array.isArray(threads))
     })
 
-    if (aiStorageService) {
-      const storageFactory = aiStorageService
+    if (agentStorageService) {
+      const storageFactory = agentStorageService
 
       // The `owners` constraint is what keeps the generated thread-management
       // functions from leaking across tenants: a caller may only list threads

package/src/testing/service-tests/{ai-storage-service-tests.ts → agent-storage-service-tests.ts}

@@ -1,20 +1,20 @@
 import { describe, test, before } from 'node:test'
 import assert from 'node:assert/strict'
 
-import type { AIStorageService } from '../../services/ai-storage-service.js'
-import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+import type { AgentStorageService } from '../../services/agent-storage-service.js'
+import type { AgentRunStateService } from '../../services/agent-run-state-service.js'
 import type { ServiceTestConfig } from '../service-tests.js'
 
-/** Conformance suite for `aiStorageService`. Runs only when a backend supplies one. */
+/** Conformance suite for `agentStorageService`. Runs only when a backend supplies one. */
 export const defineAiStorageServiceTests = (
   name: string,
-  aiStorageService: NonNullable<
-    ServiceTestConfig['services']['aiStorageService']
+  agentStorageService: NonNullable<
+    ServiceTestConfig['services']['agentStorageService']
   >
 ): void => {
-  const factory = aiStorageService
-  describe(`AIStorageService [${name}]`, () => {
-    let storage: AIStorageService & AIRunStateService
+  const factory = agentStorageService
+  describe(`AgentStorageService [${name}]`, () => {
+    let storage: AgentStorageService & AgentRunStateService
 
     before(async () => {
       storage = await factory()

package/src/testing/service-tests.ts

@@ -3,11 +3,11 @@ import type { EventHubStore } from '../wirings/channel/eventhub-store.js'
 import type { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js'
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { DeploymentService } from '../services/deployment-service.js'
-import type { AIStorageService } from '../services/ai-storage-service.js'
-import type { AIRunStateService } from '../services/ai-run-state-service.js'
+import type { AgentStorageService } from '../services/agent-storage-service.js'
+import type { AgentRunStateService } from '../services/agent-run-state-service.js'
 import type { SecretService } from '../services/secret-service.js'
 import type { CredentialService } from '../services/credential-service.js'
-import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AgentRunService } from '../wirings/agent/agent.types.js'
 import type { SessionStore } from '../services/session-store.js'
 
 export interface ServiceTestConfig {
@@ -20,7 +20,9 @@ export interface ServiceTestConfig {
     deploymentService?: () => Promise<
       DeploymentService & { stop(): Promise<void> }
     >
-    aiStorageService?: () => Promise<AIStorageService & AIRunStateService>
+    agentStorageService?: () => Promise<
+      AgentStorageService & AgentRunStateService
+    >
     agentRunService?: () => Promise<AgentRunService>
     secretService?: (config: {
       key: string
@@ -40,7 +42,7 @@ import { defineChannelStoreTests } from './service-tests/channel-store-tests.js'
 import { defineEventHubStoreTests } from './service-tests/event-hub-store-tests.js'
 import { defineWorkflowServiceTests } from './service-tests/workflow-service-tests.js'
 import { defineWorkflowRunServiceTests } from './service-tests/workflow-run-service-tests.js'
-import { defineAiStorageServiceTests } from './service-tests/ai-storage-service-tests.js'
+import { defineAiStorageServiceTests } from './service-tests/agent-storage-service-tests.js'
 import { defineDeploymentServiceTests } from './service-tests/deployment-service-tests.js'
 import { defineSecretServiceTests } from './service-tests/secret-service-tests.js'
 import { defineCredentialServiceTests } from './service-tests/credential-service-tests.js'
@@ -68,8 +70,8 @@ export function defineServiceTests(config: ServiceTestConfig): void {
   if (services.workflowRunService) {
     defineWorkflowRunServiceTests(name, services.workflowRunService)
   }
-  if (services.aiStorageService) {
-    defineAiStorageServiceTests(name, services.aiStorageService)
+  if (services.agentStorageService) {
+    defineAiStorageServiceTests(name, services.agentStorageService)
   }
   if (services.deploymentService) {
     defineDeploymentServiceTests(name, services.deploymentService)
@@ -84,7 +86,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
     defineAgentRunServiceTests(
       name,
       services.agentRunService,
-      services.aiStorageService
+      services.agentStorageService
     )
   }
   if (services.sessionStore) {

package/src/types/core.types.ts

@@ -17,11 +17,11 @@ import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
 import type { PikkuCLI } from '../wirings/cli/cli.types.js'
 import type {
   PikkuWorkflowWire,
-  PikkuScenarioWire,
   WorkflowService,
   WorkflowServiceConfig,
   WorkflowStepWire,
 } from '../wirings/workflow/workflow.types.js'
+import type { PikkuScenarioWire } from '../wirings/workflow/scenario.types.js'
 import type {
   PikkuBrowserWire,
   PikkuScenarioStepWire,
@@ -33,19 +33,19 @@ import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
 import type { PikkuGateway } from '../wirings/gateway/gateway.types.js'
 import type { SchedulerService } from '../services/scheduler-service.js'
 import type { DeploymentService } from '../services/deployment-service.js'
-import type { AIStorageService } from '../services/ai-storage-service.js'
+import type { AgentStorageService } from '../services/agent-storage-service.js'
 
 import type { ContentService } from '../services/content-service.js'
 import type {
   ScenarioPersonaOf,
   ScenarioPersonas,
 } from '../services/personas-service.js'
-import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
+import type { AgentRunnerService } from '../services/agent-runner-service.js'
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js'
-import type { AIRunStateService } from '../services/ai-run-state-service.js'
-import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AgentRunStateService } from '../services/agent-run-state-service.js'
+import type { AgentRunService } from '../wirings/agent/agent.types.js'
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js'
-import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
+import type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
@@ -325,12 +325,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   eventHub?: EventHubService<Record<string, any>>
   schedulerService?: SchedulerService
   deploymentService?: DeploymentService
-  aiStorage?: AIStorageService
+  agentStorage?: AgentStorageService
 
   content?: ContentService
-  aiAgentRunner?: AIAgentRunnerService
+  agentRunner?: AgentRunnerService
   aiEmbedding?: AIEmbeddingService
-  aiRunState?: AIRunStateService
+  agentRunState?: AgentRunStateService
   agentRunService?: AgentRunService
   workflowRunService?: WorkflowRunService
   credentialService?: CredentialService
@@ -547,14 +547,14 @@ export const pikkuChannelMiddlewareFactory = <In = any>(
   return factory
 }
 
-export type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
+export type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'
 
-export const pikkuAIMiddleware = <
+export const pikkuAgentMiddleware = <
   State extends Record<string, unknown> = Record<string, unknown>,
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
 >(
-  hooks: PikkuAIMiddlewareHooks<State, SingletonServices>
-): PikkuAIMiddlewareHooks<State, SingletonServices> => hooks
+  hooks: PikkuAgentMiddlewareHooks<State, SingletonServices>
+): PikkuAgentMiddlewareHooks<State, SingletonServices> => hooks
 
 export type CoreServices<SingletonServices = CoreSingletonServices> =
   SingletonServices

package/src/types/state.types.ts

@@ -25,14 +25,11 @@ import type {
   CoreMCPPrompt,
   MCPPromptMeta,
 } from '../wirings/mcp/mcp.types.js'
+import type { CoreAgent, AgentsMeta } from '../wirings/agent/agent.types.js'
 import type {
-  CoreAIAgent,
-  AIAgentMeta,
-} from '../wirings/ai-agent/ai-agent.types.js'
-import type {
-  PikkuAIScorer,
+  PikkuAgentScorer,
   ScorerMeta,
-} from '../wirings/ai-scorer/ai-scorer.types.js'
+} from '../wirings/agent-scorer/agent-scorer.types.js'
 import type {
   CoreGateway,
   GatewaysMeta,
@@ -47,9 +44,9 @@ import type {
 } from '../wirings/scheduler/scheduler.types.js'
 import type {
   CoreWorkflow,
-  CoreFeature,
   WorkflowsRuntimeMeta,
 } from '../wirings/workflow/workflow.types.js'
+import type { CoreFeature } from '../wirings/workflow/scenario.types.js'
 import type {
   CoreTrigger,
   CoreTriggerSource,
@@ -102,6 +99,10 @@ export interface PikkuPackageState {
         variableOverrides?: Record<string, string>
         /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
         credentialOverrides?: Record<string, string>
+        /** Secrets the host lends this instance, named as the addon reads them */
+        secretGrants?: string[]
+        /** Credentials the host lends this instance, named as the addon reads them */
+        credentialGrants?: string[]
         /** Why this instance gets the whole `SecretService` rather than one scoped to its declared secrets */
         globalSecrets?: string
         /** Why this instance gets the whole `CredentialService` rather than one scoped to its declared credentials */
@@ -159,9 +160,9 @@ export interface PikkuPackageState {
     promptsMeta: MCPPromptMeta
   }
   agent: {
-    agents: Map<string, CoreAIAgent>
-    agentsMeta: AIAgentMeta
-    scorers: Map<string, PikkuAIScorer>
+    agents: Map<string, CoreAgent>
+    agentsMeta: AgentsMeta
+    scorers: Map<string, PikkuAgentScorer>
     scorersMeta: ScorerMeta
     /** Alias -> `provider/model`, from the `models` table in pikku.config.json. */
     modelAliases: Record<string, string>

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

@@ -7,9 +7,9 @@ import type {
   TargetAgentReply,
   ActorFlowApprovalPolicy,
 } from './actor-flow.types.js'
-import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+import type { AgentStepResult } from '../../services/agent-runner-service.js'
 
-const stepResult = (object: unknown): AIAgentStepResult => ({
+const stepResult = (object: unknown): AgentStepResult => ({
   text: '',
   object,
   toolCalls: [],

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

@@ -5,11 +5,11 @@ import type {
   TargetPendingApproval,
 } from './actor-flow.types.js'
 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 {
-  AIAgentRunnerParams,
-  AIAgentStepResult,
-} from '../../services/ai-agent-runner-service.js'
+  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 = {
@@ -56,9 +56,7 @@ 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: AIAgentRunnerParams
-) => Promise<AIAgentStepResult>
+export type ActorLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>
 
 export interface RunConversationParams {
   /** The person being played — name, job title, personality. */
@@ -85,7 +83,7 @@ export interface RunConversationParams {
   agentName: string
 }
 
-function msg(role: AIMessage['role'], content: string): AIMessage {
+function msg(role: AgentMessage['role'], content: string): AgentMessage {
   return {
     id: globalThis.crypto.randomUUID(),
     role,
@@ -221,7 +219,7 @@ export async function runConversation(
   // 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: AIMessage[] = [
+  const actorMessages: AgentMessage[] = [
     msg(
       'user',
       'Begin the conversation now — send your first message to the assistant to work towards your goal.'