@pikku/core 0.12.1 → 0.12.3

package/src/types/core.types.ts

@@ -22,6 +22,7 @@ import type {
 } from '../wirings/workflow/workflow.types.js'
 import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
 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'
@@ -29,7 +30,9 @@ import type { AIStorageService } from '../services/ai-storage-service.js'
 import type { ContentService } from '../services/content-service.js'
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-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 { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
+import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 
 export type PikkuWiringTypes =
   | 'http'
@@ -42,6 +45,7 @@ export type PikkuWiringTypes =
   | 'cli'
   | 'workflow'
   | 'agent'
+  | 'gateway'
 
 export interface FunctionServicesMeta {
   optimized: boolean
@@ -105,7 +109,8 @@ export type FunctionRuntimeMeta = {
   readonly?: boolean
   sessionless?: boolean
   version?: number
-  requiresApproval?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: string
   contractHash?: string
   inputHash?: string
   outputHash?: string
@@ -218,6 +223,10 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   aiAgentRunner?: AIAgentRunnerService
   /** AI run state service (run lifecycle + approval persistence) */
   aiRunState?: AIRunStateService
+  /** Agent run service (listing threads, runs, steps) */
+  agentRunService?: AgentRunService
+  /** Workflow run service (listing workflow runs) */
+  workflowRunService?: WorkflowRunService
 }
 
 /**
@@ -249,6 +258,7 @@ export type PikkuWire<
   workflowStep: WorkflowStepWire
   graph: PikkuGraphWire
   trigger: PikkuTrigger<TriggerOutput>
+  gateway: PikkuGateway
   session: HasInitialSession extends true
     ? UserSession
     : UserSession | undefined
@@ -445,6 +455,7 @@ export type CreateConfig<
  */
 export type CommonWireMeta = {
   pikkuFuncId: string
+  packageName?: string
 
   title?: string
   tags?: string[]

package/src/types/state.types.ts

@@ -26,6 +26,10 @@ import type {
   CoreAIAgent,
   AIAgentMeta,
 } from '../wirings/ai-agent/ai-agent.types.js'
+import type {
+  CoreGateway,
+  GatewaysMeta,
+} from '../wirings/gateway/gateway.types.js'
 import type {
   CoreQueueWorker,
   QueueWorkersMeta,
@@ -75,8 +79,10 @@ export interface PikkuPackageState {
         path: string
       }
     >
-    /** Maps namespace aliases to package config (e.g., 'ext' -> { package: '@pikku/...', rpcEndpoint: '...' }) */
-    addons: Map<
+  }
+  /** Maps namespace aliases to package config (e.g., 'console' -> { package: '@pikku/console', ... }) */
+  addons: {
+    packages: Map<
       string,
       { package: string; rpcEndpoint?: string; auth?: boolean; tags?: string[] }
     >
@@ -121,6 +127,10 @@ export interface PikkuPackageState {
     agents: Map<string, CoreAIAgent>
     agentsMeta: AIAgentMeta
   }
+  gateway: {
+    gateways: Map<string, CoreGateway>
+    meta: GatewaysMeta
+  }
   cli: {
     meta: CLIMeta | Record<string, any> // Backward compatible with old published CLI format
     programs: Record<string, CLIProgramState>

package/src/utils/hash.test.ts

@@ -0,0 +1,68 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { canonicalJSON, hashString } from './hash.js'
+
+describe('canonicalJSON', () => {
+  it('sorts object keys alphabetically', () => {
+    const result = canonicalJSON({ b: 1, a: 2, c: 3 })
+    assert.equal(result, '{"a":2,"b":1,"c":3}')
+  })
+
+  it('sorts nested object keys', () => {
+    const result = canonicalJSON({ z: { b: 1, a: 2 }, a: 1 })
+    assert.equal(result, '{"a":1,"z":{"a":2,"b":1}}')
+  })
+
+  it('preserves array order', () => {
+    const result = canonicalJSON([3, 1, 2])
+    assert.equal(result, '[3,1,2]')
+  })
+
+  it('sorts objects inside arrays', () => {
+    const result = canonicalJSON([{ b: 1, a: 2 }])
+    assert.equal(result, '[{"a":2,"b":1}]')
+  })
+
+  it('handles null and undefined', () => {
+    assert.equal(canonicalJSON(null), 'null')
+    assert.equal(canonicalJSON(undefined), undefined)
+  })
+
+  it('handles primitives', () => {
+    assert.equal(canonicalJSON('hello'), '"hello"')
+    assert.equal(canonicalJSON(42), '42')
+    assert.equal(canonicalJSON(true), 'true')
+  })
+
+  it('produces deterministic output for same input regardless of key order', () => {
+    const a = canonicalJSON({ x: 1, y: 2, z: 3 })
+    const b = canonicalJSON({ z: 3, x: 1, y: 2 })
+    assert.equal(a, b)
+  })
+})
+
+describe('hashString', () => {
+  it('returns a hex string of default length 16', () => {
+    const result = hashString('test')
+    assert.equal(result.length, 16)
+    assert.match(result, /^[0-9a-f]+$/)
+  })
+
+  it('returns consistent hash for same input', () => {
+    const a = hashString('hello world')
+    const b = hashString('hello world')
+    assert.equal(a, b)
+  })
+
+  it('returns different hashes for different inputs', () => {
+    const a = hashString('hello')
+    const b = hashString('world')
+    assert.notEqual(a, b)
+  })
+
+  it('respects custom length parameter', () => {
+    const result = hashString('test', 8)
+    assert.equal(result.length, 8)
+  })
+})

package/src/utils/hash.ts

@@ -0,0 +1,26 @@
+import { createHash } from 'crypto'
+
+export function canonicalJSON(obj: unknown): string {
+  return JSON.stringify(sortDeep(obj))
+}
+
+function sortDeep(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortDeep)
+  }
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = sortDeep((value as Record<string, unknown>)[key])
+    }
+    return sorted
+  }
+  return value
+}
+
+export function hashString(input: string, length: number = 16): string {
+  return createHash('sha256').update(input).digest('hex').slice(0, length)
+}

package/src/utils.ts

@@ -103,7 +103,7 @@ export const stopSingletonServices = async (): Promise<void> => {
   const singletonServices = getSingletonServices()
   const logger = singletonServices.logger
 
-  // First, stop all addon package singleton services
+  // Stop all addon package singleton services
   const stateMap = getAllPackageStates()
   if (stateMap.size > 0) {
     for (const [packageName, packageState] of stateMap) {

package/src/wirings/ai-agent/agent-dynamic-workflow.ts

@@ -0,0 +1,469 @@
+import type { AIAgentToolDef } from './ai-agent.types.js'
+import { pikkuState, getSingletonServices } from '../../pikku-state.js'
+import { canonicalJSON, hashString } from '../../utils/hash.js'
+import type { WorkflowRuntimeMeta } from '../workflow/workflow.types.js'
+import { runWorkflowGraph } from '../workflow/graph/graph-runner.js'
+import type { StreamContext } from './ai-agent-prepare.js'
+import type { PikkuWire, CoreUserSession } from '../../types/core.types.js'
+import { ContextAwareRPCService, resolveNamespace } from '../rpc/rpc-runner.js'
+import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import {
+  validateWorkflowWiring,
+  computeEntryNodeIds,
+} from '../workflow/graph/graph-validation.js'
+
+export function buildDynamicWorkflowInstructions(tools: string[], mode: 'read' | 'always' | 'ask'): string {
+  if (mode === 'read') {
+    return (
+      '\n\n## Existing Workflows\n\n' +
+      'You can list and execute previously saved workflows using listAgentWorkflows and executeAgentWorkflow.\n' +
+      'Use listAgentWorkflows to discover what\'s available, then executeAgentWorkflow to run them.'
+    )
+  }
+
+  const modeGuidance = mode === 'always'
+    ? 'When a user requests a complex multi-step task, prefer creating a workflow over making sequential tool calls.\n' +
+      'Check if a suitable workflow already exists with listAgentWorkflows first.\n' +
+      'If none exists, create one with createAgentWorkflow, save with saveAgentWorkflow, then execute.\n\n'
+    : 'When you receive a request that would benefit from a reusable multi-step workflow,\n' +
+      'suggest creating one to the user. Explain the benefits (reusability, reliability,\n' +
+      'can run in background) and wait for confirmation before creating.\n' +
+      'Do NOT create workflows automatically — always propose and get user approval first.\n' +
+      'For one-off tasks, just use the tools directly.\n\n'
+
+  const toolSchemaLines: string[] = []
+
+  for (const toolName of tools) {
+    let fnMeta: any
+    let schemas: Map<string, any>
+
+    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null
+
+    if (resolved) {
+      fnMeta = pikkuState(resolved.package, 'function', 'meta')[
+        resolved.function
+      ]
+      schemas = pikkuState(resolved.package, 'misc', 'schemas')
+    } else {
+      const rpcMeta = pikkuState(null, 'rpc', 'meta')
+      const pikkuFuncId = rpcMeta[toolName]
+      if (!pikkuFuncId) continue
+      fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
+      schemas = pikkuState(null, 'misc', 'schemas')
+    }
+
+    if (!fnMeta) continue
+
+    const inputSchema = fnMeta.inputSchemaName
+      ? schemas.get(fnMeta.inputSchemaName)
+      : null
+    const outputSchema = fnMeta.outputSchemaName
+      ? schemas.get(fnMeta.outputSchemaName)
+      : null
+
+    const toolDescription = fnMeta.description || fnMeta.title || ''
+    const inputProps = inputSchema?.properties
+      ? Object.entries(inputSchema.properties)
+          .map(
+            ([k, v]: [string, any]) =>
+              `${k}${inputSchema.required?.includes(k) ? '' : '?'}: ${v.type || 'any'}`
+          )
+          .join(', ')
+      : ''
+    const outputProps = outputSchema?.properties
+      ? Object.entries(outputSchema.properties)
+          .map(([k, v]: [string, any]) => `${k}: ${v.type || 'any'}`)
+          .join(', ')
+      : 'any'
+
+    toolSchemaLines.push(
+      `- ${toolName}(input: {${inputProps}}) → {${outputProps}}${toolDescription ? ` — ${toolDescription}` : ''}`
+    )
+  }
+
+  return (
+    '\n\n## Workflow Creation\n\n' +
+    modeGuidance +
+    'You can create workflows that chain your tools together. Use createAgentWorkflow to validate and preview a workflow, then saveAgentWorkflow to save it, then executeAgentWorkflow to run it.\n\n' +
+    '### Tool Schemas:\n' +
+    toolSchemaLines.join('\n') +
+    '\n\n### Workflow Format:\n' +
+    '- Each node has: rpcName (tool name), input (with $ref to wire outputs), next (flow control), onError\n' +
+    '- Use {"$ref": "nodeId", "path": "fieldName"} to wire a previous node\'s output field to this node\'s input\n' +
+    '- Use {"$ref": "trigger", "path": "fieldName"} to extract a field from the workflow\'s trigger input. IMPORTANT: Always include "path" — never pass {"$ref": "trigger"} without "path", or the entire trigger object will be used as the value.\n' +
+    '- Use {"$ref": "nodeId", "path": "fieldName"} to extract a field from a previous node\'s output. Always include "path" to select the specific field.\n' +
+    '- next can be a string (single next node), array (parallel), or object {branchKey: nextNode} for branching\n' +
+    '\n### Example (add todo from trigger title, then list):\n' +
+    '{"add":{"rpcName":"todos:addTodo","input":{"title":{"$ref":"trigger","path":"title"}},"next":"list"},"list":{"rpcName":"todos:listTodos","input":{}}}\n' +
+    '\n### Example (add todo, sleep, complete using addTodo result id):\n' +
+    '{"add":{"rpcName":"todos:addTodo","input":{"title":{"$ref":"trigger","path":"title"}},"next":"wait"},"wait":{"rpcName":"sleep","input":{"seconds":5},"next":"complete"},"complete":{"rpcName":"todos:completeTodo","input":{"id":{"$ref":"add","path":"id"}}}}'
+  )
+}
+
+export function buildWorkflowTools(
+  agentName: string,
+  packageName: string | null,
+  toolNames: string[],
+  mode: 'read' | 'always' | 'ask',
+  streamContext?: StreamContext,
+  sessionService?: SessionService<CoreUserSession>
+): AIAgentToolDef[] {
+  const tools: AIAgentToolDef[] = []
+
+  if (mode !== 'read') {
+  tools.push({
+    name: 'createAgentWorkflow',
+    description:
+      'Validate and create a draft workflow graph that chains tools together. Call saveAgentWorkflow to activate it after the user approves.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description:
+            'Short name for the workflow (will be prefixed with ai:{agentName}:)',
+        },
+        description: {
+          type: 'string',
+          description: 'What this workflow does',
+        },
+        nodes: {
+          type: 'string',
+          description:
+            'JSON string of a map of nodeId to node config. Each node has: rpcName (tool name), input (with $ref to wire outputs), next (string|string[]|{branchKey: string}), onError (string|string[]). Example: {"list":{"rpcName":"todos:listTodos","input":{}}}',
+        },
+      },
+      required: ['name', 'nodes'],
+    },
+    execute: async (input: unknown) => {
+      const raw = input as {
+        name: string
+        description?: string
+        nodes: string | Record<string, any>
+      }
+      const name = raw.name.replace(/[^a-zA-Z0-9_-]/g, '-')
+      let nodes: Record<string, any>
+      if (typeof raw.nodes === 'string') {
+        try {
+          nodes = JSON.parse(raw.nodes)
+        } catch {
+          return { error: 'Invalid JSON in nodes field' }
+        }
+      } else {
+        nodes = raw.nodes
+      }
+
+      if (Object.keys(nodes).length < 2) {
+        return {
+          error:
+            'A workflow must have at least 2 nodes. A single node is just a tool call — use the tool directly instead.',
+        }
+      }
+
+      const validationErrors = validateWorkflowWiring(nodes, toolNames)
+      if (validationErrors.length > 0) {
+        return {
+          error: 'Workflow validation failed',
+          errors: validationErrors,
+        }
+      }
+
+      const entryNodeIds = computeEntryNodeIds(nodes)
+      if (entryNodeIds.length === 0) {
+        return {
+          error:
+            'No entry nodes found. Every node is referenced by another node, creating a cycle.',
+        }
+      }
+
+      const fullName = `ai:${agentName}:${name}`
+
+      const graphHash = hashString(canonicalJSON({ nodes, entryNodeIds }))
+      const graph: WorkflowRuntimeMeta = {
+        name: fullName,
+        pikkuFuncId: fullName,
+        source: 'ai-agent',
+        description: raw.description,
+        nodes,
+        entryNodeIds,
+        graphHash,
+      }
+
+      const singletonServices = getSingletonServices()
+      if (!singletonServices?.workflowService) {
+        return { error: 'Workflow service not available' }
+      }
+
+      await singletonServices.workflowService.upsertWorkflowVersion(
+        fullName,
+        graphHash,
+        graph,
+        'ai-agent',
+        'draft'
+      )
+
+      return {
+        valid: true,
+        workflowName: fullName,
+        graphHash,
+        entryNodes: entryNodeIds,
+        nodeCount: Object.keys(nodes).length,
+        message: `Workflow '${fullName}' validated and saved as draft. Present this to the user and call saveAgentWorkflow to activate it.`,
+      }
+    },
+  })
+
+  tools.push({
+    name: 'saveAgentWorkflow',
+    description:
+      'Activate a previously created draft workflow so it can be executed. Requires user approval.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description:
+            'Full workflow name returned by createAgentWorkflow (e.g. ai:agentName:myWorkflow)',
+        },
+        graphHash: {
+          type: 'string',
+          description: 'Graph hash returned by createAgentWorkflow',
+        },
+      },
+      required: ['name', 'graphHash'],
+    },
+    needsApproval: true,
+    approvalDescriptionFn: async (input: unknown) => {
+      const raw = input as { name: string; graphHash: string }
+      const fullName = raw.name.startsWith(`ai:${agentName}:`)
+        ? raw.name
+        : `ai:${agentName}:${raw.name}`
+
+      const singletonServices = getSingletonServices()
+      if (!singletonServices?.workflowService) {
+        return `Activate workflow '${fullName}'`
+      }
+
+      const version =
+        await singletonServices.workflowService.getWorkflowVersion(
+          fullName,
+          raw.graphHash
+        )
+      if (version) {
+        const graph = version.graph as WorkflowRuntimeMeta
+        if (graph.nodes) {
+          const desc = graph.description ? `\n${graph.description}` : ''
+          return `Activate workflow '${fullName}' (${Object.keys(graph.nodes).length} nodes)${desc}`
+        }
+      }
+      return `Activate workflow '${fullName}'`
+    },
+    execute: async (input: unknown) => {
+      const raw = input as { name: string; graphHash: string }
+      const fullName = raw.name.startsWith(`ai:${agentName}:`)
+        ? raw.name
+        : `ai:${agentName}:${raw.name}`
+
+      const singletonServices = getSingletonServices()
+      if (!singletonServices?.workflowService) {
+        return { error: 'Workflow service not available' }
+      }
+
+      const version =
+        await singletonServices.workflowService.getWorkflowVersion(
+          fullName,
+          raw.graphHash
+        )
+      if (!version) {
+        return {
+          error: `Workflow '${fullName}' with hash '${raw.graphHash}' not found. Use createAgentWorkflow first.`,
+        }
+      }
+
+      await singletonServices.workflowService.updateWorkflowVersionStatus(
+        fullName,
+        raw.graphHash,
+        'active'
+      )
+
+      const graph = version.graph as WorkflowRuntimeMeta
+      const allMeta = pikkuState(null, 'workflows', 'meta')
+      allMeta[fullName] = graph
+
+      if (streamContext) {
+        streamContext.channel.send({
+          type: 'workflow-created',
+          workflowName: fullName,
+          graph,
+        })
+      }
+
+      return {
+        success: true,
+        workflowName: fullName,
+        message: `Workflow '${fullName}' activated and ready to execute.`,
+      }
+    },
+  })
+  } // end if (mode !== 'read')
+
+  tools.push({
+    name: 'listAgentWorkflows',
+    description:
+      'List previously saved workflows for this agent that can be executed.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+    execute: async () => {
+      const singletonServices = getSingletonServices()
+      if (!singletonServices?.workflowService) {
+        return { error: 'Workflow service not available' }
+      }
+
+      const results: Array<{
+        name: string
+        description?: string
+        graphHash?: string
+      }> = []
+
+      const allMeta = pikkuState(null, 'workflows', 'meta')
+      const prefix = `ai:${agentName}:`
+      for (const [name, meta] of Object.entries(allMeta)) {
+        if (name.startsWith(prefix) && meta.source === 'ai-agent') {
+          results.push({
+            name,
+            description: meta.description,
+            graphHash: meta.graphHash,
+          })
+        }
+      }
+
+      if (results.length === 0) {
+        const persisted =
+          await singletonServices.workflowService.getAIGeneratedWorkflows(
+            agentName
+          )
+        for (const wf of persisted) {
+          results.push({
+            name: wf.workflowName,
+            graphHash: wf.graphHash,
+          })
+        }
+      }
+
+      return { workflows: results }
+    },
+  })
+
+  tools.push({
+    name: 'executeAgentWorkflow',
+    description: 'Execute a previously saved workflow with the given input.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description:
+            'Workflow name (will be auto-prefixed with ai:{agentName}: if needed)',
+        },
+        input: {
+          type: 'object',
+          description: 'Input data for the workflow trigger',
+        },
+      },
+      required: ['name'],
+    },
+    needsApproval: true,
+    approvalDescriptionFn: async (input: unknown) => {
+      const { name, input: workflowInput } = input as {
+        name: string
+        input?: Record<string, any>
+      }
+      const fullName = name.startsWith(`ai:${agentName}:`)
+        ? name
+        : `ai:${agentName}:${name}`
+      const inputStr = workflowInput
+        ? `\nInput: ${JSON.stringify(workflowInput)}`
+        : ''
+      return `Execute workflow '${fullName}'${inputStr}`
+    },
+    execute: async (toolInput: unknown) => {
+      const { name, input: workflowInput } = toolInput as {
+        name: string
+        input?: Record<string, any>
+      }
+
+      const fullName = name.startsWith(`ai:${agentName}:`)
+        ? name
+        : `ai:${agentName}:${name}`
+
+      const singletonServices = getSingletonServices()
+      if (!singletonServices?.workflowService) {
+        return { error: 'Workflow service not available' }
+      }
+
+      const allMeta = pikkuState(null, 'workflows', 'meta')
+      if (!allMeta[fullName]) {
+        return {
+          error: `Workflow '${fullName}' not found. Use listAgentWorkflows to see available workflows, or createAgentWorkflow to make a new one.`,
+        }
+      }
+
+      const workflowService = singletonServices.workflowService as any
+
+      const wire: PikkuWire = sessionService
+        ? { ...createMiddlewareSessionWireProps(sessionService) }
+        : {}
+      const rpcService = new ContextAwareRPCService(singletonServices, wire, {
+        sessionService,
+      })
+
+      const { runId } = await runWorkflowGraph(
+        workflowService,
+        fullName,
+        workflowInput ?? {},
+        rpcService,
+        true,
+        undefined,
+        { type: 'ai-agent' }
+      )
+
+      const maxWait = 45000
+      const startTime = Date.now()
+      let pollInterval = 100
+      while (Date.now() - startTime < maxWait) {
+        const run = await workflowService.getRun(runId)
+        if (!run) {
+          return { error: `Workflow run '${runId}' not found` }
+        }
+        if (
+          run.status === 'completed' ||
+          run.status === 'failed' ||
+          run.status === 'cancelled' ||
+          run.status === 'suspended'
+        ) {
+          if (run.status === 'failed') {
+            return {
+              error: `Workflow failed: ${run.error?.message || 'Unknown error'}`,
+              runId,
+            }
+          }
+          return { result: run.output, runId, status: run.status }
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval))
+        pollInterval = Math.min(pollInterval * 1.5, 2000)
+      }
+
+      return {
+        runId,
+        status: 'running',
+        message:
+          'Workflow is still running after timeout. It will continue in the background.',
+      }
+    },
+  })
+
+  return tools
+}