@pikku/cli 0.12.100 → 0.12.102

package/dist/src/functions/wirings/console/serialize-console-functions.js

@@ -5,13 +5,6 @@ export const serializeConsoleFunctions = (pathToPikkuTypes, _pathToAgentTypes, g
  */
 import { z } from 'zod'
 
-export const SecretRef = z.object({ secretId: z.string() })
-
-export const SetSecret = z.object({
-  secretId: z.string(),
-  value: z.unknown(),
-})
-
 export const VariableRef = z.object({ variableId: z.string() })
 
 export const SetVariable = z.object({
@@ -24,34 +17,16 @@ export const ValueResult = z.object({
   value: z.unknown().nullable(),
 })
 
-export const Exists = z.object({ exists: z.boolean() })
-
 export const Success = z.object({ success: z.boolean() })
 `;
     const functions = `import { pikkuFunc, defineHTTPRoutes, wireHTTPRoutes, ref, wireAddon } from '${pathToPikkuTypes}'
 import {
-  SecretRef,
-  SetSecret,
   VariableRef,
   SetVariable,
   ValueResult,
-  Exists,
   Success,
 } from './console.schemas.gen.js'
 
-export const pikkuConsoleSetSecret = pikkuFunc({
-  secretBroker: true,
-  tags: ['pikku'],
-  description: 'Set the value of a secret',
-  expose: true,
-  input: SetSecret,
-  output: Success,
-  func: async ({ secrets }, { secretId, value }) => {
-    await secrets.setSecret(secretId, value)
-    return { success: true }
-  },
-})
-
 export const pikkuConsoleGetVariable = pikkuFunc({
   tags: ['pikku'],
   description: 'Get the current value of a variable',
@@ -89,36 +64,6 @@ export const pikkuConsoleSetVariable = pikkuFunc({
   },
 })
 
-export const pikkuConsoleHasSecret = pikkuFunc({
-  secretBroker: true,
-  tags: ['pikku'],
-  description: 'Check if a secret exists without reading its value',
-  expose: true,
-  input: SecretRef,
-  output: Exists,
-  func: async ({ secrets }, { secretId }) => {
-    const exists = await secrets.hasSecret(secretId)
-    return { exists }
-  },
-})
-
-export const pikkuConsoleGetSecret = pikkuFunc({
-  secretBroker: true,
-  tags: ['pikku'],
-  description: 'Get the current value of a secret',
-  expose: true,
-  input: SecretRef,
-  output: ValueResult,
-  func: async ({ secrets }, { secretId }) => {
-    const exists = await secrets.hasSecret(secretId)
-    if (!exists) {
-      return { exists: false, value: null }
-    }
-    const value = await secrets.getSecret(secretId)
-    return { exists: true, value: value.reveal() }
-  },
-})
-
 export const consoleRoutes = defineHTTPRoutes({
   auth: false,
   tags: ['pikku'],
@@ -132,7 +77,15 @@ export const consoleRoutes = defineHTTPRoutes({
   },
 })
 
-wireAddon({ name: 'console', package: '@pikku/addon-console', scopes: ['admin'] })
+wireAddon({
+  name: 'console',
+  package: '@pikku/addon-console',
+  scopes: ['admin'],
+  globalSecrets:
+    'the console administers secrets an operator names at runtime, so no static declaration can cover them',
+  globalCredentials:
+    'the console lists and links credentials across every user, so it cannot be scoped to a declared set',
+})
 wireHTTPRoutes({ basePath: '${globalHTTPPrefix}', routes: { console: consoleRoutes } })
 `;
     return { schemas, functions };

package/dist/src/functions/wirings/functions/serialize-function-types.js

@@ -15,7 +15,7 @@ export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeNam
  * Core function, middleware, and permission types for all wirings
  */
 
-import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired, SecretlessServices, SecretService } from '@pikku/core'
+import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired, SecretlessServices } from '@pikku/core'
 import type { CorePikkuFunctionConfig, CorePikkuSessionlessFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
 import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
 import {
@@ -56,16 +56,6 @@ export type WiredServices = SecretlessServices<RequiredSingletonServices & Servi
 /** \`WiredSingletonServices\` without \`secrets\`, for auth gates. */
 export type WiredAuthServices = SecretlessServices<WiredSingletonServices>
 
-/**
- * \`WiredServices\` with \`secrets\` restored, for the console's secret-admin
- * functions. Reached by declaring \`secretBroker: true\` on a \`pikkuFunc\` config.
- *
- * Declaring it does not grant the service. The runner hands out the real
- * \`SecretService\` only to the functions the inspector marks as secret brokers;
- * every other function still receives the throwing accessor.
- */
-export type WiredSecretBrokerServices = WiredServices & { secrets: SecretService }
-
 /**
  * Inline node configuration for function definitions.
  */
@@ -301,15 +291,10 @@ export const pikkuApprovalDescription = <In = unknown, RequiredServices extends
  * @template In - The input type
  * @template Out - The output type that the function returns
  * @template RequiredServices - Services required by this function
- * @template ScenarioOut - Types \`scenario.context\`. Only scenarios set it:
- *   \`PikkuFunctionScenario\` passes the scenario's own output, and a *hook*
- *   passes the output of the scenario it belongs to (it returns void itself).
- *
- *   It deliberately does NOT default to \`Out\`. That would make every ordinary
- *   function's wire type vary with its return type, and a \`func\` written
- *   against the \`PikkuFunction | PikkuFunctionSessionless\` union then loses
- *   contextual typing — its parameters fall back to \`any\` and the assignment
- *   fails with no hint as to why.
+ * @template ScenarioOut - Types \`scenario.context\`; only scenarios set it.
+ *   Not defaulted to \`Out\`, which would make every ordinary function's wire
+ *   type vary with its return type and cost a \`func\` written against the
+ *   \`PikkuFunction | PikkuFunctionSessionless\` union its contextual typing.
  */
 export type PikkuFunctionSessionless<
   In = unknown,
@@ -363,10 +348,8 @@ export type PikkuFunctionConfig<
   In = unknown,
   Out = unknown,
   RequiredWires extends keyof PikkuWire = never,
-  // \`any\` in the ScenarioOut slot, not \`unknown\`: a scenario body types its
-  // context as its own output, and a constraint pinned to one context type
-  // would refuse it. \`ScenarioContext<any>\` collapses to \`any\`, so the
-  // constraint stays open on that axis alone.
+  // \`any\` in the ScenarioOut slot: a constraint pinned to one context type
+  // would refuse a scenario body, which types its context as its own output.
   PikkuFunc extends PikkuFunction<In, Out, RequiredWires, any> | PikkuFunctionSessionless<In, Out, RequiredWires, any, any> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
@@ -454,12 +437,6 @@ export type PikkuFunctionConfigWithSchema<
  * })
  * \`\`\`
  */
-export function pikkuFunc<
-  InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined
->(
-  config: PikkuFunctionConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc', WiredSecretBrokerServices> & { secretBroker: true }
-): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
 export function pikkuFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined

package/dist/src/functions/wirings/middleware/serialize-middleware-imports.js

@@ -60,8 +60,12 @@ export const serializeMiddlewareImports = (outputPath, middlewareState, httpStat
     // it here, into the always-bootstrap-imported pikku-middleware.gen.ts,
     // guarantees global middleware registers in every unit. A duplicate import
     // in full builds is harmless — module bodies evaluate once.
+    //
+    // `isFactoryCall` is not consulted: it distinguishes `mw()` from `mw` as an
+    // array element, not a deferred registration behind an exported factory, and
+    // addGlobalMiddleware registers at module evaluation under either form.
     for (const [instanceId, instance] of Object.entries(middlewareState.instances)) {
-        if (instanceId.startsWith('global:') && !instance.isFactoryCall) {
+        if (instanceId.startsWith('global:')) {
             directImports.add(getFileImportRelativePath(outputPath, instance.sourceFile, packageMappings));
         }
     }

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

@@ -35,6 +35,17 @@ export const pikkuPackage = pikkuSessionlessFunc({
                 };
             }
         }
+        // A secret read the inspector could not resolve to a literal is absent by
+        // construction — such an addon needs `globalSecrets` on its `wireAddon`.
+        const declaredSecrets = new Set();
+        for (const definition of state.secrets?.definitions ?? []) {
+            declaredSecrets.add(definition.secretId);
+        }
+        for (const usage of state.secrets?.usage?.values() ?? []) {
+            for (const key of usage.keys) {
+                declaredSecrets.add(key);
+            }
+        }
         const content = serializePackageFactories(packageFile, addonName, pikkuConfigFactory
             ? {
                 file: pikkuConfigFactory.file,
@@ -50,7 +61,7 @@ export const pikkuPackage = pikkuSessionlessFunc({
                 file: wireServicesFactory.file,
                 variable: wireServicesFactory.variable,
             }
-            : undefined, packageMappings, Object.keys(credentialsMeta).length > 0 ? credentialsMeta : undefined, state.addonRequiredParentServices);
+            : undefined, packageMappings, Object.keys(credentialsMeta).length > 0 ? credentialsMeta : undefined, state.addonRequiredParentServices, [...declaredSecrets].sort());
         if (!content) {
             logger.info({
                 message: 'Skipping package factories - no service factories found',

package/dist/src/functions/wirings/package/serialize-package.d.ts

@@ -8,4 +8,4 @@ export interface CredentialMetaForPackage {
     type: 'singleton' | 'wire';
     oauth2?: boolean;
 }
-export declare const serializePackageFactories: (outputPath: string, packageName: string, configFactory: PackageFactoryInfo | undefined, singletonServicesFactory: PackageFactoryInfo | undefined, wireServicesFactory: PackageFactoryInfo | undefined, packageMappings?: Record<string, string>, credentialsMeta?: Record<string, CredentialMetaForPackage>, requiredParentServices?: string[]) => string | null;
+export declare const serializePackageFactories: (outputPath: string, packageName: string, configFactory: PackageFactoryInfo | undefined, singletonServicesFactory: PackageFactoryInfo | undefined, wireServicesFactory: PackageFactoryInfo | undefined, packageMappings?: Record<string, string>, credentialsMeta?: Record<string, CredentialMetaForPackage>, requiredParentServices?: string[], declaredSecrets?: string[]) => string | null;

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

@@ -1,5 +1,5 @@
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-export const serializePackageFactories = (outputPath, packageName, configFactory, singletonServicesFactory, wireServicesFactory, packageMappings = {}, credentialsMeta, requiredParentServices) => {
+export const serializePackageFactories = (outputPath, packageName, configFactory, singletonServicesFactory, wireServicesFactory, packageMappings = {}, credentialsMeta, requiredParentServices, declaredSecrets) => {
     const imports = [
         `import { pikkuState } from '@pikku/core/ecosystem'`,
     ];
@@ -29,10 +29,13 @@ export const serializePackageFactories = (outputPath, packageName, configFactory
     const requiredParentServicesLine = requiredParentServices && requiredParentServices.length > 0
         ? `\npikkuState('${packageName}', 'package', 'requiredParentServices', ${JSON.stringify(requiredParentServices)})\n`
         : '';
+    const declaredSecretsLine = declaredSecrets
+        ? `\npikkuState('${packageName}', 'package', 'declaredSecrets', ${JSON.stringify(declaredSecrets)})\n`
+        : '';
     return `${imports.join('\n')}
 
 pikkuState('${packageName}', 'package', 'factories', {
 ${factoryEntries.join('\n')}
 })
-${credentialsLine}${requiredParentServicesLine}`;
+${credentialsLine}${requiredParentServicesLine}${declaredSecretsLine}`;
 };

package/dist/src/functions/wirings/rpc/serialize-typed-rpc-map.js

@@ -59,12 +59,7 @@ ${generateAddonAgentImports(wireAddonDeclarations)}
 ${generateMergedAgentMap(wireAddonDeclarations)}
 
 import type { PikkuRPC } from '@pikku/core/rpc'
-
-interface AIAgentInput {
-  message: string
-  threadId: string
-  resourceId: string
-}
+import type { AIAgentInput } from '@pikku/core/ai-agent'
 
 export type TypedStartWorkflow = <Name extends keyof FlattenedWorkflowMap>(
   name: Name,

package/dist/src/functions/wirings/scenarios/register-scenario-instrumentation.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { addFunction } from '@pikku/core/function';
 import { pikkuState } from '@pikku/core/ecosystem';
 import { getStubTracker, isTestRun, } from '@pikku/core/services';
+import { enableScoreSnapshots, getScoreSnapshot, gradeRun as coreGradeRun, } from '@pikku/core/ai-scorer';
 /**
  * The instrumentation `pikku scenario run` calls on the server under test:
  * snapshot/reset live coverage, and reset/read recorded stub calls.
@@ -52,6 +53,26 @@ const resetStubs = {
 const getStubCalls = {
     func: async (_services, data) => getStubTracker().getCalls(data?.service ?? undefined),
 };
+/**
+ * Grade a finished agent run on demand, from the snapshot the runtime kept.
+ *
+ * Deliberately not sampled and not persisted: a scenario asserting on a grade
+ * needs that grade every time, and the assertion is the outcome — writing a
+ * test's score alongside production's would make the live figures unreadable.
+ */
+const gradeRun = {
+    func: async (services, data) => {
+        const run = getScoreSnapshot(data.runId);
+        if (!run) {
+            throw new Error(`No finished run '${data.runId}' is available to grade. A run is gradeable only from the server that produced it, and only while it is among the most recent — check the scenario graded the run it just triggered.`);
+        }
+        return await coreGradeRun({
+            ...run,
+            ...(data.reference !== undefined ? { reference: data.reference } : {}),
+            scorerName: data.scorer,
+        }, services, { persist: false });
+    },
+};
 const instrumentation = {
     pikkuScenarioTakeLiveCoverage: {
         ...takeLiveCoverage,
@@ -73,6 +94,11 @@ const instrumentation = {
         title: 'Get Stub Calls',
         description: 'Returns calls recorded against stubbed/spied services (via the stub()/spy() core utils). Empty unless the server records service calls (pikku dev --test).',
     },
+    pikkuScenarioGradeRun: {
+        ...gradeRun,
+        title: 'Grade Run',
+        description: "Runs one declared scorer against a finished agent run and returns the grade, ignoring the scorer's live sample rate. Accepts a reference answer, which is the only way a reference-based judge is reachable. The grade is returned, never recorded.",
+    },
 };
 /**
  * Register the instrumentation into the running dev server's state, so the
@@ -85,6 +111,10 @@ const instrumentation = {
  */
 export const registerScenarioInstrumentation = (requireAuth) => {
     const meta = pikkuState(null, 'function', 'meta');
+    // Retaining finished runs is what makes them gradeable, and this is the only
+    // place that can grade one — so the buffer is turned on here rather than by a
+    // flag someone has to remember, and stays absent from every other process.
+    enableScoreSnapshots();
     for (const [name, { func, title, description }] of Object.entries(instrumentation)) {
         addFunction(name, { func, auth: requireAuth });
         meta[name] = {

package/dist/src/functions/wirings/workflow/serialize-workflow-routes.js

@@ -274,10 +274,18 @@ export const workflowStatusStreamFull = pikkuSessionlessFunc({
  * The decision is validated on replay inside the workflow body — the only place
  * the approval's schema value is in scope — so this route deliberately accepts
  * an unknown payload. An invalid one re-closes the gate rather than failing the
- * A run started through a session may only be approved by that session's user
- * (\`assertWorkflowRunOwner\`). A run with no recorded owner has nobody to compare
- * a caller against — gate this route with your own auth/permissions to control
- * WHO may approve those.
+ * request.
+ *
+ * WHO may approve is likewise the gate's own business, declared with
+ * \`approvers\`/\`approverScope\` on \`workflow.approval()\`, and enforced in two
+ * places. Once the run has reached the gate it has published its policy, so this
+ * route judges the caller against it and refuses with a 403. A decision arriving
+ * before the gate has no policy to judge against yet, so it is accepted here and
+ * judged on replay instead, where failing discards the decision and leaves the
+ * gate closed. A caller sees either outcome depending on that timing.
+ *
+ * A gate that declares neither accepts a decision from anyone this route lets
+ * through — gate the route with your own auth/permissions to narrow that.
  */
 export const workflowApprover = pikkuSessionlessFunc({
   tags: ['pikku'],

package/dist/src/functions/wirings/workflow/serialize-workflow-types.js

@@ -71,10 +71,7 @@ export interface TypedScenarioSteps {
   ): Promise<FlattenedScenarioStepMap[K]['output']>
 }
 
-/**
- * \`Out\` types \`scenario.context\` — the scratch the body shares with its
- * \`before\`/\`after\` hooks — as a partial of what a completed run produces.
- */
+/** \`Out\` types \`scenario.context\`. */
 export type TypedScenario<Out = unknown> = TypedWorkflow &
   Omit<PikkuScenarioWire<Out>, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> &
   TypedScenarioSteps
@@ -91,9 +88,9 @@ export type PikkuFunctionWorkflow<
 > = PikkuFunctionSessionless<In, Out, 'workflow'>
 
 /**
- * \`Ctx\` types \`scenario.context\` and defaults to the function's own output,
- * which is what a scenario body wants. A hook returns void but shares the
- * scenario's context, so it passes the scenario's output here instead.
+ * \`Ctx\` types \`scenario.context\`, defaulting to the body's own output. A hook
+ * returns void but shares the scenario's context, so it passes that scenario's
+ * output here instead.
  */
 export type PikkuFunctionScenario<
   In = unknown,
@@ -185,10 +182,8 @@ export type PikkuScenarioConfigWithSchema<
    * Always runs after the scenario body, in a \`finally\`, whether it passed or
    * failed. Throwing fails a run that would otherwise have passed; on an
    * already-failed run it attaches as the \`cause\` and never replaces the
-   * original error.
-   *
-   * Reads \`scenario.context\` for whatever the body managed to record before it
-   * stopped — that is how teardown learns the ids a failed run created.
+   * original error. Reads \`scenario.context\` for whatever the body managed to
+   * record before it stopped.
    */
   after?: PikkuScenarioHook<InputSchema, OutputSchema>
   /**
@@ -202,11 +197,8 @@ export type PikkuScenarioConfigWithSchema<
 
 /**
  * A scenario lifecycle hook: the scenario's own \`(services, data, wire)\`
- * signature with its result discarded.
- *
- * The hook returns void but shares the scenario's \`context\`, so the output
- * schema types \`scenario.context\` while the return type stays \`void\` — a hook
- * is setup and teardown, never a step, and nothing it returns is recorded.
+ * signature with its result discarded. \`OutputSchema\` types
+ * \`scenario.context\` while the return type stays \`void\`.
  */
 export type PikkuScenarioHook<
   InputSchema extends StandardSchemaV1 | undefined = undefined,

package/dist/src/functions/workflows/all.workflow.js

@@ -154,16 +154,21 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         if (hasPackageFactories) {
             allImports.push(config.packageFile);
         }
-        const [hasInternalRPCs, agents] = await Promise.all([
+        const [hasInternalRPCs, agents, scorers] = await Promise.all([
             workflow.do('RPC', 'pikkuRPC', null),
             workflow.do('AI agent', 'pikkuAIAgent', null),
+            workflow.do('AI scorer', 'pikkuAIScorer', null),
         ]);
+        allImports.push(config.modelAliasesFile);
         if (agents) {
             allImports.push(config.agentWiringMetaFile, config.agentWiringsFile);
             if (config.scaffold?.agent) {
                 await workflow.do('Public agent scaffold', 'pikkuPublicAgent', null);
             }
         }
+        if (scorers) {
+            allImports.push(config.scorerWiringMetaFile, config.scorerWiringsFile);
+        }
         // Scaffold and definition generators are all independent
         await Promise.all([
             workflow.do('Graph wirings', 'pikkuGraphWirings', null),

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

@@ -24,6 +24,9 @@ export class BunServerRunner {
             // every Bun project: `config.content` arrived, but the service that
             // verifies its signatures did not.
             contentSigningJWT: options.contentSigningJWT,
+            // 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,
         });
     }
 }

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

@@ -26,6 +26,16 @@ export type DevServerOptions = {
      * instance — otherwise every signed URL is rejected.
      */
     contentSigningJWT?: JWTService;
+    /**
+     * The generated MCP manifest. Handed straight to the transport, which mounts
+     * the MCP endpoint only when it is present — so a runner that forgets to
+     * forward this serves a 404 with no error anywhere.
+     */
+    mcpJson?: {
+        tools?: unknown[];
+        resources?: unknown[];
+        prompts?: unknown[];
+    };
 };
 export interface DevServerRunner {
     /**

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

@@ -18,6 +18,9 @@ export class NodeServerRunner {
                 pikkuWebsocketHandler({ server: httpServer, wss, logger });
             },
             contentSigningJWT: options.contentSigningJWT,
+            // 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,
         });
         return {
             init: () => server.init(),

package/dist/src/services.js

@@ -267,6 +267,7 @@ export const createSingletonServices = async (config) => {
                 // cost. Never runs during a plain `pikku all`.
                 classificationCheck: !setupOnly && !!config.security,
                 strictMeta: !!config.strictMeta,
+                modelAliases: config.models ?? {},
                 allow: config.allow ?? {},
                 schemaConfig: !setupOnly
                     ? {

package/dist/src/utils/meta-diff.d.ts

@@ -6,7 +6,7 @@
  * second inspection pass. Only user-visible buildable surfaces are included;
  * plumbing (secrets/variables/middleware/permissions) is intentionally omitted.
  */
-export type MetaDiffCategoryName = 'functions' | 'http' | 'workflow' | 'email' | 'scheduler' | 'queue' | 'channel' | 'trigger' | 'mcp' | 'agent';
+export type MetaDiffCategoryName = 'functions' | 'http' | 'workflow' | 'email' | 'scheduler' | 'queue' | 'channel' | 'trigger' | 'mcp' | 'agent' | 'scorer';
 export interface MetaDiffEntry {
     id: string;
     status: 'added' | 'removed' | 'modified';

package/dist/src/utils/meta-diff.js

@@ -12,12 +12,14 @@ const SINGLE_FILE = {
     trigger: 'trigger/pikku-trigger-meta.gen.json',
     mcp: 'mcp/pikku-mcp-wirings-meta.gen.json',
     agent: 'agent/pikku-agent-wirings-meta.gen.json',
+    scorer: 'agent/pikku-scorer-wirings-meta.gen.json',
 };
 // A few meta files wrap their real entities under a single key rather than
 // keying them at the top level — unwrap to that map so ids are the entities.
 const UNWRAP = {
     email: 'templates',
     agent: 'agentsMeta',
+    scorer: 'scorersMeta',
 };
 // Workflows (incl. scenarios) are written one file per workflow under
 // this dir; the file basename (sans `.gen.json`) is the id, `-verbose` excluded.

package/dist/src/utils/model-alias-override.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Applies `--model cheap:openai/gpt-5-nano` to a `pikku dev` / `pikku serve`
+ * run, via PIKKU_MODEL_ALIASES so it leaves no trace in generated output.
+ */
+export declare const applyModelAliasOverride: (logger: {
+    warn: (message: string) => void;
+}, model: string | undefined, configuredAliases?: Record<string, string>) => void;

package/dist/src/utils/model-alias-override.js

@@ -0,0 +1,33 @@
+/**
+ * Applies `--model cheap:openai/gpt-5-nano` to a `pikku dev` / `pikku serve`
+ * run, via PIKKU_MODEL_ALIASES so it leaves no trace in generated output.
+ */
+export const applyModelAliasOverride = (logger, model, configuredAliases = {}) => {
+    if (!model)
+        return;
+    for (const entry of model.split(',')) {
+        const separator = entry.indexOf(':');
+        if (separator === -1) {
+            throw new Error(`--model expects alias:provider/model (e.g. 'cheap:openai/gpt-5-nano'), got '${entry}'.`);
+        }
+        const alias = entry.slice(0, separator).trim();
+        const target = entry.slice(separator + 1).trim();
+        // An empty half still contains the separator, so it survives the check
+        // above. `cheap:` is the damaging one: the core resolver prefers the
+        // environment override, finds nothing behind the alias, and fails later
+        // with an unknown-alias error naming a model the user never typed.
+        if (!alias || !target) {
+            throw new Error(`--model expects alias:provider/model (e.g. 'cheap:openai/gpt-5-nano'), got '${entry}' with ${alias ? 'no model' : 'no alias'}.`);
+        }
+        if (alias.includes('/')) {
+            throw new Error(`--model repoints an alias, and '${alias}' is not an alias but a provider-qualified model. Name the alias whose model you want to change, e.g. 'cheap:${target}'.`);
+        }
+        // A warning, not an error: the table may come from an addon config this
+        // run has not loaded.
+        if (Object.keys(configuredAliases).length > 0 &&
+            !configuredAliases[alias]) {
+            logger.warn(`--model overrides alias '${alias}', which is not in the "models" table of pikku.config.json (${Object.keys(configuredAliases).sort().join(', ')}) — nothing may use it.`);
+        }
+    }
+    process.env.PIKKU_MODEL_ALIASES = model;
+};

package/dist/src/utils/pikku-cli-config.js

@@ -489,12 +489,28 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.agentWiringMetaJsonFile) {
             result.agentWiringMetaJsonFile = join(agentDir, 'pikku-agent-wirings-meta.gen.json');
         }
+        if (!result.modelAliasesFile) {
+            result.modelAliasesFile = join(agentDir, 'pikku-model-aliases.gen.ts');
+        }
         if (!result.agentTypesFile) {
             result.agentTypesFile = join(agentDir, 'pikku-agent-types.gen.ts');
         }
         if (!result.agentMapDeclarationFile) {
             result.agentMapDeclarationFile = join(agentDir, 'pikku-agent-map.gen.d.ts');
         }
+        // AI Scorer — the same directory as agents: a scorer exists to grade one.
+        if (!result.scorerWiringsFile) {
+            result.scorerWiringsFile = join(agentDir, 'pikku-scorer-wirings.gen.ts');
+        }
+        if (!result.scorerWiringMetaFile) {
+            result.scorerWiringMetaFile = join(agentDir, 'pikku-scorer-wirings-meta.gen.ts');
+        }
+        if (!result.scorerWiringMetaJsonFile) {
+            result.scorerWiringMetaJsonFile = join(agentDir, 'pikku-scorer-wirings-meta.gen.json');
+        }
+        if (!result.scorerNamesDeclarationFile) {
+            result.scorerNamesDeclarationFile = join(agentDir, 'pikku-scorer-names.gen.d.ts');
+        }
         // CLI
         if (!result.cliWiringsFile) {
             result.cliWiringsFile = join(cliDir, 'pikku-cli-wirings.gen.ts');