@pikku/addon-execution 0.2.0

package/.pikku/addon/pikku-addon-types.gen.ts

@@ -0,0 +1,105 @@
+/**
+ * This file was generated by @pikku/cli@0.12.55
+ */
+/**
+ * Addon package types for pikkuAddonConfig and pikkuAddonServices
+ */
+
+import type { CreateConfig, PikkuWire } from '@pikku/core'
+import type { SingletonServices } from '../../types/application-types.d.js'
+import type { Config } from '../../types/application-types.d.js'
+import type { RequiredSingletonServices } from '../pikku-services.gen.js'
+import { TypedSecretService } from '../secrets/pikku-secrets.gen.js'
+import { TypedVariablesService } from '../variables/pikku-variables.gen.js'
+
+
+
+
+
+/**
+ * Base services provided to addon package service factories.
+ * These are always available from the parent application.
+ */
+export type AddonBaseServices = {
+  logger: SingletonServices['logger']
+  variables: TypedVariablesService
+  secrets: TypedSecretService
+}
+
+/**
+ * Creates a Pikku config factory for addon packages.
+ * Unlike pikkuConfig, this receives AddonBaseServices (logger, variables, secrets)
+ * from the parent application, so addon packages can read variables/secrets during config creation.
+ */
+export const pikkuAddonConfig = <ExistingServices extends Omit<Partial<SingletonServices>, 'variables' | 'secrets'> & AddonBaseServices>(
+  func: (services: ExistingServices) => Promise<Config>
+): CreateConfig<Config> => {
+  return (async (_variables: any, existingServices?: Partial<SingletonServices>): Promise<Config> => {
+    const { secrets, variables, ...rest } = (existingServices ?? {}) as unknown as SingletonServices
+    return func({ ...rest, secrets: new TypedSecretService(secrets), variables: new TypedVariablesService(variables) } as ExistingServices)
+  }) as unknown as CreateConfig<Config>
+}
+
+/**
+ * Creates a Pikku singleton services factory for addon packages.
+ * Unlike pikkuServices, this expects the parent application to provide
+ * logger, variables, and secrets - no fallbacks needed.
+ *
+ * @param func - Addon services factory function that receives config and base services
+ * @returns The singleton services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createSingletonServices = pikkuAddonServices(async (
+ *   config,
+ *   { secrets }
+ * ) => {
+ *   const creds = await secrets.getSecret<GithubCredentials>('GITHUB_CREDENTIALS')
+ *   const github = new GithubService(creds)
+ *   return { github }
+ * })
+ * ```
+ */
+export const pikkuAddonServices = <T extends Record<string, any>, ExistingServices extends Omit<Partial<SingletonServices>, 'variables' | 'secrets'> & AddonBaseServices>(
+  func: (config: Config, services: ExistingServices) => Promise<T>
+) => {
+  return async (config: Config, existingServices?: Partial<SingletonServices>): Promise<RequiredSingletonServices> => {
+    const { logger, variables, secrets, schema } = (existingServices ?? {}) as unknown as SingletonServices
+    const typedVariables = new TypedVariablesService(variables)
+    const typedSecrets = new TypedSecretService(secrets)
+    const result = await func(config, { ...existingServices, logger, variables: typedVariables, secrets: typedSecrets } as ExistingServices)
+    return {
+      config,
+      logger,
+      schema,
+      variables: typedVariables,
+      secrets: typedSecrets,
+      ...result,
+    } as unknown as RequiredSingletonServices
+  }
+}
+
+/**
+ * Creates a Pikku wire services factory for addon packages.
+ * Wire services are created per-request and have access to the HTTP request context.
+ *
+ * @param func - Wire services factory function that receives singleton services and the wire context
+ * @returns The wire services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createWireServices = pikkuAddonWireServices(async (services, wire) => {
+ *   const authHeader = wire.http?.request?.header('authorization')
+ *   return { myService: new MyService(authHeader) }
+ * })
+ * ```
+ */
+export const pikkuAddonWireServices = <ExistingServices extends Omit<Partial<SingletonServices>, 'variables' | 'secrets'> & AddonBaseServices>(
+  func: (services: ExistingServices, wire: PikkuWire) => Promise<Record<string, any>>
+) => {
+  return ((services: any, wire: PikkuWire) => {
+    const typedVariables = new TypedVariablesService(services.variables)
+    const typedSecrets = new TypedSecretService(services.secrets)
+    return func({ ...services, variables: typedVariables, secrets: typedSecrets } as ExistingServices, wire)
+  }) as any
+}

package/.pikku/addon/pikku-package.gen.ts

@@ -0,0 +1,9 @@
+/**
+ * This file was generated by @pikku/cli@0.12.55
+ */
+import { pikkuState } from '@pikku/core/internal'
+import { createSingletonServices as createSingletonServices } from '../../src/services.js'
+
+pikkuState('@pikku/addon-execution', 'package', 'factories', {
+  createSingletonServices,
+})

package/.pikku/agent/pikku-agent-map.gen.d.ts

@@ -0,0 +1,4 @@
+/**
+ * This file was generated by @pikku/cli@0.12.55
+ */
+export type AgentMap = {}

package/.pikku/agent/pikku-agent-types.gen.ts

@@ -0,0 +1,82 @@
+/**
+ * This file was generated by @pikku/cli@0.12.55
+ */
+import {
+  CoreAIAgent,
+  PikkuAIMiddlewareHooks,
+} from '@pikku/core/ai-agent'
+import {
+  agent as coreAgent,
+  agentStream as coreAgentStream,
+  agentResume as coreAgentResume,
+  agentApprove as coreAgentApprove,
+} from '@pikku/core/ai-agent'
+import type { PikkuPermission, PikkuMiddleware, Services, PikkuFunctionConfig } from '../function/pikku-function-types.gen.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { AIAgentMemoryConfig, AIAgentInput } from '@pikku/core/ai-agent'
+import type { AgentMap } from './pikku-agent-map.gen.d.js'
+
+type AIAgentConfig<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = Omit<CoreAIAgent<PikkuPermission, PikkuMiddleware>, 'tools' | 'agents' | 'memory' | 'input' | 'output'> & {
+  input?: InputSchema
+  output?: OutputSchema
+  memory?: Omit<AIAgentMemoryConfig, 'workingMemory'> & { workingMemory?: StandardSchemaV1 }
+  tools?: object[]
+  agents?: AIAgentConfig<StandardSchemaV1 | undefined, StandardSchemaV1 | undefined>[]
+}
+
+export const pikkuAIAgent = <
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  agent: AIAgentConfig<InputSchema, OutputSchema>
+) => {
+  return agent
+}
+
+export const pikkuAIMiddleware = <
+  State extends Record<string, unknown> = Record<string, unknown>,
+  RequiredServices extends Services = Services,
+>(
+  hooks: PikkuAIMiddlewareHooks<State, RequiredServices>
+): PikkuAIMiddlewareHooks<State, RequiredServices> => hooks
+
+export const agent = <Name extends keyof AgentMap>(
+  agentName: Name
+) => {
+  return coreAgent<AgentMap>(agentName as string & keyof AgentMap) as PikkuFunctionConfig<
+    AIAgentInput,
+    { runId: string; result: AgentMap[Name]['output']; usage: { inputTokens: number; outputTokens: number } },
+    'session' | 'rpc'
+  >
+}
+
+export const agentStream = <Name extends keyof AgentMap>(
+  agentName?: Name
+) => {
+  return coreAgentStream<AgentMap>(agentName as string & keyof AgentMap) as PikkuFunctionConfig<
+    { agentName?: string; message: string; threadId: string; resourceId: string },
+    void,
+    'session' | 'rpc'
+  >
+}
+
+export const agentResume = () => {
+  return coreAgentResume() as PikkuFunctionConfig<
+    { runId: string; toolCallId: string; approved: boolean },
+    void,
+    'session' | 'rpc'
+  >
+}
+
+export const agentApprove = <Name extends keyof AgentMap>(
+  agentName: Name
+) => {
+  return coreAgentApprove<AgentMap>(agentName as string & keyof AgentMap) as PikkuFunctionConfig<
+    { runId: string; approvals: { toolCallId: string; approved: boolean }[] },
+    unknown,
+    'session' | 'rpc'
+  >
+}

package/.pikku/channel/pikku-channel-types.gen.ts

@@ -0,0 +1,177 @@
+/**
+ * This file was generated by @pikku/cli@0.12.55
+ */
+/**
+ * Channel-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, wireChannel as wireChannelCore, defineChannelRoutes as defineChannelRoutesCore, addChannelMiddleware as addChannelMiddlewareCore } from '@pikku/core/channel'
+import { AssertHTTPWiringParams } from '@pikku/core/http'
+import type { PikkuFunctionConfig, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware, Services } from '../function/pikku-function-types.gen.js'
+import type { CorePermissionGroup } from '@pikku/core'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+/**
+ * Helper type to infer the output type from a Standard Schema
+ */
+type InferSchemaOutput<T> = T extends StandardSchemaV1<any, infer Output> ? Output : never
+
+/**
+ * Type definition for WebSocket channels with typed data exchange.
+ * Supports connection, disconnection, and message handling.
+ * Accepts both session-based (PikkuFunction) and sessionless (PikkuFunctionSessionless) functions.
+ *
+ * @template ChannelData - Type of data exchanged through the channel
+ * @template Channel - String literal type for the channel name
+ */
+type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<
+  ChannelData,
+  Channel,
+  PikkuFunctionConfig<void, any, 'channel' | 'session' | 'rpc'>,
+  PikkuFunctionConfig<void, void, 'channel' | 'session' | 'rpc'>,
+  PikkuFunctionConfig<any, any, 'channel' | 'session' | 'rpc'>,
+  PikkuPermission,
+  PikkuMiddleware
+>
+
+/**
+ * Creates a function that handles WebSocket channel connections.
+ * Called when a client connects to a channel.
+ *
+ * @template Out - Output type for connection response
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ */
+export const pikkuChannelConnectionFunc = <Out = unknown>(
+  func:
+    | PikkuFunctionSessionless<void, Out, 'channel' | 'session' | 'rpc'>
+    | PikkuFunctionConfig<void, Out, 'channel' | 'session' | 'rpc'>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Creates a function that handles WebSocket channel disconnections.
+ * Called when a client disconnects from a channel.
+ *
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ */
+export const pikkuChannelDisconnectionFunc = (
+  func:
+    | PikkuFunctionSessionless<void, void, 'channel'>
+    | PikkuFunctionConfig<void, void, 'channel' | 'session' | 'rpc'>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Configuration object for channel functions with Zod schema validation.
+ */
+type PikkuChannelFuncConfigWithSchema<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = {
+  name?: string
+  tags?: string[]
+  expose?: boolean
+  remote?: boolean
+  func: PikkuFunctionSessionless<
+    InferSchemaOutput<InputSchema>,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'channel' | 'session' | 'rpc'
+  >
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+  middleware?: PikkuMiddleware[]
+  input: InputSchema
+  output?: OutputSchema
+}
+
+/**
+ * Creates a function that handles WebSocket channel messages.
+ * Called when a message is received on a channel.
+ *
+ * Supports two patterns:
+ * 1. Generic types: `pikkuChannelFunc<Input, Output>({ func: ... })`
+ * 2. Zod schemas: `pikkuChannelFunc({ input: z.object(...), func: ... })`
+ *
+ * @template In - Input type for channel messages (inferred from schema if provided)
+ * @template Out - Output type for channel responses (inferred from schema if provided)
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * ```typescript
+ * // Pattern 1: Using generic types
+ * const handleMessage = pikkuChannelFunc<{text: string}, {received: boolean}>({
+ *   func: async (_services, { text }) => ({ received: true })
+ * })
+ *
+ * // Pattern 2: Using Zod schemas
+ * const messageInput = z.object({ text: z.string() })
+ * const messageOutput = z.object({ received: z.boolean() })
+ *
+ * const handleMessage = pikkuChannelFunc({
+ *   input: messageInput,
+ *   output: messageOutput,
+ *   func: async (_services, { text }) => ({ received: true })
+ * })
+ * ```
+ */
+export function pikkuChannelFunc<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuChannelFuncConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InferSchemaOutput<InputSchema>, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'channel' | 'session' | 'rpc'>
+export function pikkuChannelFunc<In, Out = unknown>(
+  func:
+    | PikkuFunctionSessionless<In, Out, 'channel' | 'session' | 'rpc'>
+    | PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
+): PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
+export function pikkuChannelFunc(func: any) {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Registers a WebSocket channel with the Pikku framework.
+ *
+ * @template ChannelData - Type of data associated with the channel
+ * @template Channel - String literal type for the channel name
+ * @param channel - Channel definition with connection, disconnection, and message handlers
+ */
+export const wireChannel = <ChannelData, Channel extends string>(
+  channel: ChannelWiring<ChannelData, Channel> & AssertHTTPWiringParams<ChannelData, Channel>
+) => {
+  wireChannelCore(channel as any)
+}
+
+/**
+ * Type-safe helper for defining channel message routes that can be composed.
+ * Returns the routes record as-is for use with wireChannel's onMessageWiring.
+ *
+ * @template T - Record of channel route handlers
+ * @param routes - The channel routes record
+ * @returns The same routes record (identity function for type safety)
+ */
+export function defineChannelRoutes<T extends Record<string, any>>(routes: T): T {
+  return defineChannelRoutesCore(routes)
+}
+
+export type PikkuChannelMiddleware<RequiredServices extends Services = Services, Event = unknown> = CorePikkuChannelMiddleware<RequiredServices, Event>
+
+export const pikkuChannelMiddleware = <RequiredServices extends Services = Services, Event = unknown>(
+  middleware: PikkuChannelMiddleware<RequiredServices, Event>
+): PikkuChannelMiddleware<RequiredServices, Event> => {
+  return middleware
+}
+
+export const pikkuChannelMiddlewareFactory = <In = any>(
+  factory: CorePikkuChannelMiddlewareFactory<In>
+): CorePikkuChannelMiddlewareFactory<In> => {
+  return factory
+}
+
+export const addChannelMiddleware = (tag: string, middleware: PikkuChannelMiddleware[]) =>
+  addChannelMiddlewareCore(tag, middleware, '@pikku/addon-execution')

package/.pikku/console/pikku-addon-meta.gen.json

@@ -0,0 +1,36 @@
+{
+  "nodes": {
+    "execute": {
+      "name": "execute",
+      "displayName": "Execute Command",
+      "category": "DevOps",
+      "type": "action",
+      "rpc": "execute",
+      "description": "Run a shell command, capturing stdout, stderr, and the exit code",
+      "errorOutput": false,
+      "inputSchemaName": "ExecuteInput",
+      "outputSchemaName": "ExecuteOutput"
+    },
+    "spawnCommand": {
+      "name": "spawnCommand",
+      "displayName": "Spawn Process",
+      "category": "DevOps",
+      "type": "action",
+      "rpc": "spawnCommand",
+      "description": "Spawn a program with an argument array (no shell), capturing stdout, stderr, and the exit code",
+      "errorOutput": false,
+      "inputSchemaName": "SpawnCommandInput",
+      "outputSchemaName": "SpawnCommandOutput"
+    }
+  },
+  "secrets": {},
+  "package": {
+    "displayName": "Execution",
+    "description": "Run shell commands and spawn processes, capturing stdout, stderr, and exit code",
+    "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <rect x=\"2\" y=\"4\" width=\"20\" height=\"16\" rx=\"2\" />\n  <path d=\"m6 9 3 3-3 3\" />\n  <path d=\"M13 15h4\" />\n</svg>",
+    "categories": [
+      "Utility",
+      "DevOps"
+    ]
+  }
+}

package/.pikku/console/pikku-node-types.gen.ts

@@ -0,0 +1,8 @@
+/**
+ * This file was generated by @pikku/cli@0.12.55
+ */
+import type { FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.js'
+
+export type NodeCategory = 'Utility' | 'DevOps'
+
+export type NodeRPCName = keyof FlattenedRPCMap