@pikku/cli 0.12.100 → 0.12.102

package/dist/src/functions/validate/validate-registry.d.ts

@@ -0,0 +1,52 @@
+import type { ValidateFinding as Finding } from './persona-checks.js';
+export type ValidateTarget = {
+    /** Absolute directory the check runs against. */
+    dir: string;
+    /** How the target is named in output — repo-relative, or "." for the root. */
+    label: string;
+};
+/**
+ * A check plus the condition under which it means anything.
+ *
+ * `pikku validate` runs every check whose precondition holds, wherever it
+ * holds. It deliberately does not detect a project *kind* and then dispatch:
+ * the repos that motivated this are several kinds at once — the addons
+ * monorepo is a workspace containing 217 publishable addons — and any
+ * single-kind guess is wrong for them. Preconditions compose where a mode
+ * would have had to pick.
+ */
+export type ValidateCheck = {
+    id: string;
+    /** What this check is for, shown when reporting what ran. */
+    subject: string;
+    applies: (target: ValidateTarget) => Promise<boolean>;
+    run: (target: ValidateTarget) => Promise<Finding[]>;
+};
+/**
+ * Every directory under `root` that holds a package.json.
+ *
+ * Walking beats reading the `workspaces` globs: the field is an array in one
+ * repo and `{ packages: [...] }` in the next, spells the same layout as
+ * `packages/**` or as six explicit globs, and a package that is real but
+ * unlisted is exactly the kind of thing worth validating. Over-collecting is
+ * harmless here because the preconditions decide what actually runs.
+ */
+export declare function discoverTargets(root: string, maxDepth?: number): Promise<ValidateTarget[]>;
+export declare const CHECKS: ValidateCheck[];
+export type ValidationPlan = Array<{
+    check: ValidateCheck;
+    target: ValidateTarget;
+}>;
+export declare function planValidation(root: string): Promise<ValidationPlan>;
+export type ValidateReport = {
+    ok: boolean;
+    root: string;
+    /** What ran, so a clean result can say what it actually looked at. */
+    ran: Array<{
+        checkId: string;
+        subject: string;
+        target: string;
+    }>;
+    findings: Finding[];
+};
+export declare function runValidate(root: string): Promise<ValidateReport>;

package/dist/src/functions/validate/validate-registry.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { isAddonPackage, runAddonPackageChecks, } from './addon-package-checks.js';
+import { runSharedProjectChecks } from './shared-checks.js';
+/** A hand-written `types/application-types.d.ts` beside package.json. */
+const ADDON_MARKER = join('types', 'application-types.d.ts');
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.pikku',
+    '.pikku-runtime',
+    'coverage',
+    '.next',
+    '.yarn',
+]);
+/**
+ * Every directory under `root` that holds a package.json.
+ *
+ * Walking beats reading the `workspaces` globs: the field is an array in one
+ * repo and `{ packages: [...] }` in the next, spells the same layout as
+ * `packages/**` or as six explicit globs, and a package that is real but
+ * unlisted is exactly the kind of thing worth validating. Over-collecting is
+ * harmless here because the preconditions decide what actually runs.
+ */
+export async function discoverTargets(root, maxDepth = 5) {
+    const targets = [];
+    const visit = async (dir, depth) => {
+        if (existsSync(join(dir, 'package.json'))) {
+            targets.push({ dir, label: relative(root, dir) || '.' });
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
+                continue;
+            await visit(join(dir, entry.name), depth + 1);
+        }
+    };
+    await visit(root, 0);
+    return targets;
+}
+export const CHECKS = [
+    {
+        id: 'app-project',
+        subject: 'app project',
+        // An addon also carries a pikku.config.json, and running the app-shaped
+        // checks against one reports every app convention it has no reason to
+        // follow — starting with a packages/functions/ it will never have.
+        applies: async ({ dir }) => existsSync(join(dir, 'pikku.config.json')) &&
+            !existsSync(join(dir, ADDON_MARKER)),
+        run: async ({ dir }) => (await runSharedProjectChecks(dir)).findings,
+    },
+    {
+        id: 'addon-package',
+        subject: 'addon',
+        applies: async ({ dir }) => isAddonPackage(dir),
+        run: async ({ dir }) => runAddonPackageChecks(dir),
+    },
+];
+export async function planValidation(root) {
+    const plan = [];
+    for (const target of await discoverTargets(root)) {
+        for (const check of CHECKS) {
+            if (await check.applies(target))
+                plan.push({ check, target });
+        }
+    }
+    return plan;
+}
+export async function runValidate(root) {
+    const plan = await planValidation(root);
+    const findings = [];
+    const ran = [];
+    for (const { check, target } of plan) {
+        findings.push(...(await check.run(target)));
+        ran.push({
+            checkId: check.id,
+            subject: check.subject,
+            target: target.label,
+        });
+    }
+    return {
+        ok: !findings.some((f) => f.severity === 'error'),
+        root,
+        ran,
+        findings,
+    };
+}

package/dist/src/functions/validate/validate.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export { readJsonSafe, readTextSafe } from './shared-checks.js';
+export declare const FindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    severity: z.ZodEnum<{
+        warn: "warn";
+        error: "error";
+        info: "info";
+    }>;
+    message: z.ZodString;
+    path: z.ZodString;
+    fixHint: z.ZodString;
+}, z.core.$strip>;
+export type Finding = z.infer<typeof FindingSchema>;
+export declare const ValidateInput: z.ZodObject<{}, z.core.$strip>;
+export declare const ValidateOutput: z.ZodObject<{
+    ok: z.ZodBoolean;
+    root: z.ZodString;
+    ran: z.ZodArray<z.ZodObject<{
+        checkId: z.ZodString;
+        subject: z.ZodString;
+        target: z.ZodString;
+    }, z.core.$strip>>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            warn: "warn";
+            error: "error";
+            info: "info";
+        }>;
+        message: z.ZodString;
+        path: z.ZodString;
+        fixHint: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The workspace root, or failing that the package the caller is standing in.
+ *
+ * A standalone publishable addon has no `workspaces` anywhere above it, and
+ * running from its `src/` would otherwise validate `src/` — a directory with no
+ * package.json, where every check's precondition is false and the run reports
+ * that nothing applied. The addon author is exactly who the addon checks are
+ * for, so the nearest package.json is the answer when no workspace claims it.
+ */
+export declare function findProjectRoot(startDir: string): Promise<string>;
+export declare function runProjectValidate(startDir?: string): Promise<z.infer<typeof ValidateOutput>>;
+export declare const renderValidate: (_s: unknown, { ok, root, ran, findings }: z.infer<typeof ValidateOutput>) => void;

package/dist/src/functions/validate/{workspace-validate.js → validate.js}

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { added, changed, dim, removed } from '../../fabric/lib/output.js';
-import { runSharedProjectChecks } from './shared-checks.js';
+import { runValidate } from './validate-registry.js';
 export { readJsonSafe, readTextSafe } from './shared-checks.js';
 export const FindingSchema = z.object({
     id: z.string(),
@@ -12,16 +12,32 @@ export const FindingSchema = z.object({
     path: z.string(),
     fixHint: z.string(),
 });
-export const WorkspaceValidateInput = z.object({});
-export const WorkspaceValidateOutput = z.object({
+export const ValidateInput = z.object({});
+export const ValidateOutput = z.object({
     ok: z.boolean(),
     root: z.string(),
+    ran: z.array(z.object({
+        checkId: z.string(),
+        subject: z.string(),
+        target: z.string(),
+    })),
     findings: z.array(FindingSchema),
 });
+/**
+ * The workspace root, or failing that the package the caller is standing in.
+ *
+ * A standalone publishable addon has no `workspaces` anywhere above it, and
+ * running from its `src/` would otherwise validate `src/` — a directory with no
+ * package.json, where every check's precondition is false and the run reports
+ * that nothing applied. The addon author is exactly who the addon checks are
+ * for, so the nearest package.json is the answer when no workspace claims it.
+ */
 export async function findProjectRoot(startDir) {
     let dir = startDir;
+    let nearestPackage;
     while (true) {
         if (existsSync(join(dir, 'package.json'))) {
+            nearestPackage ??= dir;
             try {
                 const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
                 if (pkg.workspaces)
@@ -33,19 +49,37 @@ export async function findProjectRoot(startDir) {
         }
         const parent = dirname(dir);
         if (parent === dir)
-            return startDir;
+            return nearestPackage ?? startDir;
         dir = parent;
     }
 }
-export async function runWorkspaceValidate(startDir = process.cwd()) {
+export async function runProjectValidate(startDir = process.cwd()) {
     const root = await findProjectRoot(startDir);
-    const { findings } = await runSharedProjectChecks(root);
-    const ok = !findings.some((f) => f.severity === 'error');
-    return { ok, root, findings };
+    return runValidate(root);
 }
-export const renderWorkspaceValidate = (_s, { ok, root, findings }) => {
+/** "2 addons, 1 app project" — what the run actually looked at. */
+function describeRan(ran) {
+    const bySubject = new Map();
+    for (const entry of ran) {
+        bySubject.set(entry.subject, (bySubject.get(entry.subject) ?? 0) + 1);
+    }
+    return [...bySubject]
+        .map(([subject, count]) => `${count} ${subject}${count === 1 ? '' : 's'}`)
+        .join(', ');
+}
+export const renderValidate = (_s, { ok, root, ran, findings }) => {
+    // A green tick for a run that checked nothing is the one outcome worth
+    // guarding against: auto-detection that finds nothing looks identical to
+    // auto-detection that found everything and liked it.
+    if (ran.length === 0) {
+        console.log(changed('⚠') +
+            '  ' +
+            'Nothing to validate here — no app project and no publishable addon found');
+        console.log(`   ${dim('fix:')}    Run from a directory with a pikku.config.json, or from a package that publishes generated pikku output.`);
+        return;
+    }
     if (findings.length === 0) {
-        console.log(added('✓  All checks passed — workspace is Pikku-compatible'));
+        console.log(added(`✓  All checks passed — checked ${describeRan(ran)}`));
         return;
     }
     const relPath = (p) => p.startsWith(root + '/') || p.startsWith(root + '\\')
@@ -76,9 +110,9 @@ export const renderWorkspaceValidate = (_s, { ok, root, findings }) => {
         counts.push(dim(`${infos.length} info${infos.length !== 1 ? 's' : ''}`));
     }
     console.log('─'.repeat(40));
-    console.log(counts.join('  '));
+    console.log(`${counts.join('  ')}  ${dim(`across ${describeRan(ran)}`)}`);
     if (ok) {
         console.log();
-        console.log(added('✓') + '  ' + dim('no errors — workspace is structurally sound'));
+        console.log(added('✓') + '  ' + dim('no errors'));
     }
 };

package/dist/src/functions/wirings/ai-agent/pikku-command-ai-agent-types.js

@@ -5,11 +5,12 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializeAIAgentTypes } from './serialize-ai-agent-types.js';
 export const pikkuAIAgentTypes = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
-        const { agentTypesFile, functionTypesFile, agentMapDeclarationFile, scopesFile, packageMappings, } = config;
+        const { agentTypesFile, functionTypesFile, agentMapDeclarationFile, scorerNamesDeclarationFile, scopesFile, packageMappings, } = config;
         const functionTypesImportPath = getFileImportRelativePath(agentTypesFile, functionTypesFile, packageMappings);
         const agentMapImportPath = getFileImportRelativePath(agentTypesFile, agentMapDeclarationFile, packageMappings);
         const scopesImportPath = getFileImportRelativePath(agentTypesFile, scopesFile, packageMappings);
-        const content = serializeAIAgentTypes(functionTypesImportPath, agentMapImportPath, scopesImportPath);
+        const scorerNamesImportPath = getFileImportRelativePath(agentTypesFile, scorerNamesDeclarationFile, packageMappings);
+        const content = serializeAIAgentTypes(functionTypesImportPath, agentMapImportPath, scopesImportPath, scorerNamesImportPath);
         await writeFileInDir(logger, agentTypesFile, content);
     },
     middleware: [

package/dist/src/functions/wirings/ai-agent/pikku-command-ai-agent.js

@@ -4,11 +4,15 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
 import { serializeAgentMap } from './serialize-agent-map.js';
+import { serializeModelAliases } from './serialize-model-aliases.js';
 export const pikkuAIAgent = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const { agents, functions } = await getInspectorState();
-        const { agentWiringsFile, agentWiringMetaFile, agentWiringMetaJsonFile, agentMapDeclarationFile, packageMappings, schema, addonName, } = config;
+        const { agentWiringsFile, agentWiringMetaFile, agentWiringMetaJsonFile, agentMapDeclarationFile, modelAliasesFile, packageMappings, schema, addonName, models, } = config;
         const agentFiles = agents.files;
+        // Written even with no agents: the image/speech/embedding runner methods
+        // take a model too.
+        await writeFileInDir(logger, modelAliasesFile, serializeModelAliases(models, addonName ?? null));
         if (agentFiles.size === 0 || Object.keys(agents.agentsMeta).length === 0) {
             // Still need to generate an empty agent map for the types import
             await writeFileInDir(logger, agentMapDeclarationFile, `export type AgentMap = {}\n`);

package/dist/src/functions/wirings/ai-agent/serialize-ai-agent-types.d.ts

@@ -1 +1 @@
-export declare const serializeAIAgentTypes: (functionTypesImportPath: string, agentMapImportPath: string, scopesImportPath: string) => string;
+export declare const serializeAIAgentTypes: (functionTypesImportPath: string, agentMapImportPath: string, scopesImportPath: string, scorerNamesImportPath: string) => string;

package/dist/src/functions/wirings/ai-agent/serialize-ai-agent-types.js

@@ -1,4 +1,4 @@
-export const serializeAIAgentTypes = (functionTypesImportPath, agentMapImportPath, scopesImportPath) => {
+export const serializeAIAgentTypes = (functionTypesImportPath, agentMapImportPath, scopesImportPath, scorerNamesImportPath) => {
     return `import {
   CoreAIAgent,
   PikkuAIMiddlewareHooks,
@@ -9,16 +9,21 @@ import {
   agentResume as coreAgentResume,
   agentApprove as coreAgentApprove,
 } from '@pikku/core/ai-agent'
+import {
+  pikkuAIScorer as corePikkuAIScorer,
+  pikkuAIJudge as corePikkuAIJudge,
+} from '@pikku/core/ai-scorer'
 import type { PikkuPermission, PikkuMiddleware, Services, PikkuFunctionConfig } from '${functionTypesImportPath}'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { AIAgentMemoryConfig, AIAgentInput } from '@pikku/core/ai-agent'
 import type { AgentMap } from '${agentMapImportPath}'
 import type { ScopeId } from '${scopesImportPath}'
+import type { ScorerName } from '${scorerNamesImportPath}'
 
 type AIAgentConfig<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
-> = Omit<CoreAIAgent<PikkuPermission, PikkuMiddleware, ScopeId>, 'tools' | 'agents' | 'workflows' | 'memory' | 'input' | 'output'> & {
+> = Omit<CoreAIAgent<PikkuPermission, PikkuMiddleware, ScopeId, ScorerName>, 'tools' | 'agents' | 'workflows' | 'memory' | 'input' | 'output'> & {
   input?: InputSchema
   output?: OutputSchema
   memory?: Omit<AIAgentMemoryConfig, 'workingMemory'> & { workingMemory?: StandardSchemaV1 }
@@ -36,6 +41,14 @@ export const pikkuAIAgent = <
   return agent
 }
 
+export const pikkuAIScorer = (
+  config: Parameters<typeof corePikkuAIScorer<Services>>[0]
+) => corePikkuAIScorer<Services>(config)
+
+export const pikkuAIJudge = (
+  config: Parameters<typeof corePikkuAIJudge<Services>>[0]
+) => corePikkuAIJudge<Services>(config)
+
 export const pikkuAIMiddleware = <
   State extends Record<string, unknown> = Record<string, unknown>,
   RequiredServices extends Services = Services,

package/dist/src/functions/wirings/ai-agent/serialize-model-aliases.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Bakes the `models` alias table into pikku state. Generated rather than read
+ * at runtime: a deployed unit never sees pikku.config.json.
+ */
+export declare const serializeModelAliases: (models: Record<string, string> | undefined, addonName: string | null) => string;

package/dist/src/functions/wirings/ai-agent/serialize-model-aliases.js

@@ -0,0 +1,12 @@
+/**
+ * Bakes the `models` alias table into pikku state. Generated rather than read
+ * at runtime: a deployed unit never sees pikku.config.json.
+ */
+export const serializeModelAliases = (models, addonName) => {
+    const packageArg = addonName ? `'${addonName}'` : 'null';
+    const table = JSON.stringify(models ?? {}, null, 2);
+    return `import { pikkuState } from '@pikku/core/ecosystem'
+
+pikkuState(${packageArg}, 'agent', 'modelAliases', ${table})
+`;
+};

package/dist/src/functions/wirings/ai-scorer/pikku-command-ai-scorer.d.ts

@@ -0,0 +1 @@
+export declare const pikkuAIScorer: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/ai-scorer/pikku-command-ai-scorer.js

@@ -0,0 +1,51 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { serializeScorerNames } from './serialize-scorer-names.js';
+export const pikkuAIScorer = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }) => {
+        const { scorers } = await getInspectorState();
+        const { scorerWiringsFile, scorerWiringMetaFile, scorerWiringMetaJsonFile, scorerNamesDeclarationFile, packageMappings, schema, addonName, } = config;
+        const scorerFiles = scorers.files;
+        // Written even when empty: the agent types file imports ScorerName
+        // unconditionally, so a project with no scorers still has to typecheck.
+        await writeFileInDir(logger, scorerNamesDeclarationFile, serializeScorerNames(scorers.scorersMeta));
+        if (scorerFiles.size === 0 ||
+            Object.keys(scorers.scorersMeta).length === 0) {
+            return undefined;
+        }
+        const lines = [];
+        lines.push(`import { addAIScorer } from '@pikku/core/ai-scorer'`);
+        // Ahead of the registrations: addAIScorer refuses a scorer whose metadata
+        // has not landed yet.
+        lines.push(`import '${getFileImportRelativePath(scorerWiringsFile, scorerWiringMetaFile, packageMappings)}'`);
+        const sortedScorers = Array.from(scorerFiles.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+        for (const [, { path, exportedName }] of sortedScorers) {
+            const importPath = getFileImportRelativePath(scorerWiringsFile, path, packageMappings);
+            lines.push(`import { ${exportedName} } from '${importPath}'`);
+        }
+        lines.push('');
+        const packageArg = addonName ? `, '${addonName}'` : '';
+        for (const [scorerName, { exportedName }] of sortedScorers) {
+            lines.push(`addAIScorer('${scorerName}', ${exportedName}${packageArg})`);
+        }
+        await writeFileInDir(logger, scorerWiringsFile, lines.join('\n'));
+        await writeFileInDir(logger, scorerWiringMetaJsonFile, JSON.stringify({ scorersMeta: scorers.scorersMeta }, null, 2));
+        const jsonImportPath = getFileImportRelativePath(scorerWiringMetaFile, scorerWiringMetaJsonFile, packageMappings);
+        const importStatement = schema?.supportsImportAttributes
+            ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
+            : `import metaData from '${jsonImportPath}'`;
+        await writeFileInDir(logger, scorerWiringMetaFile, `import { pikkuState } from '@pikku/core/ecosystem'
+import type { ScorerMeta } from '@pikku/core/ai-scorer'
+${importStatement}
+pikkuState(${addonName ? `'${addonName}'` : 'null'}, 'agent', 'scorersMeta', metaData.scorersMeta as ScorerMeta)`);
+        return true;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Finding AI scorers',
+            commandEnd: 'Found AI scorers',
+        }),
+    ],
+});

package/dist/src/functions/wirings/ai-scorer/serialize-scorer-names.d.ts

@@ -0,0 +1,10 @@
+import type { ScorerMeta } from '@pikku/core/ai-scorer';
+/**
+ * The names an agent may ask to be graded by.
+ *
+ * Emitted even when there are none — the agent types file imports it
+ * unconditionally, so a project with no scorers still has to typecheck. `never`
+ * is what makes `scorers: ['typo']` a type error there rather than a silent
+ * no-op at runtime.
+ */
+export declare const serializeScorerNames: (scorersMeta: ScorerMeta) => string;

package/dist/src/functions/wirings/ai-scorer/serialize-scorer-names.js

@@ -0,0 +1,17 @@
+/**
+ * The names an agent may ask to be graded by.
+ *
+ * Emitted even when there are none — the agent types file imports it
+ * unconditionally, so a project with no scorers still has to typecheck. `never`
+ * is what makes `scorers: ['typo']` a type error there rather than a silent
+ * no-op at runtime.
+ */
+export const serializeScorerNames = (scorersMeta) => {
+    const names = Object.keys(scorersMeta).sort();
+    return `/**
+ * The AI scorers declared in this project.
+ */
+
+export type ScorerName = ${names.length === 0 ? 'never' : names.map((name) => `'${name}'`).join(' | ')}
+`;
+};

package/dist/src/functions/wirings/auth/serialize-auth-gen.js

@@ -36,10 +36,12 @@ function variableSchemaName(name, field) {
 // External consoles (served from another origin) cannot carry the session
 // cookie, so they authenticate with 'Authorization: Bearer <PIKKU_CONSOLE_TOKEN>'.
 // The expected token resolves through the secrets service per request and the
-// middleware is a no-op while the secret is unset. Emitted into the same
-// addHTTPMiddleware('*') call as the session middleware: the inspector keys
-// route-middleware groups by pattern, so a second '*' registration from another
-// file would silently displace this one in deployed units.
+// middleware is a no-op while the secret is unset. Emitted alongside the session
+// middleware in one addGlobalMiddleware call. This used to be an
+// addHTTPMiddleware('*') call and had to be a single one, because the inspector
+// keys route-middleware groups by pattern and a second '*' registration would
+// silently displace it; global middleware is an append-only list, so that
+// hazard is gone.
 //
 // The session carries the two scope roots the console addon gates itself on.
 // Without them this token authenticates but authorizes nothing: `wireAddon`
@@ -157,7 +159,7 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
         '// AUTO-GENERATED by pikku CLI — do not edit',
         '',
         emitStatefulSession
-            ? `import { pikkuSessionlessFunc, wireHTTPRoutes, addHTTPMiddleware } from '${pikkuTypesImportPath}'`
+            ? `import { pikkuSessionlessFunc, wireHTTPRoutes } from '${pikkuTypesImportPath}'\nimport { addGlobalMiddleware } from '@pikku/core/middleware'`
             : `import { pikkuSessionlessFunc, wireHTTPRoutes } from '${pikkuTypesImportPath}'`,
         emitStatefulSession
             ? `import { createAuthHandler, betterAuthSession } from '@pikku/better-auth'`
@@ -183,10 +185,10 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
         // Stateful: betterAuthSession calls services.auth(), so it stays here with
         // the auth.wiring import.
         if (includeConsoleToken) {
-            wiring.push(`addHTTPMiddleware('*', [`, `  betterAuthSession(),`, ...consoleTokenMiddlewareLines(), `])`, '');
+            wiring.push(`addGlobalMiddleware([`, `  betterAuthSession(),`, ...consoleTokenMiddlewareLines(), `])`, '');
         }
         else {
-            wiring.push(`addHTTPMiddleware('*', [betterAuthSession()])`, '');
+            wiring.push(`addGlobalMiddleware([betterAuthSession()])`, '');
         }
     }
     // `pikku` tag marks these as scaffold plumbing (not user-authored wiring) so
@@ -208,10 +210,25 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
     if (stateless) {
         // Stateless session middleware in its own file — imports neither auth.wiring
         // nor the better-auth server, so every unit's bootstrap stays lean.
+        // Global, not `addHTTPMiddleware('*')`.
+        //
+        // Both entries resolve a session from whatever request the call arrived on;
+        // neither is an HTTP routing concern. Registered as HTTP middleware they ran
+        // for HTTP wirings alone, so an MCP tool fronting a session-requiring
+        // function could only answer 'Authentication required' however the caller
+        // authenticated — the cookie was sent and never looked at.
+        //
+        // Wirings that carry no request are unaffected: every one of these opens
+        // with `if (!http?.request) return`, so queue, scheduler and CLI invocations
+        // pass straight through as before.
+        //
+        // This also retires the displacement hazard that kept both entries in one
+        // call — global middleware is a list rather than a map keyed by route
+        // pattern, so a second registration appends instead of overwriting.
         const middleware = [
             '// AUTO-GENERATED by pikku CLI — do not edit',
             '',
-            `import { addHTTPMiddleware } from '${pikkuTypesImportPath}'`,
+            `import { addGlobalMiddleware } from '@pikku/core/middleware'`,
             `import { betterAuthStatelessSession } from '@pikku/better-auth'`,
             ...(includeConsoleToken
                 ? [`import { authBearer } from '@pikku/core/middleware'`]
@@ -219,12 +236,12 @@ export const serializeAuthGen = (definition, providers, authFile, typesDeclarati
             '',
             ...(includeConsoleToken
                 ? [
-                    `addHTTPMiddleware('*', [`,
+                    `addGlobalMiddleware([`,
                     `  betterAuthStatelessSession(),`,
                     ...consoleTokenMiddlewareLines(),
                     `])`,
                 ]
-                : [`addHTTPMiddleware('*', [betterAuthStatelessSession()])`]),
+                : [`addGlobalMiddleware([betterAuthStatelessSession()])`]),
             '',
         ];
         output.middleware = middleware.join('\n');

package/dist/src/functions/wirings/cli/serialize-channel-cli.js

@@ -61,7 +61,7 @@ import { wireChannel } from '${channelTypesPath}'
 import { pikkuMiddleware${hasAddonFuncs ? ', ref' : ''}, pikkuSessionlessFunc } from '${functionTypesPath}'
 import { generateCommandHelp } from '@pikku/core/cli'
 import { handleRawCLI, type RawCLIFrame } from '@pikku/core/cli/channel'
-import { pikkuState } from '@pikku/core/ecosystem'
+import { pikkuState, getSingletonServices, getCreateWireServices } from '@pikku/core/ecosystem'
 ${imports}
 
 // Middleware to close the channel after CLI command completes
@@ -108,12 +108,17 @@ export const cliHelp = pikkuSessionlessFunc<{ args?: string[] }, { help: string
  */
 export const cliRaw = pikkuSessionlessFunc<{ args: string[] }, RawCLIFrame>({
   auth: false,
-  func: async (services, data: { args: string[] }, { channel, session }) => {
+  func: async (_services, data: { args: string[] }, { channel, session }) => {
     const { help, result, error, exitCode, commandId } = await handleRawCLI({
       programName: '${programName}',
       args: data.args,
-      singletonServices: services as any,
-      createWireServices: pikkuState(null, 'package', 'factories')?.createWireServices,
+      // The singletons, not this function's own view of them: a function body
+      // is handed \`secrets\` as a throwing accessor, and passing that down
+      // would strip every command run on this channel of a service its
+      // middleware is entitled to. Each command is stripped again by its own
+      // runner, so nothing gains access it would not have over HTTP.
+      singletonServices: getSingletonServices() as any,
+      createWireServices: getCreateWireServices(),
       // The connection authenticated during its upgrade — commands run as it.
       session,
       // The socket the command arrived on, so \`channel.remote(...)\` inside a