@pikku/skills 0.12.4 → 0.12.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.4",
+  "version": "0.12.8",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-addon/SKILL.md

@@ -2,8 +2,8 @@
 name: pikku-addon
 description: >-
   Use when creating or consuming reusable function packages (addons) in Pikku. Covers wireAddon,
-  addon(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, and cross-project
-  function sharing. TRIGGER when: code uses wireAddon/addon()/pikkuAddonServices, user asks about
+  ref(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, and cross-project
+  function sharing. TRIGGER when: code uses wireAddon/ref()/pikkuAddonServices, user asks about
   addons, reusable function packages, cross-project sharing, or addon package structure. DO NOT
   TRIGGER when: user asks about internal function composition (use pikku-rpc) or general function
   definitions (use pikku-concepts).
@@ -46,41 +46,66 @@ wireAddon({
   name: string,                    // Namespace for addon functions (e.g. 'todos')
   package: string,                 // NPM package name (e.g. '@pikku/addon-todos')
   rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
-  auth?: boolean,                  // Whether addon functions require authentication
+  auth?: boolean,                  // Require a session for every function in the addon
+  mcp?: boolean,
   tags?: string[],                 // Tags applied to all addon functions
-  secretOverrides?: Record<string, string>,    // Remap secret names
-  variableOverrides?: Record<string, string>,  // Remap variable names
+  scopes?: string[],               // Required of every function, on top of its own
+  secretOverrides?: Record<string, string>,      // Remap secret names
+  variableOverrides?: Record<string, string>,    // Remap variable names
+  credentialOverrides?: Record<string, string>,  // Remap credential names
 })
 ```
 
-### `addon(name)`
+**`auth`, `tags` and `scopes` only ever tighten.** `auth: false` is not honoured —
+it would weaken the wiring's own gate — so the addon-level setting can require a
+session but never waive one. The same package wired twice under two namespaces is
+governed by the union of both instances' scopes and tags.
 
-Type-safe reference to an addon function — use when wiring to HTTP, agents, etc.:
+### `ref(name)`
+
+Type-safe reference to a function — local or addon — for use in any wiring. It
+returns a function config that proxies the call via RPC at runtime:
+
+```typescript
+import { ref } from '#pikku'
+
+ref('todos:addTodo') // namespace:functionName for an addon function
+ref('myLocalFunc') // a local function by name
+```
+
+There is no `addon()` helper; `ref()` covers both. For an addon that publishes
+**wiring contracts** rather than bare functions, codegen also emits `refHTTP`,
+`refChannel` and `refCLI`, which carry the addon's own route/config metadata:
 
 ```typescript
-import { addon } from '#pikku'
+import { refHTTP } from '#pikku'
 
-addon('todos:addTodo') // Returns a typed function config
-addon('emails:sendEmail') // Namespace:functionName format
+wireHTTP(refHTTP('todos:listTodos', { basePath: '/api' }))
 ```
 
 ### `pikkuAddonServices(factory)`
 
-Define singleton services for an addon package (created once at startup):
+Define singleton services for an addon package (created once at startup). The
+second argument is always present — an addon never falls back to its own logger,
+variables or secrets; the consuming app supplies them:
 
 ```typescript
 import { pikkuAddonServices } from '#pikku'
 
 export const createSingletonServices = pikkuAddonServices(
-  async (config, parentServices?) => {
-    // parentServices: logger, variables, secrets from the consuming app
-    return {
-      myStore: new MyStore(),
-    }
+  async (config, { secrets, logger }) => {
+    const creds =
+      await secrets.getSecret<GithubCredentials>('GITHUB_CREDENTIALS')
+    return { github: new GithubService(creds.reveal()) }
   }
 )
 ```
 
+`secrets` and `variables` arrive **typed against the addon's own declarations**,
+and a secret is a `SecretValue` — `.reveal()` is the only way to the plaintext
+(see `pikku-config`). `pikkuAddonConfig` is the matching factory for the addon's
+config object.
+
 ### `pikkuAddonWireServices(factory)`
 
 Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
@@ -104,7 +129,8 @@ export const createWireServices = pikkuAddonWireServices(
 ### Scaffold
 
 ```bash
-npx pikku new addon
+npx pikku new addon <name>          # name is a required positional
+npx pikku new addon stripe --display-name Stripe --category Payments --dir addons
 ```
 
 This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json` (`addon: true`), `tsconfig.json` (`#pikku` path mapping), `src/services.ts`, `src/functions/`, and `types/application-types.d.ts`. For the full file contents/exports you rarely hand-edit, read `references/addon-package-manifest.md`.
@@ -159,11 +185,24 @@ approvalDescription: async (_services, { title }) => `Add a todo called "${title
 ### Build
 
 ```bash
-npx pikku all    # Generate types
-yarn tsc         # Compile TypeScript
-cp -r .pikku dist/  # Include generated files in dist
+yarn pikku all          # Generate types
+yarn tsc                # Compile TypeScript
+cp -r .pikku types dist/  # Ship the generated files and the types they import
+yarn pikku validate     # Check the published file set holds together
 ```
 
+`yarn pikku`, not `npx pikku`: a scaffolded addon carries `@pikku/cli` as a
+devDependency, and building it against a different CLI than it declares is how
+generated output ends up disagreeing with the packaged one. `npx pikku new
+addon` above is the exception — it runs before the addon, and its CLI, exist.
+
+`types/` has to be copied alongside `.pikku`: the generated files import
+`SingletonServices`, `Services`, `Config` and `UserSession` from
+`../../types/application-types.d.js`, and `tsc` never emits a hand-written
+`.d.ts` to `outDir`, so nothing else puts it in `dist`. Leave it out and the
+addon installs fine and fails to typecheck in every app that depends on it —
+which is what `pikku validate` is there to catch before you publish.
+
 ## Consuming an Addon
 
 ### Install & Register
@@ -179,7 +218,7 @@ import { wireAddon } from '#pikku'
 wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 ```
 
-After registration, run `npx pikku all` to generate types for the addon's functions.
+After registration, run `yarn pikku all` to generate types for the addon's functions.
 
 ### Call via RPC
 
@@ -195,12 +234,12 @@ export const myFunc = pikkuFunc({
 ### Wire to HTTP
 
 ```typescript
-import { wireHTTP, addon } from '#pikku'
+import { wireHTTP, ref } from '#pikku'
 
 wireHTTP({
   method: 'get',
   route: '/todos',
-  func: addon('todos:listTodos'),
+  func: ref('todos:listTodos'),
   auth: false,
 })
 ```
@@ -208,14 +247,14 @@ wireHTTP({
 Or batch multiple addon routes with `defineHTTPRoutes` + `wireHTTPRoutes`:
 
 ```typescript
-import { wireHTTPRoutes, defineHTTPRoutes, addon } from '#pikku'
+import { wireHTTPRoutes, defineHTTPRoutes, ref } from '#pikku'
 
 const todoRoutes = defineHTTPRoutes({
   tags: ['todos'],
   auth: false,
   routes: {
-    list: { method: 'get', route: '/todos', func: addon('todos:listTodos') },
-    add: { method: 'post', route: '/todos', func: addon('todos:addTodo') },
+    list: { method: 'get', route: '/todos', func: ref('todos:listTodos') },
+    add: { method: 'post', route: '/todos', func: ref('todos:addTodo') },
   },
 })
 
@@ -225,19 +264,21 @@ wireHTTPRoutes({ basePath: '/api', routes: { todos: todoRoutes } })
 ### Use in AI Agents
 
 ```typescript
-import { pikkuAIAgent } from '#pikku'
-import { addon } from '#pikku'
+import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku'
 
 export const todoAgent = pikkuAIAgent({
   name: 'todo-agent',
   description: 'Manages a todo list',
-  instructions: 'You help users manage their todos.',
-  model: 'openai/gpt-4o',
+  goal: 'You help users manage their todos.',
+  model: 'openai/gpt-5-mini',
   tools: [
-    addon('todos:listTodos'),
-    addon('todos:addTodo'),
-    addon('todos:deleteTodo'),
+    ref('todos:listTodos'),
+    ref('todos:addTodo'),
+    ref('todos:deleteTodo'),
   ],
   maxSteps: 5,
 })
 ```
+
+See `pikku-ai-agent` — an addon function is just another `ref()` in `tools`.

package/skills/pikku-ai-agent/SKILL.md

@@ -2,9 +2,10 @@
 name: pikku-ai-agent
 description: >-
   Use when building AI agents, chatbots, or LLM-powered assistants with Pikku. Covers
-  pikkuAIAgent, tool registration, memory, streaming, and agent invocation. TRIGGER when: code
-  uses pikkuAIAgent/runAIAgent/streamAIAgent, user asks about AI agents, chatbots, LLM assistants,
-  tool-calling agents, or agent memory/streaming. DO NOT TRIGGER when: user asks about MCP tool
+  pikkuAIAgent, ref() tool registration, memory, streaming, tool approval, thread ownership, and
+  invocation via rpc.agent. TRIGGER when: code uses pikkuAIAgent/rpc.agent/runAIAgent/
+  streamAIAgent, user asks about AI agents, chatbots, LLM assistants, tool-calling agents, agent
+  memory/streaming, or `pikku enable agent`. DO NOT TRIGGER when: user asks about MCP tool
   exposure (use pikku-mcp) or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
@@ -36,16 +37,35 @@ See `pikku-concepts` for the core mental model.
 
 ### `pikkuAIAgent(config)`
 
+Import it from the generated agent types file — `#pikku` does not re-export it:
+
 ```typescript
-import { pikkuAIAgent } from '#pikku'
+import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/pikku-types.gen.js'
 
 pikkuAIAgent({
   name: string,                  // Unique agent identifier
-  description: string,           // What the agent does
-  instructions: string | string[],  // System prompt / behavior instructions
-  model: string,                 // LLM model (e.g. 'openai/gpt-5-mini')
-  tools?: PikkuFunc[],           // Pikku functions the agent can call
-  agents?: AIAgentConfig[],      // Sub-agents this agent can delegate to
+  description: string,           // What the agent does (shown in agent listings)
+  summary?: string,
+  errors?: string[],
+
+  // --- system prompt: three fields, joined role → personality → goal ---
+  role?: string,                 // Who it is: 'You are a support engineer triaging bugs.'
+  personality?: string,          // How it sounds: tone, verbosity
+  goal: string,                  // REQUIRED — what it is for
+
+  model: string,                 // e.g. 'openai/gpt-5-mini'
+  temperature?: number,
+  providerOptions?: {            // passed through untouched, keyed by provider
+    openai?: { reasoningEffort?: 'minimal' | ... },
+  },
+
+  // --- capabilities: all three take ref() handles, not imported values ---
+  tools?: unknown[],             // ref('todos:addTodo'), ref('graph:sleep'), …
+  agents?: unknown[],            // sub-agents to delegate to
+  workflows?: unknown[],         // workflows callable as a tool
+  agentMode?: 'delegate' | 'supervise',
+
   memory?: {
     storage?: string,            // Service name for persistence (e.g. 'aiStorage')
     vector?: string,             // Vector store service name
@@ -53,118 +73,189 @@ pikkuAIAgent({
     lastMessages?: number,       // How many messages to retain in context
     workingMemory?: ZodSchema,   // Schema for structured working memory
   },
+
   maxSteps?: number,             // Max tool-call rounds per invocation
-  temperature?: number,          // LLM temperature (0-1)
   toolChoice?: 'auto' | 'required' | 'none',
-  input?: ZodSchema,             // Input validation schema
-  output?: ZodSchema,            // Output validation schema
-  tags?: string[],               // For grouping and middleware targeting
-  aiMiddleware?: PikkuAIMiddlewareHooks[],  // AI-specific middleware
-  middleware?: PikkuMiddleware[],
+  prepareStep?: (ctx) => void,   // See "Narrowing tools per step"
+  input?: ZodSchema,
+  output?: ZodSchema,            // Structured output — only honoured with NO tools
+  tags?: string[],
+
+  sessionScope?: 'user' | 'org', // Who owns this agent's threads. Default 'user'
+  auth?: boolean,                // Default false — see below
+  scopes?: ScopeId[],            // AND gate, checked before permissions
   permissions?: PermissionGroup,
+
+  middleware?: PikkuMiddleware[],
+  channelMiddleware?: PikkuChannelMiddleware[],
+  aiMiddleware?: PikkuAIMiddlewareHooks[],
 })
 ```
 
-### `runAIAgent(name, input, options)` — Non-streaming
+**`goal` is the required prompt field, not `instructions`** — there is no
+`instructions` key. `role`/`personality`/`goal` are concatenated in that order,
+and nothing validates which text lands in which, so the split is purely for
+legibility: prose in the "wrong" one still reaches the model.
+
+**Tools are `ref('domain:funcName')` handles, not imported function values.** The
+inspector resolves the ref against the generated function map, which is what lets
+an agent reach a function in another package (or a `graph:*` builtin) without an
+import cycle.
+
+`auth` defaults to `false` because agents are usually invoked from an
+already-authenticated `pikkuFunc`. `scopes` and `permissions` are enforced either
+way — see `pikku-permissions`.
+
+### Invoking an agent
+
+From inside a Pikku function, go through `wire.rpc.agent` — it carries the
+session, credentials, and RPC depth for you:
 
 ```typescript
-const result = await runAIAgent(
-  agentName,
-  {
-    message: string, // User message
-    threadId: string, // Conversation thread ID
-    resourceId: string, // User/resource identifier
-  },
-  { singletonServices }
-)
+const result = await rpc.agent.run('todo-agent', {
+  message, threadId, resourceId,     // required
+  attachments?, model?, temperature?, context?,
+})
 
-result.text // Agent's text response
-result.steps // Array of tool calls made
-result.usage // Token usage { inputTokens, outputTokens }
+await rpc.agent.stream('todo-agent', input)              // writes to the wire's channel
+await rpc.agent.approve(runId, [{ toolCallId, approved }], expectedAgentName?)
+await rpc.agent.resume(runId, { toolCallId, approved })
+await rpc.agent.interrupt(runId, 'user' | 'speech' | 'timeout')
 ```
 
-### `streamAIAgent(name, input, channel, options)` — Streaming
+`context` is a string injected into the system prompt for this request only —
+use it for upfront state (current org, project, deployment) so the agent stops
+asking the user for identifiers it could have been handed.
+
+`run` resolves to:
 
 ```typescript
-await streamAIAgent(
-  agentName,
-  {
-    message: string,
-    threadId: string,
-    resourceId: string,
-  },
-  channel,
-  { singletonServices }
-)
-
-// Channel receives events:
-// { type: 'step-start', stepNumber: 1 }
-// { type: 'text-delta', text: '...' }
-// { type: 'reasoning-delta', text: '...' }
+{
+  runId, threadId, text,
+  object?,                              // set when the agent has an `output` schema
+  steps,                                // tool calls made
+  usage: { inputTokens, outputTokens },
+  status?: 'completed' | 'suspended',
+  pendingApprovals?: [{ toolCallId, toolName, args, reason?, runId }],
+}
+```
+
+`runAIAgent` / `streamAIAgent` from `@pikku/core/ai-agent` are the layer beneath
+this. Their third argument is `RunAIAgentParams` (`{ sessionService?,
+getCredential?, anonymousOwnerResourceId? }`) — **not** `{ singletonServices }`.
+Reach for them only outside a wired function; inside one, `rpc.agent` is the
+supported path.
+
+### Stream events
+
+`rpc.agent.stream` pushes `AIStreamEvent`s onto the channel:
+
+```typescript
+// { type: 'step-start', stepNumber }
+// { type: 'text-delta' | 'reasoning-delta', text }
 // { type: 'tool-call', toolCallId, toolName, args }
 // { type: 'tool-result', toolCallId, toolName, result }
-// { type: 'agent-call', agentName, session, input }
-// { type: 'agent-result', agentName, session, result }
-// { type: 'approval-request', toolCallId, toolName, args, reason? }
+// { type: 'agent-call' | 'agent-result', agentName, session, input | result }
+// { type: 'approval-request', toolCallId, toolName, args, reason?, runId? }
+// { type: 'credential-request', toolCallId, toolName, credentialName,
+//   credentialType: 'oauth2' | 'apikey', connectUrl?, runId }
 // { type: 'usage', tokens: { input, output }, model }
+// { type: 'transcript', text }                    // what the user was heard to say
+// { type: 'audio-delta', data, format, text? } | { type: 'audio-done' }
+// { type: 'data', name, data } | { type: 'generative-ui', spec }
+// { type: 'suspended', reason: 'rpc-missing', missingRpcs }
+// { type: 'interrupted', runId, text, reason }
 // { type: 'error', message }
 // { type: 'done' }
 ```
 
+Every event except `agent-call`/`agent-result`/`suspended` also carries optional
+`agent` and `session` fields, so a UI can attribute output to a sub-agent rather
+than folding it into the parent's transcript.
+
 ## Usage Patterns
 
 ### Define an Agent
 
 ```typescript
-const todoAssistant = pikkuAIAgent({
-  name: 'todo-assistant',
-  description: 'A helpful assistant that manages todos',
-  instructions:
-    'You help users manage their todo lists. Be concise and helpful.',
+import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/pikku-types.gen.js'
+
+export const todoAgent = pikkuAIAgent({
+  name: 'todo-agent',
+  description: 'Manages a todo list',
+  goal: 'You help users manage their todos. You can list, add, complete and delete them.',
   model: 'openai/gpt-5-mini',
-  tools: [listTodos, createTodo, completeTodo],
-  memory: {
-    storage: 'aiStorage',
-    lastMessages: 20,
-  },
-  maxSteps: 5,
-  temperature: 0.7,
+  tools: [
+    ref('todos:listTodos'),
+    ref('todos:addTodo'),
+    ref('todos:completeTodo'),
+    ref('graph:sleep'),
+  ],
+  memory: { storage: 'aiStorage', lastMessages: 20 },
+  maxSteps: 10,
+  toolChoice: 'auto',
 })
 ```
 
-### Invoke Non-Streaming
+### Scaffold the HTTP surface
 
-```typescript
-const result = await runAIAgent(
-  'todo-assistant',
-  {
-    message: 'Create a task for tomorrow: buy groceries',
-    threadId: 'thread-123',
-    resourceId: 'user-456',
-  },
-  { singletonServices }
-)
+```bash
+pikku enable agent            # session required
+pikku enable agent --noAuth   # public
+```
+
+The next `pikku all` generates `agent.gen.ts` — run/stream/approve/resume
+callers plus thread listing endpoints, with thread ownership already enforced
+against the session. Don't hand-write these routes.
+
+### Structured output
+
+An `output` schema fills `result.object`, but **only when the agent exposes no
+tools** — with a tool present the runner falls back to free text, silently. If
+you need both, split the classification into its own tool-free agent.
 
-console.log(result.text) // "I've created a task 'buy groceries' for tomorrow."
-console.log(result.steps) // [{ tool: 'createTodo', args: {...}, result: {...} }]
-console.log(result.usage) // { inputTokens: 150, outputTokens: 42 }
+```typescript
+export const structuredAgent = pikkuAIAgent({
+  name: 'structured-agent',
+  description: 'Classifies a message and returns a structured verdict',
+  goal: 'You classify the sentiment of the user message.',
+  model: 'openai/gpt-5-mini',
+  output: z.object({ sentiment: z.string(), score: z.number() }),
+})
 ```
 
-### Stream Responses
+### Narrowing tools per step
+
+`prepareStep` runs before each step with the live tool array for that step, so
+mutating it in place changes what the model is offered from there on. `stop()`
+ends the loop — called before step 0 the run completes with an empty result
+rather than signalling that it was short-circuited.
 
 ```typescript
-await streamAIAgent(
-  'todo-assistant',
-  {
-    message: 'Create a task for tomorrow',
-    threadId: 'thread-123',
-    resourceId: 'user-456',
-  },
-  channel,
-  { singletonServices }
-)
+prepareStep: ({ stepNumber, tools }) => {
+  if (stepNumber >= 1) tools.length = 0   // withdraw tools after the first step
+}
 ```
 
+### Tool approval
+
+A tool that should pause for a human sets `approvalRequired: true` (with an
+optional `approvalDescription`) on the *function*, not on the agent. The run then
+resolves with `status: 'suspended'` and `pendingApprovals`, and streaming emits
+`approval-request`. Answer with `rpc.agent.approve(runId, approvals)`.
+
+Authorization around tools is two-layer: an agent only sees tools its session can
+reach, and the function's own `permissions` still guard the call when the model
+picks one.
+
+### Thread ownership
+
+`resourceId` is caller-supplied but never trusted as an owner. The session's
+principal (`userId`, or `orgId` when `sessionScope: 'org'`) is prefixed onto it,
+so a client can sub-partition inside its own boundary and cannot read across one.
+A sessionless run gets an ephemeral anonymous owner instead.
+
 ## Complete Example
 
 ```typescript
@@ -190,41 +281,42 @@ export const completeTodo = pikkuFunc({
   },
 })
 
-// agents/todo-assistant.ts
-const todoAssistant = pikkuAIAgent({
+// agents/todo-assistant.agent.ts
+import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/pikku-types.gen.js'
+
+export const todoAssistant = pikkuAIAgent({
   name: 'todo-assistant',
   description: 'A helpful assistant that manages todos',
-  instructions: `You help users manage their todo lists.
-    - Be concise and helpful
+  role: 'You are an assistant that manages a user’s todo list.',
+  personality: 'Concise. One short paragraph unless asked for detail.',
+  goal: `Keep the user's todos accurate.
     - When creating todos, infer priority if not specified
     - When listing todos, summarize the results`,
   model: 'openai/gpt-5-mini',
-  tools: [listTodos, createTodo, completeTodo],
-  memory: {
-    storage: 'aiStorage',
-    lastMessages: 20,
-  },
+  tools: [
+    ref('todos:listTodos'),
+    ref('todos:createTodo'),
+    ref('todos:completeTodo'),
+  ],
+  memory: { storage: 'aiStorage', lastMessages: 20 },
   maxSteps: 5,
   temperature: 0.7,
 })
 
-// Wire to HTTP for chat endpoint
+// Wire to HTTP for a chat endpoint — or skip this entirely and run
+// `pikku enable agent`, which scaffolds run/stream/approve/resume for you.
 wireHTTP({
   method: 'post',
   route: '/chat',
   func: pikkuFunc({
     title: 'Chat',
-    func: async (services, { message, threadId }, wire) => {
-      const { session } = wire
-      return await runAIAgent(
-        'todo-assistant',
-        {
-          message,
-          threadId,
-          resourceId: session.userId,
-        },
-        { singletonServices: services }
-      )
+    func: async (_services, { message, threadId }, { session, rpc }) => {
+      return await rpc.agent.run('todo-assistant', {
+        message,
+        threadId,
+        resourceId: session.userId,
+      })
     },
   }),
 })