@pikku/cli 0.12.156 → 0.12.159

package/dist/src/functions/commands/knowledge-reconcile.js

@@ -6,6 +6,6 @@ export const knowledgeReconcile = pikkuSessionlessFunc({
     description: 'Say the one thing to do next with the knowledge base — repair a note, write a plan, ask the user, dispatch a build, or nothing — derived from what is on disk rather than from what a previous step remembered to announce.',
     input: KnowledgeReconcileInputSchema,
     output: KnowledgeReconcileOutputSchema,
-    func: async ({ config }) => runKnowledgeReconcile(config.rootDir),
+    func: async ({ config }, input) => runKnowledgeReconcile(config.rootDir, input),
 });
 export { renderKnowledgeReconcile };

package/dist/src/functions/commands/scenario.js

@@ -236,7 +236,7 @@ export const scenarioRun = pikkuSessionlessFunc({
             apiUrl: env.apiUrl,
             appUrl: env.appUrl,
         });
-        scenarioService.setRunSurface(runSurface);
+        scenarioService.setRunSurface(runSurface, strict);
         // Scenario steps run here, not on the target — everything they touch of the
         // app goes over HTTP through an actor, which is what `guardRpc` below
         // enforces. `actor.converse` is the exception, and the reason this is not

package/dist/src/functions/commands/skill-agents.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The frontmatter a skill adds to become a subagent as well as a skill.
+ *
+ * A skill is instructions a session reads; an agent is a child process a host
+ * dispatches and then judges. The difference is entirely the gate, so the gate is
+ * the only thing a skill has to declare — everything else about the agent is
+ * derived from the skill it already is.
+ */
+export interface SkillAgentSpec {
+    tools?: string;
+    timeoutMs?: number;
+    acceptance?: Record<string, unknown>;
+}
+interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    agent?: SkillAgentSpec;
+}
+export declare function parseSkill(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+} | null;
+/**
+ * Write out an agent for every installed skill that declares one.
+ *
+ * Skills without an `agent:` block are not projected: a reference skill has no
+ * post-condition a host could check, and an agent whose acceptance is `none` is a
+ * subagent dispatched to read something the caller could have read itself.
+ */
+export declare function installSkillAgents(skills: string[], agentRoot: string, skillDir: string, update: boolean, existing: (path: string) => boolean, read: (path: string) => Promise<string | null>, 
+/**
+ * Host extensions every projected agent loads, as pi resolves them.
+ *
+ * They are passed in rather than declared by the skill because they belong to
+ * whoever is running the agent, not to the instructions it follows: a sandbox
+ * fences its writers and routes their model, and the same skill run on a
+ * developer's own checkout needs neither.
+ */
+extensions?: string[]): Promise<{
+    written: string[];
+    skipped: string[];
+}>;
+export {};

package/dist/src/functions/commands/skill-agents.js

@@ -0,0 +1,135 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { parse, stringify } from 'yaml';
+/**
+ * The tools that can change the workspace, and so decide the agent's role.
+ *
+ * `bash` counts because a shell is a superset of the rest: `sed -i`, `echo >` and
+ * `git checkout` all mutate without touching a file tool.
+ */
+const MUTATING_TOOLS = [
+    'bash',
+    'shell',
+    'write',
+    'edit',
+    'write_files',
+    'edit_files',
+    'patch',
+];
+const DEFAULT_TOOLS = 'read, write, edit, bash, grep';
+/**
+ * The role is derived from the tools rather than declared beside them.
+ *
+ * It is what acceptance is inferred from, so a skill that declares the two
+ * independently can declare them inconsistently — a read-only role holding `write`
+ * is an agent the host judges by rules its tools do not match.
+ */
+function acceptanceRole(tools) {
+    const declared = tools.split(',').map((tool) => tool.trim());
+    return declared.some((tool) => MUTATING_TOOLS.includes(tool))
+        ? 'writer'
+        : 'read-only';
+}
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+export function parseSkill(content) {
+    const match = content.match(FRONTMATTER);
+    if (!match)
+        return null;
+    try {
+        return { frontmatter: parse(match[1]) ?? {}, body: match[2] ?? '' };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The first paragraph of the skill's own description, as the one line a host shows
+ * when it is choosing between agents.
+ *
+ * A skill description is written for a trigger matcher and carries TRIGGER/DO NOT
+ * TRIGGER clauses that mean nothing to a dispatcher, so they are cut rather than
+ * shipped as noise into every agent listing.
+ */
+function agentDescription(description) {
+    return description
+        .split(/\bTRIGGER when\b|\bDO NOT TRIGGER\b/)[0]
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/[,;]\s*$/, '');
+}
+/**
+ * pi reads `acceptance` as a JSON string on one line, and ignores any frontmatter key
+ * it does not know — a post-condition under a key pi has no reader for runs nowhere and
+ * says nothing about it. Emitting through the one key pi acts on is what makes the gate
+ * real rather than decorative.
+ */
+function renderAgent(name, frontmatter, skillDir, extensions) {
+    const agent = frontmatter.agent;
+    const tools = agent.tools ?? DEFAULT_TOOLS;
+    const lines = [
+        '---',
+        `name: ${name}`,
+        `description: ${JSON.stringify(agentDescription(frontmatter.description ?? name))}`,
+        `tools: ${tools}`,
+    ];
+    if (extensions.length > 0) {
+        lines.push(`extensions: ${extensions.join(', ')}`);
+    }
+    if (agent.acceptance) {
+        lines.push('acceptance:');
+        lines.push(stringify(agent.acceptance, { indent: 2 })
+            .trimEnd()
+            .split('\n')
+            .map((line) => `  ${line}`)
+            .join('\n'));
+    }
+    lines.push(`acceptanceRole: ${acceptanceRole(tools)}`);
+    if (agent.timeoutMs) {
+        lines.push(`timeoutMs: ${agent.timeoutMs}`);
+    }
+    lines.push('---', '');
+    const verify = (agent.acceptance?.verify ?? []);
+    lines.push(`Your instructions are \`${skillDir}/${name}/SKILL.md\`. Read it in full before you act, and follow it as written rather than improvising around it.`, '', 'Your caller dispatched you because this stage of the pipeline has a gate it can check, not because it wanted prose back. So the gate is the job.', '');
+    if (verify.length > 0) {
+        lines.push('You are not done until every one of these exits 0, and you have run them yourself:', '', ...verify.map((v) => `- \`${v.command}\``), '', 'A refusal is the gate working. Read what it says is wrong, fix that, and run it again — do not stop at the first one, and do not report success on a command you have not seen pass.', '');
+    }
+    lines.push('Report what you ran and what it said, what you changed, and anything in the skill that was wrong, missing or ambiguous. If you could not pass the gate, say so outright and say where you got stuck — a truthful failure is worth more to your caller than a pass it cannot trust.', '');
+    return lines.join('\n');
+}
+/**
+ * Write out an agent for every installed skill that declares one.
+ *
+ * Skills without an `agent:` block are not projected: a reference skill has no
+ * post-condition a host could check, and an agent whose acceptance is `none` is a
+ * subagent dispatched to read something the caller could have read itself.
+ */
+export async function installSkillAgents(skills, agentRoot, skillDir, update, existing, read, 
+/**
+ * Host extensions every projected agent loads, as pi resolves them.
+ *
+ * They are passed in rather than declared by the skill because they belong to
+ * whoever is running the agent, not to the instructions it follows: a sandbox
+ * fences its writers and routes their model, and the same skill run on a
+ * developer's own checkout needs neither.
+ */
+extensions = []) {
+    const written = [];
+    const skipped = [];
+    for (const name of skills) {
+        const content = await read(`${name}/SKILL.md`);
+        if (content === null)
+            continue;
+        const parsed = parseSkill(content);
+        if (!parsed?.frontmatter.agent)
+            continue;
+        const target = join(agentRoot, `${name}.md`);
+        if (existing(target) && !update) {
+            skipped.push(name);
+            continue;
+        }
+        await mkdir(agentRoot, { recursive: true });
+        await writeFile(target, renderAgent(name, parsed.frontmatter, skillDir, extensions), 'utf-8');
+        written.push(name);
+    }
+    return { written, skipped };
+}

package/dist/src/functions/commands/skills.d.ts

@@ -12,6 +12,9 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     fabric?: boolean;
     client?: boolean;
     update?: boolean;
+    agentExtensions?: string;
+    agentDir?: string;
+    agentSkillDir?: string;
 }, void, "rpc" | "session", import("#pikku/function").PikkuFunction<{
     agent?: string;
     only?: string;
@@ -19,6 +22,9 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     fabric?: boolean;
     client?: boolean;
     update?: boolean;
+    agentExtensions?: string;
+    agentDir?: string;
+    agentSkillDir?: string;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
     agent?: string;
     only?: string;
@@ -26,4 +32,7 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     fabric?: boolean;
     client?: boolean;
     update?: boolean;
+    agentExtensions?: string;
+    agentDir?: string;
+    agentSkillDir?: string;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/commands/skills.js

@@ -1,7 +1,8 @@
 import { readdir, mkdir, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { dirname, join, sep } from 'path';
+import { dirname, isAbsolute, join, sep } from 'path';
 import { listSkillFiles, listSkillNames, readSkillFile } from '@pikku/skills';
+import { installSkillAgents } from './skill-agents.js';
 import { pikkuSessionlessFunc } from '#pikku/function';
 /**
  * Write one skill's files out to `dest`, reading through @pikku/skills rather
@@ -33,6 +34,17 @@ const AGENT_SKILL_DIRS = {
     opencode: join('.opencode', 'skills'),
     pi: join('.pi', 'skills'),
 };
+/**
+ * Where a harness that dispatches subagents reads them from.
+ *
+ * Only harnesses that can enforce a post-condition are listed. Installing an agent
+ * for a harness that cannot run its `acceptance` gate ships the instruction to verify
+ * with nothing that verifies, which reads as stricter than the skill it came from
+ * while being exactly as strict.
+ */
+const AGENT_DIRS = {
+    pi: join('.pi', 'agents'),
+};
 function parseInstallGroups(frontmatter) {
     const inline = frontmatter.match(/^\s*installGroups\s*:\s*\[([^\]]*)\]/m);
     if (inline) {
@@ -118,7 +130,7 @@ export const pikkuSkillsList = pikkuSessionlessFunc({
     },
 });
 export const pikkuSkillsInstall = pikkuSessionlessFunc({
-    func: async ({ logger }, { agent = 'claude', only, core = false, fabric = false, client = false, update = false, }) => {
+    func: async ({ logger }, { agent = 'claude', only, core = false, fabric = false, client = false, update = false, agentExtensions, agentDir, agentSkillDir, }) => {
         const supportedAgents = Object.keys(AGENT_SKILL_DIRS);
         if (!supportedAgents.includes(agent)) {
             logger.error(`Agent "${agent}" is not yet supported. Supported: ${supportedAgents.join(', ')}. ` +
@@ -156,5 +168,20 @@ export const pikkuSkillsInstall = pikkuSessionlessFunc({
         logger.info(`Installed ${installed} skill(s) into ${destLabel}${skipped > 0
             ? ` (skipped ${skipped} already present — pass --update to overwrite)`
             : ''}`);
+        const agentRelative = agentDir ?? AGENT_DIRS[agent];
+        if (!agentRelative)
+            return;
+        const projected = await installSkillAgents(wanted, isAbsolute(agentRelative)
+            ? agentRelative
+            : join(process.cwd(), agentRelative), agentSkillDir ?? AGENT_SKILL_DIRS[agent].split(sep).join('/'), update, existsSync, readSkillFile, agentExtensions
+            ?.split(',')
+            .map((path) => path.trim())
+            .filter(Boolean));
+        if (projected.written.length === 0 && projected.skipped.length === 0)
+            return;
+        const agentLabel = `${agentRelative.split(sep).join('/')}/`;
+        logger.info(`Projected ${projected.written.length} agent(s) into ${agentLabel}${projected.skipped.length > 0
+            ? ` (skipped ${projected.skipped.length} already present — pass --update to overwrite)`
+            : ''}`);
     },
 });

package/dist/src/functions/db/postgres/postgres-introspector.d.ts

@@ -27,6 +27,12 @@ export declare class PostgresIntrospector implements DbIntrospector {
      */
     private getCheckEnums;
     getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;
+    /**
+     * `pk_cols` is fenced with `AS MATERIALIZED` deliberately. Referenced once,
+     * Postgres 12+ inlines it, and the constraint views it joins are then
+     * re-derived per candidate row — quadratic in the number of tables, minutes
+     * instead of milliseconds on a large schema.
+     */
     getAllColumns(): Promise<Map<string, ColumnInfo[]>>;
     getAllForeignKeys(): Promise<Map<string, ForeignKeyInfo[]>>;
     listEnums(): Promise<EnumInfo[]>;

package/dist/src/functions/db/postgres/postgres-introspector.js

@@ -167,8 +167,14 @@ export class PostgresIntrospector {
             foreignColumn: r.foreign_column_name,
         }));
     }
+    /**
+     * `pk_cols` is fenced with `AS MATERIALIZED` deliberately. Referenced once,
+     * Postgres 12+ inlines it, and the constraint views it joins are then
+     * re-derived per candidate row — quadratic in the number of tables, minutes
+     * instead of milliseconds on a large schema.
+     */
     async getAllColumns() {
-        const result = await this.client.query(`WITH pk_cols AS (
+        const result = await this.client.query(`WITH pk_cols AS MATERIALIZED (
          SELECT tc.table_schema, tc.table_name, kcu.column_name
          FROM information_schema.table_constraints tc
          JOIN information_schema.key_column_usage kcu

package/dist/src/functions/knowledge/render.d.ts

@@ -16,4 +16,4 @@ export declare const renderKnowledgePlanDefer: (_services: unknown, { ok, messag
  * rendered as a picker: this is the fallback every harness has, and one that can do
  * better reads the same answer as JSON.
  */
-export declare const renderKnowledgeReconcile: (_services: unknown, { kind, reason, note, hold, notes, question }: KnowledgeReconcileResult) => void;
+export declare const renderKnowledgeReconcile: (_services: unknown, { kind, reason, note, hold, notes, question, required, satisfied, }: KnowledgeReconcileResult) => void;

package/dist/src/functions/knowledge/render.js

@@ -1,9 +1,15 @@
 import { added, changed, dim, removed } from '../../fabric/lib/output.js';
+const ORPHANS_SHOWN = 10;
 export const renderKnowledgeValidate = (_services, { ok, notes, findings }) => {
     const errors = findings.filter((f) => f.severity === 'error');
     const warns = findings.filter((f) => f.severity === 'warn');
     const infos = findings.filter((f) => f.severity === 'info');
-    for (const finding of [...errors, ...warns, ...infos]) {
+    // Orphans are one finding each so a consumer can act on one at a time, but a
+    // project with no knowledge base yet reports every function it has — printing
+    // those in full buries the findings somebody can actually fix.
+    const orphans = infos.filter((f) => f.id.startsWith('knowledge-orphan-'));
+    const rest = infos.filter((f) => !f.id.startsWith('knowledge-orphan-'));
+    for (const finding of [...errors, ...warns, ...rest]) {
         const icon = finding.severity === 'error'
             ? removed('✗')
             : finding.severity === 'warn'
@@ -13,6 +19,18 @@ export const renderKnowledgeValidate = (_services, { ok, notes, findings }) => {
         console.log(`   ${dim('fix:')}  ${finding.fixHint}`);
         console.log();
     }
+    if (orphans.length) {
+        const shown = orphans.slice(0, ORPHANS_SHOWN);
+        console.log(`${dim('ℹ')}  ${orphans.length} thing${orphans.length !== 1 ? 's' : ''} in the code that no note describes`);
+        for (const orphan of shown) {
+            console.log(`   ${dim(orphan.id.slice('knowledge-orphan-'.length))}`);
+        }
+        if (orphans.length > shown.length) {
+            console.log(`   ${dim(`… and ${orphans.length - shown.length} more`)}`);
+        }
+        console.log(`   ${dim('fix:')}  ${shown[0].fixHint}`);
+        console.log();
+    }
     const counts = [dim(`${notes} note${notes !== 1 ? 's' : ''}`)];
     if (errors.length) {
         counts.push(removed(`${errors.length} error${errors.length !== 1 ? 's' : ''}`));
@@ -148,7 +166,12 @@ export const renderKnowledgePlanDefer = (_services, { ok, message }) => {
  * rendered as a picker: this is the fallback every harness has, and one that can do
  * better reads the same answer as JSON.
  */
-export const renderKnowledgeReconcile = (_services, { kind, reason, note, hold, notes, question }) => {
+export const renderKnowledgeReconcile = (_services, { kind, reason, note, hold, notes, question, required, satisfied, }) => {
+    if (required && !satisfied) {
+        process.exitCode = 1;
+        console.log(`${removed('✗')}  next is ${kind}, and this check requires ${required.join(' or ')}`);
+        console.log();
+    }
     if (kind === 'idle') {
         console.log(`${dim('=')}  ${dim(reason)}`);
         return;

package/dist/src/functions/knowledge/schemas.d.ts

@@ -94,7 +94,9 @@ export declare const KnowledgePlanDeferOutputSchema: import("zod").ZodObject<{
     path: import("zod").ZodString;
     message: import("zod").ZodString;
 }, import("zod/v4/core").$strip>;
-export declare const KnowledgeReconcileInputSchema: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
+export declare const KnowledgeReconcileInputSchema: import("zod").ZodObject<{
+    require: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
 export declare const KnowledgeReconcileOutputSchema: import("zod").ZodObject<{
     kind: import("zod").ZodEnum<{
         "ask-user": "ask-user";
@@ -116,4 +118,6 @@ export declare const KnowledgeReconcileOutputSchema: import("zod").ZodObject<{
             description: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strip>>>;
     }, import("zod/v4/core").$strip>>;
+    satisfied: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    required: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
 }, import("zod/v4/core").$strip>;

package/dist/src/functions/wirings/mcp/pikku-command-mcp-json.js

@@ -1,16 +1,43 @@
 import { pikkuSessionlessFunc } from '#pikku/function';
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'path';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { mcpSurfaceSlug } from '../../../utils/mcp-surface.js';
 import { serializeMCPJson } from '@pikku/inspector';
 export const pikkuMCPJSON = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const state = await getInspectorState();
         const mcpJsonFile = config.mcpJsonFile ?? config.clientFiles?.mcpJsonFile;
-        if (mcpJsonFile) {
-            const mcpJson = serializeMCPJson(logger, state);
-            await writeFileInDir(logger, mcpJsonFile, mcpJson, {
-                ignoreModifyComment: true,
-            });
+        if (!mcpJsonFile) {
+            return;
+        }
+        await writeFileInDir(logger, mcpJsonFile, serializeMCPJson(logger, state), {
+            ignoreModifyComment: true,
+        });
+        // A project serving several MCP endpoints gets one manifest per endpoint,
+        // named after its surface, beside the default one. `deploy-apply` finds
+        // each by the slug in its unit's name, so the slug has to be built the
+        // same way here as it is in the analyzer.
+        const mcpDir = dirname(mcpJsonFile);
+        const surfaces = state.mcpEndpoints.surfaces ?? {};
+        const written = new Set();
+        for (const surface of Object.keys(surfaces)) {
+            const name = `mcp.${mcpSurfaceSlug(surface)}.gen.json`;
+            written.add(name);
+            await writeFileInDir(logger, join(mcpDir, name), serializeMCPJson(logger, state, surface), { ignoreModifyComment: true });
+        }
+        // A surface that has gone away leaves its manifest behind, and `pikku dev`
+        // mounts every manifest it finds — so without this, dropping `mcpEndpoint`
+        // keeps serving the endpoint it was supposed to remove, with whatever tool
+        // list it had on the last run that still wrote it.
+        if (existsSync(mcpDir)) {
+            for (const name of readdirSync(mcpDir)) {
+                if (!/^mcp\..+\.gen\.json$/.test(name) || written.has(name))
+                    continue;
+                logger.debug(`Removing manifest for a surface that no longer exists: ${name}`);
+                rmSync(join(mcpDir, name));
+            }
         }
     },
     middleware: [

package/dist/src/server/bun-server-runner.js

@@ -27,6 +27,7 @@ export class BunServerRunner {
             // Read off this options object by the transport, not off `config` — so it
             // has to be forwarded here explicitly, exactly like the JWT above.
             mcpJson: options.mcpJson,
+            mcpSurfaces: options.mcpSurfaces,
         });
     }
 }

package/dist/src/server/dev-server-runner.interface.d.ts

@@ -45,6 +45,19 @@ export type DevServerOptions = {
         resources?: unknown[];
         prompts?: unknown[];
     };
+    /**
+     * The further MCP endpoints this project serves, one per surface, each with
+     * the path it answers on. Forwarded the same way and with the same
+     * consequence for forgetting: the surface 404s with no error anywhere.
+     */
+    mcpSurfaces?: Array<{
+        mcpJson: {
+            tools?: unknown[];
+            resources?: unknown[];
+            prompts?: unknown[];
+        };
+        mcpPath: string;
+    }>;
 };
 export interface DevServerRunner {
     /**

package/dist/src/server/node-server-runner.js

@@ -47,6 +47,7 @@ export class NodeServerRunner {
             // Read off this options object by the transport, not off `config` — so it
             // has to be forwarded here explicitly, exactly like the JWT above.
             mcpJson: options.mcpJson,
+            mcpSurfaces: options.mcpSurfaces,
         });
         return {
             init: () => server.init(),

package/dist/src/utils/mcp-surface.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The slug a surface's manifest filename and its deploy unit name are both
+ * built from. `deploy-apply` recovers the filename by stripping `mcp-` off the
+ * unit name, so codegen and the analyzer have to agree on it exactly or a
+ * deployed unit reads a manifest nobody wrote — hence one function, not the
+ * same expression written twice.
+ */
+export declare const mcpSurfaceSlug: (surface: string) => string;

package/dist/src/utils/mcp-surface.js

@@ -0,0 +1,9 @@
+import { toSafeKebab } from '../deploy/analyzer/naming.js';
+/**
+ * The slug a surface's manifest filename and its deploy unit name are both
+ * built from. `deploy-apply` recovers the filename by stripping `mcp-` off the
+ * unit name, so codegen and the analyzer have to agree on it exactly or a
+ * deployed unit reads a manifest nobody wrote — hence one function, not the
+ * same expression written twice.
+ */
+export const mcpSurfaceSlug = (surface) => toSafeKebab(surface);