@pikku/skills 0.12.1

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@pikku/skills",
+  "version": "0.12.1",
+  "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",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "embed": "node scripts/embed.mjs",
+    "tsc": "yarn embed && tsc",
+    "build": "yarn embed && tsc -b",
+    "ncu": "npx npm-check-updates",
+    "test": "bash run-tests.sh",
+    "test:watch": "bash run-tests.sh --watch",
+    "test:coverage": "bash run-tests.sh --coverage",
+    "prepublishOnly": "yarn build"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.11.0",
+    "typescript": "^6.0.3",
+    "yaml": "^2.8.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/skills/pikku-addon/SKILL.md

@@ -0,0 +1,243 @@
+---
+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
+  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).
+installGroups: [core]
+---
+
+# Pikku Addons
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+Addons are reusable Pikku function packages that can be shared across projects. They bundle functions, services, secrets, and variables into a self-contained NPM package.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions and addons
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### `wireAddon(config)`
+
+Register an addon in the consuming project:
+
+```typescript
+import { wireAddon } from '#pikku'
+
+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
+  tags?: string[],                 // Tags applied to all addon functions
+  secretOverrides?: Record<string, string>,    // Remap secret names
+  variableOverrides?: Record<string, string>,  // Remap variable names
+})
+```
+
+### `addon(name)`
+
+Type-safe reference to an addon function — use when wiring to HTTP, agents, etc.:
+
+```typescript
+import { addon } from '#pikku'
+
+addon('todos:addTodo') // Returns a typed function config
+addon('emails:sendEmail') // Namespace:functionName format
+```
+
+### `pikkuAddonServices(factory)`
+
+Define singleton services for an addon package (created once at startup):
+
+```typescript
+import { pikkuAddonServices } from '#pikku'
+
+export const createSingletonServices = pikkuAddonServices(
+  async (config, parentServices?) => {
+    // parentServices: logger, variables, secrets from the consuming app
+    return {
+      myStore: new MyStore(),
+    }
+  }
+)
+```
+
+### `pikkuAddonWireServices(factory)`
+
+Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
+
+```typescript
+import { pikkuAddonWireServices } from '#pikku'
+
+export const createWireServices = pikkuAddonWireServices(
+  async (singletonServices, wire) => {
+    // wire: transport context (http, channel, session, etc.)
+    const authHeader = wire.http?.request?.header('authorization')
+    return {
+      myService: new MyService(authHeader),
+    }
+  }
+)
+```
+
+## Creating an Addon
+
+### Scaffold
+
+```bash
+npx pikku new addon
+```
+
+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`.
+
+### Services
+
+```typescript
+// src/services.ts
+import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku'
+import { TodoStore } from './todo-store.service.js'
+
+export const createSingletonServices = pikkuAddonServices(async () => {
+  const todoStore = new TodoStore()
+  return { todoStore }
+})
+
+// Optional — only needed if addon functions require per-request services
+export const createWireServices = pikkuAddonWireServices(
+  async (singletonServices, wire) => {
+    return {}
+  }
+)
+```
+
+### Functions
+
+```typescript
+// src/functions/addTodo.function.ts
+import { z } from 'zod'
+import { pikkuSessionlessFunc } from '#pikku'
+
+const AddTodoInput = z.object({ title: z.string() })
+const AddTodoOutput = z.object({ id: z.string(), title: z.string() })
+
+export const addTodo = pikkuSessionlessFunc({
+  description: 'Adds a new todo',
+  input: AddTodoInput,
+  output: AddTodoOutput,
+  func: async ({ todoStore }, { title }) => {
+    return todoStore.add(title)
+  },
+})
+```
+
+Optional approval gating (e.g. for agent tools) — add `approvalRequired: true` plus an `approvalDescription` resolver:
+
+```typescript
+approvalRequired: true,
+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
+```
+
+## Consuming an Addon
+
+### Install & Register
+
+```bash
+yarn add @my-org/addon-todos
+```
+
+```typescript
+// wirings/todos.wirings.ts
+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.
+
+### Call via RPC
+
+```typescript
+export const myFunc = pikkuFunc({
+  func: async (_services, data, { rpc }) => {
+    const todo = await rpc.invoke('todos:addTodo', { title: 'Buy milk' })
+    return todo
+  },
+})
+```
+
+### Wire to HTTP
+
+```typescript
+import { wireHTTP, addon } from '#pikku'
+
+wireHTTP({
+  method: 'get',
+  route: '/todos',
+  func: addon('todos:listTodos'),
+  auth: false,
+})
+```
+
+Or batch multiple addon routes with `defineHTTPRoutes` + `wireHTTPRoutes`:
+
+```typescript
+import { wireHTTPRoutes, defineHTTPRoutes, addon } 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') },
+  },
+})
+
+wireHTTPRoutes({ basePath: '/api', routes: { todos: todoRoutes } })
+```
+
+### Use in AI Agents
+
+```typescript
+import { pikkuAIAgent } from '#pikku'
+import { addon } 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',
+  tools: [
+    addon('todos:listTodos'),
+    addon('todos:addTodo'),
+    addon('todos:deleteTodo'),
+  ],
+  maxSteps: 5,
+})
+```

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -0,0 +1,63 @@
+# Addon Package Manifest Reference
+
+`npx pikku new addon` scaffolds these files. You rarely hand-edit them — consult this when wiring exports or config by hand.
+
+## Package Structure
+
+```text
+my-addon/
+├── package.json               # Exports .pikku/* and dist/
+├── pikku.config.json          # addon: true + metadata
+├── tsconfig.json              # #pikku path mapping
+├── src/
+│   ├── services.ts            # createSingletonServices (required)
+│   └── functions/
+│       └── *.function.ts      # Function definitions
+├── types/
+│   └── application-types.d.ts # SingletonServices interface
+└── .pikku/                    # Generated (gitignored)
+```
+
+## pikku.config.json
+
+```json
+{
+  "tsconfig": "./tsconfig.json",
+  "srcDirectories": ["src", "types"],
+  "outDir": "./.pikku",
+  "addon": true,
+  "node": {
+    "displayName": "My Addon",
+    "description": "What this addon does",
+    "categories": ["General"]
+  }
+}
+```
+
+## package.json (key fields)
+
+```json
+{
+  "name": "@my-org/addon-todos",
+  "imports": {
+    "#pikku": "./.pikku/pikku-types.gen.ts",
+    "#pikku/*": "./.pikku/*"
+  },
+  "exports": {
+    ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
+    "./.pikku/*": "./.pikku/*",
+    "./.pikku/pikku-metadata.gen.json": "./.pikku/pikku-metadata.gen.json",
+    "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.js": {
+      "types": "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts"
+    }
+  },
+  "files": ["dist", ".pikku"],
+  "peerDependencies": {
+    "@pikku/core": "*"
+  },
+  "scripts": {
+    "pikku": "pikku all",
+    "build": "tsc && cp -r .pikku dist/"
+  }
+}
+```

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

@@ -0,0 +1,231 @@
+---
+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
+  exposure (use pikku-mcp) or general function definitions (use pikku-concepts).
+installGroups: [core]
+---
+
+# Pikku AI Agent Wiring
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+Build AI agents that use Pikku functions as tools. Agents support conversation memory, streaming, and multi-step tool execution.
+
+## Before You Start
+
+```bash
+pikku info functions --verbose   # See existing functions that can be used as agent tools
+pikku info tags --verbose        # Understand project organization
+```
+
+See `pikku-concepts` for the core mental model.
+
+## API Reference
+
+### `pikkuAIAgent(config)`
+
+```typescript
+import { pikkuAIAgent } from '#pikku'
+
+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
+  memory?: {
+    storage?: string,            // Service name for persistence (e.g. 'aiStorage')
+    vector?: string,             // Vector store service name
+    embedder?: string,           // Embedding service name
+    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[],
+  permissions?: PermissionGroup,
+})
+```
+
+### `runAIAgent(name, input, options)` — Non-streaming
+
+```typescript
+const result = await runAIAgent(
+  agentName,
+  {
+    message: string, // User message
+    threadId: string, // Conversation thread ID
+    resourceId: string, // User/resource identifier
+  },
+  { singletonServices }
+)
+
+result.text // Agent's text response
+result.steps // Array of tool calls made
+result.usage // Token usage { inputTokens, outputTokens }
+```
+
+### `streamAIAgent(name, input, channel, options)` — Streaming
+
+```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: '...' }
+// { 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: 'usage', tokens: { input, output }, model }
+// { type: 'error', message }
+// { type: 'done' }
+```
+
+## 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.',
+  model: 'openai/gpt-5-mini',
+  tools: [listTodos, createTodo, completeTodo],
+  memory: {
+    storage: 'aiStorage',
+    lastMessages: 20,
+  },
+  maxSteps: 5,
+  temperature: 0.7,
+})
+```
+
+### Invoke Non-Streaming
+
+```typescript
+const result = await runAIAgent(
+  'todo-assistant',
+  {
+    message: 'Create a task for tomorrow: buy groceries',
+    threadId: 'thread-123',
+    resourceId: 'user-456',
+  },
+  { singletonServices }
+)
+
+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 }
+```
+
+### Stream Responses
+
+```typescript
+await streamAIAgent(
+  'todo-assistant',
+  {
+    message: 'Create a task for tomorrow',
+    threadId: 'thread-123',
+    resourceId: 'user-456',
+  },
+  channel,
+  { singletonServices }
+)
+```
+
+## Complete Example
+
+```typescript
+// functions/todos.functions.ts
+export const listTodos = pikkuSessionlessFunc({
+  description: 'List all todo items',
+  func: async ({ db }, { status }) => {
+    return { todos: await db.listTodos(status) }
+  },
+})
+
+export const createTodo = pikkuFunc({
+  description: 'Create a new todo item',
+  func: async ({ db }, { text, priority, dueDate }) => {
+    return await db.createTodo({ text, priority, dueDate })
+  },
+})
+
+export const completeTodo = pikkuFunc({
+  description: 'Mark a todo as complete',
+  func: async ({ db }, { todoId }) => {
+    return await db.completeTodo(todoId)
+  },
+})
+
+// agents/todo-assistant.ts
+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
+    - 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,
+  },
+  maxSteps: 5,
+  temperature: 0.7,
+})
+
+// Wire to HTTP for chat endpoint
+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 }
+      )
+    },
+  }),
+})
+```

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

@@ -0,0 +1,82 @@
+---
+name: pikku-ai-vercel
+description: >-
+  Use when setting up AI agent execution with the Vercel AI SDK in a Pikku app. Covers
+  VercelAIAgentRunner for streaming and non-streaming AI agent steps. TRIGGER when: code uses
+  VercelAIAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
+  @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or
+  voice I/O (use pikku-ai-voice).
+installGroups: [core]
+---
+
+# Pikku AI Vercel (Agent Runner)
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+`@pikku/ai-vercel` provides an AI agent runner backed by the [Vercel AI SDK](https://sdk.vercel.ai/). Implements `AIAgentRunnerService` from `@pikku/core`.
+
+## Installation
+
+```bash
+yarn add @pikku/ai-vercel ai @ai-sdk/openai  # or any AI SDK provider
+```
+
+## API Reference
+
+### `VercelAIAgentRunner`
+
+```typescript
+import { VercelAIAgentRunner } from '@pikku/ai-vercel'
+
+const runner = new VercelAIAgentRunner(
+  providers: Record<string, any>  // Map of provider name → Vercel AI SDK provider instance
+)
+```
+
+**Methods:**
+
+- `stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<AIAgentStepResult>` — Stream AI responses with tool calls
+- `run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>` — Execute a single AI step (non-streaming)
+
+The `providers` map lets you register multiple AI providers. Model strings use `provider:model` format (e.g., `"openai:gpt-4o"`).
+
+## Usage Patterns
+
+### Basic Setup
+
+```typescript
+import { VercelAIAgentRunner } from '@pikku/ai-vercel'
+import { openai } from '@ai-sdk/openai'
+import { anthropic } from '@ai-sdk/anthropic'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const aiRunner = new VercelAIAgentRunner({
+    openai: openai,
+    anthropic: anthropic,
+  })
+  return { config, aiRunner }
+})
+```
+
+### With AI Agent Wiring
+
+```typescript
+import { wireAIAgent } from '@pikku/core/ai-agent'
+
+wireAIAgent({
+  name: 'assistant',
+  model: 'openai:gpt-4o',
+  systemPrompt: 'You are a helpful assistant.',
+  func: myAgentFunc,
+})
+```
+
+The `VercelAIAgentRunner` is used internally by Pikku's AI agent wiring to execute model calls. See `pikku-ai-agent` for wiring details.