@pikku/core 0.12.84 → 0.12.86

package/dist/wirings/addon/wire-addon.js

@@ -0,0 +1,120 @@
+import { pikkuState } from '../../pikku-state.js';
+import { getTagGroups } from '../../utils.js';
+export const wireAddon = (config) => {
+    pikkuState(null, 'addons', 'packages').set(config.name, {
+        package: config.package,
+        rpcEndpoint: config.rpcEndpoint,
+        auth: config.auth,
+        tags: config.tags,
+        ...(config.scopes ? { scopes: config.scopes } : {}),
+        ...(config.secretOverrides
+            ? { secretOverrides: config.secretOverrides }
+            : {}),
+        ...(config.variableOverrides
+            ? { variableOverrides: config.variableOverrides }
+            : {}),
+        ...(config.credentialOverrides
+            ? { credentialOverrides: config.credentialOverrides }
+            : {}),
+        ...(config.secretGrants ? { secretGrants: config.secretGrants } : {}),
+        ...(config.credentialGrants
+            ? { credentialGrants: config.credentialGrants }
+            : {}),
+        ...(config.globalSecrets ? { globalSecrets: config.globalSecrets } : {}),
+        ...(config.globalCredentials
+            ? { globalCredentials: config.globalCredentials }
+            : {}),
+    });
+};
+/**
+ * The addon configs a running function is governed by: the named instance when
+ * the caller resolved one, every instance of the package otherwise.
+ *
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+const governingAddonConfigs = (packageName, namespace) => {
+    if (!packageName) {
+        return [];
+    }
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons) {
+        return [];
+    }
+    if (namespace) {
+        const config = addons.get(namespace);
+        if (config?.package === packageName) {
+            return [config];
+        }
+    }
+    return [...addons.values()].filter((config) => config?.package === packageName);
+};
+const unionOf = (packageName, namespace, field) => {
+    const values = new Set();
+    for (const config of governingAddonConfigs(packageName, namespace)) {
+        for (const value of config[field] ?? []) {
+            values.add(value);
+        }
+    }
+    return [...values];
+};
+/**
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+export const resolveAddonScopes = (packageName, namespace) => unionOf(packageName, namespace, 'scopes');
+/**
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonTags = (packageName, namespace) => unionOf(packageName, namespace, 'tags');
+/**
+ * True when any governing instance requires a session. `auth: false` is not
+ * honoured here — on a direct wiring it would weaken the wiring's own gate.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonAuth = (packageName, namespace) => governingAddonConfigs(packageName, namespace).some((config) => config.auth === true);
+/**
+ * The package a namespaced function id belongs to, and the name that package
+ * publishes it under.
+ *
+ * A wiring that points at an addon function through `ref('ns:fn')` records
+ * `ns:fn` as its own function id — the same id every other wire type records —
+ * but the addon publishes its metadata under the bare `fn`, in its own package
+ * state. Without this the wire finds the function it registered and no metadata
+ * to run it by.
+ *
+ * The wiring itself stays the consuming app's, so `packageName` is the package
+ * the *wire* runs in, not the target's: it is null for a `ref()` the app wired,
+ * and only narrows the lookup when a wire really does run inside the addon.
+ */
+export const resolveAddonFunctionTarget = (funcName, packageName) => {
+    const separator = funcName.indexOf(':');
+    if (separator === -1) {
+        return null;
+    }
+    const namespace = funcName.slice(0, separator);
+    const config = pikkuState(null, 'addons', 'packages').get(namespace);
+    if (!config) {
+        return null;
+    }
+    if (packageName && config.package !== packageName) {
+        return null;
+    }
+    return {
+        packageName: config.package,
+        localName: funcName.slice(separator + 1),
+    };
+};
+/**
+ * Addon tags name middleware the *consuming app* registered, so they resolve
+ * against the root tag groups rather than the addon package's own.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonTagMiddleware = (packageName, namespace) => {
+    const tags = resolveAddonTags(packageName, namespace);
+    if (tags.length === 0) {
+        return [];
+    }
+    const tagGroups = pikkuState(null, 'middleware', 'tagGroup');
+    return tags.flatMap((tag) => getTagGroups(tagGroups, tag).flat());
+};

package/dist/wirings/addon/wire-remote-addon.d.ts

@@ -0,0 +1,22 @@
+import type { CoreServices, PikkuWire } from '../../types/core.types.js';
+/** Sent as `Authorization: Bearer <token>`; a non-default header is declared by the addon. */
+export type RemoteAddonAuth = {
+    credentialId: string;
+} | {
+    secretId: string;
+} | {
+    resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string>;
+};
+export type WireRemoteAddonConfig = {
+    /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
+    name: string;
+    /** Must be installed as a devDependency — `pikku verify` enforces this. */
+    package: string;
+    serverUrl: string | ((services: CoreServices) => string | Promise<string>);
+    /** Omit when the addon declares its remote surface public. */
+    auth?: RemoteAddonAuth;
+    /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
+    remoteName?: (fn: string) => string;
+    tags?: string[];
+};
+export declare const wireRemoteAddon: (config: WireRemoteAddonConfig) => void;

package/dist/wirings/addon/wire-remote-addon.js

@@ -0,0 +1,11 @@
+import { pikkuState } from '../../pikku-state.js';
+export const wireRemoteAddon = (config) => {
+    pikkuState(null, 'addons', 'packages').set(config.name, {
+        package: config.package,
+        tags: config.tags,
+        remote: true,
+        serverUrl: config.serverUrl,
+        ...(config.auth ? { remoteAuth: config.auth } : {}),
+        ...(config.remoteName ? { remoteName: config.remoteName } : {}),
+    });
+};

package/dist/wirings/agent/agent-prepare.d.ts

@@ -1,4 +1,4 @@
-import type { CoreUserSession } from '../../types/core.types.js';
+import type { CoreUserSession, GetCredential } from '../../types/core.types.js';
 import type { CoreAgent, AgentInput, AgentToolDef, AgentMessage, AgentStreamChannel, PikkuAgentMiddlewareHooks, SessionScope } from './agent.types.js';
 import type { AgentRunnerParams } from '../../services/agent-runner-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
@@ -6,7 +6,7 @@ import type { SessionService } from '../../services/user-session-service.js';
 export type RunAgentParams = {
     sessionService?: SessionService<CoreUserSession>;
     /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
-    getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>;
+    getCredential?: GetCredential;
     /** Ephemeral owner identity minted for a sessionless request; never client-supplied, never reused across requests. */
     anonymousOwnerResourceId?: string;
 };
@@ -105,7 +105,7 @@ export declare function prepareAgentRun(agentName: string, input: AgentInput, pa
     packageName: string | null;
     resolvedName: string;
     agentRunner: import("../../services/agent-runner-service.js").AgentRunnerService;
-    storage: import("../../index.js").AgentStorageService | undefined;
+    storage: import("../../services/agent-storage-service.js").AgentStorageService | undefined;
     memoryConfig: import("./agent.types.js").AgentMemoryConfig | undefined;
     threadId: string;
     userMessage: AgentMessage;

package/dist/wirings/agent/agent-prepare.js

@@ -10,7 +10,7 @@ import { awaitPendingInterruptNote } from './agent-interrupt.js';
 import { streamAgent } from './agent-stream.js';
 import { runAgent } from './agent-runner.js';
 import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
-import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js';
+import { getOrCreatePackageSingletonServices } from '../../wirings/addon/addon-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, } from './agent-memory.js';
 import { resolveModelConfig } from './agent-model-config.js';
 export function resolveSessionPrincipal(params, sessionScope) {

package/dist/wirings/agent/agent-runner.js

@@ -7,7 +7,7 @@ import { applyInputMiddleware, describeApprovals, notifyAfterStep, toAccumulated
 import { applyOutputMiddleware, finalizeAgentRun, lastUserMessageText, } from './agent-finalize.js';
 import { resolveModelConfig } from './agent-model-config.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
-import { randomUUID } from './agent-utils.js';
+import { deniedToolResult, randomUUID } from './agent-utils.js';
 function stripNulls(obj) {
     if (obj === null)
         return undefined;
@@ -306,8 +306,7 @@ export async function resumeAgentSync(runId, approvals, params, expectedAgentNam
         let resultStr;
         let toolError;
         if (rejectedIds.has(toolCallId)) {
-            resultStr =
-                'The user explicitly declined this action. Inform them that it was declined and do not retry.';
+            resultStr = deniedToolResult();
         }
         else if (approvedIds.has(toolCallId)) {
             const matchingTool = tools.find((t) => t.name === pending.toolName);

package/dist/wirings/agent/agent-stream.js

@@ -2,7 +2,7 @@ import { finalizeAgentRun, lastUserMessageText } from './agent-finalize.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { applyInputMiddleware } from './agent-turn.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
-import { randomUUID } from './agent-utils.js';
+import { deniedToolResult, randomUUID } from './agent-utils.js';
 import { SPOKEN_TRANSCRIPT } from './voice-input.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './agent-memory.js';
@@ -717,7 +717,7 @@ export async function resumeAgent(input, channel, params, options) {
         if (pending.type === 'agent-call') {
             await agentRunState.updateRun(pending.agentRunId, { status: 'failed' });
         }
-        const denialResult = 'The user explicitly declined this action. Inform them that it was declined and do not retry.';
+        const denialResult = deniedToolResult();
         if (storage) {
             await storage.saveMessages(run.threadId, [
                 {

package/dist/wirings/agent/agent-utils.d.ts

@@ -1 +1,14 @@
 export declare const randomUUID: () => string;
+/**
+ * The tool result stored and streamed when a user denies an approval.
+ *
+ * Two readers, one string. The model needs the sentence — it has to tell the
+ * user the action was declined and not retry it. A client needs to know a
+ * denial when it sees one, so it can render the call as denied rather than as
+ * a successful call that happened to return prose; that is what `approved`
+ * carries, and it is the same flag a client sets optimistically the moment the
+ * deny button is clicked. Emitting only the sentence made the two disagree:
+ * live the call showed denied, and on any re-render from storage the same call
+ * came back green.
+ */
+export declare const deniedToolResult: () => string;

package/dist/wirings/agent/agent-utils.js

@@ -1 +1,17 @@
 export const randomUUID = () => globalThis.crypto.randomUUID();
+/**
+ * The tool result stored and streamed when a user denies an approval.
+ *
+ * Two readers, one string. The model needs the sentence — it has to tell the
+ * user the action was declined and not retry it. A client needs to know a
+ * denial when it sees one, so it can render the call as denied rather than as
+ * a successful call that happened to return prose; that is what `approved`
+ * carries, and it is the same flag a client sets optimistically the moment the
+ * deny button is clicked. Emitting only the sentence made the two disagree:
+ * live the call showed denied, and on any re-render from storage the same call
+ * came back green.
+ */
+export const deniedToolResult = () => JSON.stringify({
+    approved: false,
+    message: 'The user explicitly declined this action. Inform them that it was declined and do not retry.',
+});

package/dist/wirings/agent/agent.types.d.ts

@@ -1,5 +1,6 @@
 import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
+import type { PermissionMetadata } from '../../function/function-meta.types.js';
 import type { AIProviderOptions } from '../../services/agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
@@ -389,7 +390,7 @@ export type CoreAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMidd
      * which OR together, a scope can only narrow access.
      *
      * Narrowed to the generated `ScopeId` union in a project's own
-     * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+     * `#pikku/scopes`, so an undeclared scope is a compile error.
      */
     scopes?: Scope[];
     permissions?: CorePermissionGroup<PikkuPermission>;

package/dist/wirings/agent/index.d.ts

@@ -4,7 +4,7 @@ export { runAgent, resumeAgentSync } from './agent-runner.js';
 export { resolveModelAlias } from './agent-model-config.js';
 export { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
 export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
-export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, } from './voice-output.js';
+export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, type VoiceOutputState, } from './voice-output.js';
 export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js';
 export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, } from './agent-interrupt.js';
 export { type RunAgentParams, type StreamAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';

package/dist/wirings/agent/voice-input.js

@@ -1,4 +1,4 @@
-import { pikkuAgentMiddleware } from '../../types/core.types.js';
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js';
 import { safeFetch } from '../../utils/safe-fetch.js';
 function base64ToUint8Array(base64) {
     const binary = atob(base64);

package/dist/wirings/agent/voice-output.js

@@ -1,4 +1,4 @@
-import { pikkuAgentMiddleware } from '../../types/core.types.js';
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js';
 import { SPOKEN_TURN } from './voice-input.js';
 function bufferToBase64(data) {
     let binary = '';

package/dist/wirings/agent-scorer/agent-scorer-judge.d.ts

@@ -5,6 +5,19 @@ import type { PikkuAgentScorer, ScorerInput, ScorerJudgeConfig, ScorerOutput } f
  *
  * A reference-based judge is shown the answer key; a reference-free one is not,
  * and grades the answer on its own merits.
+ *
+ * The tool calls are shown because without them a judge cannot tell a fact from
+ * a fabrication. Grading a todo agent that had just listed the user's todos
+ * correctly, a judge given only the answer called it "a plausible-looking list"
+ * that "offers no real access to your actual list, making it effectively a
+ * guess", and scored 0.2 what it scored 1 on other runs — right by its rubric,
+ * on the evidence it was given, and wrong about the run. An agent that answers
+ * from a tool and one that invents the same sentence are indistinguishable in
+ * the output alone; they differ only in what the run did to get there.
+ *
+ * How much of that to show is `judge.toolCalls`, and the default stops at the
+ * names: the 0.2 was the judge doubting the run had any access, and a name
+ * settles that without handing a third-party model the rows.
  */
 export declare const buildJudgePrompt: (judge: ScorerJudgeConfig, input: ScorerInput) => string;
 /**

package/dist/wirings/agent-scorer/agent-scorer-judge.js

@@ -16,11 +16,59 @@ const JUDGE_OUTPUT_SCHEMA = {
     required: ['score', 'reason'],
     additionalProperties: false,
 };
+/**
+ * The default disclosure: which tools ran and which failed, and nothing about
+ * what went in or came back. A judge that can see a run reached `listTodos`
+ * can tell a retrieved list from an invented one, which is the whole of what
+ * the trajectory is needed for — the rows themselves it does not need, and an
+ * error string is a tool's own words about the caller's data, so it is
+ * summarised rather than quoted.
+ */
+const describeToolCallName = (call) => `- ${call.name}${call.error ? ' (failed)' : ''}`;
+/** Everything about a call, for a judge that grades against what came back. */
+const describeToolCall = (call) => {
+    const outcome = call.error
+        ? `failed: ${call.error}`
+        : `returned ${formatToolValue(call.result)}`;
+    return `- ${call.name}(${formatToolValue(call.args)}) ${outcome}`;
+};
+/**
+ * A tool's arguments and result are arbitrary JSON, and some of it is large —
+ * a listing, a document, a page of search results. Truncating keeps a single
+ * fat call from crowding the answer out of the judge's context; what survives
+ * is the head, which is where the shape of a value is.
+ */
+const TOOL_VALUE_LIMIT = 500;
+const formatToolValue = (value) => {
+    if (value === undefined) {
+        return 'nothing';
+    }
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    if (text === undefined) {
+        return 'nothing';
+    }
+    return text.length > TOOL_VALUE_LIMIT
+        ? `${text.slice(0, TOOL_VALUE_LIMIT)}… (truncated)`
+        : text;
+};
 /**
  * The message a judge grades when its scorer supplies no `prompt`.
  *
  * A reference-based judge is shown the answer key; a reference-free one is not,
  * and grades the answer on its own merits.
+ *
+ * The tool calls are shown because without them a judge cannot tell a fact from
+ * a fabrication. Grading a todo agent that had just listed the user's todos
+ * correctly, a judge given only the answer called it "a plausible-looking list"
+ * that "offers no real access to your actual list, making it effectively a
+ * guess", and scored 0.2 what it scored 1 on other runs — right by its rubric,
+ * on the evidence it was given, and wrong about the run. An agent that answers
+ * from a tool and one that invents the same sentence are indistinguishable in
+ * the output alone; they differ only in what the run did to get there.
+ *
+ * How much of that to show is `judge.toolCalls`, and the default stops at the
+ * names: the 0.2 was the judge doubting the run had any access, and a name
+ * settles that without handing a third-party model the rows.
  */
 export const buildJudgePrompt = (judge, input) => {
     if (judge.prompt)
@@ -30,6 +78,10 @@ export const buildJudgePrompt = (judge, input) => {
         sections.push(`Reference answer:\n${input.reference}`);
     }
     sections.push(`Assistant answered:\n${input.output}`);
+    if (judge.toolCalls !== 'off' && input.toolCalls.length > 0) {
+        const describe = judge.toolCalls === 'full' ? describeToolCall : describeToolCallName;
+        sections.push(`Tools the assistant ran:\n${input.toolCalls.map(describe).join('\n')}`);
+    }
     sections.push(judge.goal);
     sections.push('Respond with a score 0..1 and a brief reason.');
     return sections.join('\n\n');

package/dist/wirings/agent-scorer/agent-scorer.d.ts

@@ -1,4 +1,4 @@
-import type { PikkuAgentScorer, ScorerInput, ScorerOutput } from './agent-scorer.types.js';
+import type { JudgeToolCallDisclosure, PikkuAgentScorer, ScorerInput, ScorerOutput } from './agent-scorer.types.js';
 /**
  * A heuristic scorer: pure code over the finished run, no model call, so it
  * grades on the fast lane.
@@ -35,5 +35,11 @@ export declare const pikkuAgentJudge: <Services = any>(config: {
     requiresReference?: boolean;
     model: string;
     goal: string;
+    /**
+     * How much of the run's trajectory to disclose to the judge. Defaults to
+     * `names`: enough to tell a tool-backed answer from an invented one, without
+     * sending a third-party model the rows the tools returned.
+     */
+    toolCalls?: JudgeToolCallDisclosure;
     prompt?: (input: ScorerInput) => string;
 }) => PikkuAgentScorer<Services>;

package/dist/wirings/agent-scorer/agent-scorer.js

@@ -35,6 +35,7 @@ export const pikkuAgentJudge = (config) => ({
     judge: {
         model: config.model,
         goal: config.goal,
+        toolCalls: config.toolCalls ?? 'names',
         ...(config.prompt ? { prompt: config.prompt } : {}),
     },
 });

package/dist/wirings/agent-scorer/agent-scorer.types.d.ts

@@ -43,6 +43,24 @@ export interface ScorerOutput {
  */
 export type ScorerLane = 'fast' | 'slow';
 export declare const SCORER_LANE_QUEUES: Record<ScorerLane, string>;
+/**
+ * How much of the run's trajectory the default judge prompt discloses.
+ *
+ * A judge is a third-party model, and a tool's arguments and results are the
+ * most sensitive thing a run touches — the row it read, the address it looked
+ * up, the message it sent. Output middleware has already had its pass by the
+ * time a scorer sees any of this, so what a judge is shown is what was stored;
+ * this is the second gate, for a judge that should be told less than the
+ * database was.
+ *
+ * - `names` — which tools ran, and whether each failed. No arguments, no
+ *   results. Enough to tell an answer backed by a tool from an invented one,
+ *   which is the failure this exists to catch, while disclosing no row data.
+ * - `full` — names, arguments and results, truncated. For a judge that must
+ *   check the answer *against* what the tool returned.
+ * - `off` — no trajectory at all. The judge grades the answer alone.
+ */
+export type JudgeToolCallDisclosure = 'off' | 'names' | 'full';
 /**
  * A judge's model call. Present only on a scorer built with `pikkuAgentJudge`;
  * `score` is present only on one built with `pikkuAgentScorer`. Exactly one of the
@@ -51,6 +69,8 @@ export declare const SCORER_LANE_QUEUES: Record<ScorerLane, string>;
 export type ScorerJudgeConfig = {
     model: string;
     goal: string;
+    /** Always set: `pikkuAgentJudge` resolves the default. */
+    toolCalls: JudgeToolCallDisclosure;
     prompt?: (input: ScorerInput) => string;
 };
 export type PikkuAgentScorer<Services = any> = {

package/dist/wirings/agent-scorer/index.d.ts

@@ -3,4 +3,4 @@ export { addAgentScorer, getAgentScorers, getAgentScorersMeta, } from './agent-s
 export { gradeRun } from './agent-scorer-grade.js';
 export { enableScoreSnapshots, getScoreSnapshot, } from './agent-scorer-snapshots.js';
 export { wireAgentScorerQueueWorkers } from './agent-scorer-worker.js';
-export type { AgentRunScore, PikkuAgentScorer, ScoreJob, ScorerInput, ScorerJudgeConfig, ScorerLane, ScorerMeta, ScorerOutput, } from './agent-scorer.types.js';
+export type { AgentRunScore, JudgeToolCallDisclosure, PikkuAgentScorer, ScoreJob, ScorerInput, ScorerJudgeConfig, ScorerLane, ScorerMeta, ScorerOutput, } from './agent-scorer.types.js';

package/dist/wirings/channel/channel-common.d.ts

@@ -1,4 +1,5 @@
-import type { CoreSingletonServices, MiddlewareMetadata } from '../../types/core.types.js';
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { MiddlewareMetadata } from '../../middleware/middleware.types.js';
 import type { CoreChannel, ChannelMessageMeta } from './channel.types.js';
 import { type PikkuSessionService } from '../../services/user-session-service.js';
 export declare const runChannelLifecycleWithMiddleware: ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, userSession, }: {

package/dist/wirings/channel/channel-middleware-runner.d.ts

@@ -1,4 +1,5 @@
-import type { CoreSingletonServices, MiddlewareMetadata, PikkuRawWire } from '../../types/core.types.js';
+import type { CoreSingletonServices, PikkuRawWire } from '../../types/core.types.js';
+import type { MiddlewareMetadata } from '../../middleware/middleware.types.js';
 import type { CorePikkuChannelMiddleware } from './channel.types.js';
 export declare const addChannelMiddleware: (tag: string, middleware: CorePikkuChannelMiddleware[], packageName?: string | null) => CorePikkuChannelMiddleware[];
 export declare const clearChannelMiddlewareCache: () => void;

package/dist/wirings/channel/channel.types.d.ts

@@ -1,5 +1,5 @@
 import type { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
 export type BinaryData = ArrayBuffer | Uint8Array;
 export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (services: Services, event: Event, next: (event: Event | Event[] | null) => Promise<void> | void) => Promise<void> | void;
 export type CorePikkuChannelMiddlewareFactory<In = any, Services = any, Event = unknown> = (input: In) => CorePikkuChannelMiddleware<Services, Event>;

package/dist/wirings/channel/serverless/index.d.ts

@@ -1 +1,2 @@
 export { runChannelConnect, runChannelDisconnect, runChannelMessage, } from './serverless-channel-runner.js';
+export type { RunServerlessChannelParams } from './serverless-channel-runner.js';

package/dist/wirings/cli/channel/index.d.ts

@@ -2,5 +2,5 @@ export { executeCLIViaChannel } from './cli-channel-runner.js';
 export { handleRawCLI } from './cli-raw-channel-runner.js';
 export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js';
 export { executeRawCLIViaChannel } from './cli-raw-client-runner.js';
-export type { CorePikkuCLIClientRender, } from './cli-raw-client-runner.js';
+export type { CorePikkuCLIClientRender } from './cli-raw-client-runner.js';
 export type { ApprovalMode } from './cli-approval.js';

package/dist/wirings/cli/cli-runner.d.ts

@@ -1,4 +1,5 @@
-import type { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CoreCLI, CorePikkuCLIRender, CoreCLICommandConfig } from './cli.types.js';
 import type { CoreSingletonServices, CoreServices, CreateWireServices, CreateConfig, CreateSingletonServices } from '../../types/core.types.js';
 import type { PikkuChannel } from '../channel/channel.types.js';

package/dist/wirings/cli/cli-runner.js

@@ -303,8 +303,11 @@ export async function executeCLI({ programName, args, createConfig, createSingle
             }
         }
         const data = { ...parsed.positionals, ...parsed.options };
+        // The command path is passed through so a config factory can tell which
+        // command is about to run. Some commands are meant to work outside a
+        // project, and cannot be gated behind loading that project's config.
         const config = createConfig
-            ? await createConfig(new LocalVariablesService(), data)
+            ? await createConfig(new LocalVariablesService(), data, parsed.commandPath)
             : {};
         const singletonServices = await createSingletonServices(config);
         pikkuState(null, 'package', 'singletonServices', singletonServices);

package/dist/wirings/cli/cli.types.d.ts

@@ -1,15 +1,27 @@
-import type { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata } from '../../types/core.types.js';
+import type { CoreSingletonServices, CoreUserSession, CoreServices } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuFunction, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 import type { ChannelRemote, PikkuChannel } from '../channel/channel.types.js';
+/**
+ * The shape an option's value is parsed into. `'string[]'` splits a single
+ * value on commas; `'boolean'` is a flag that consumes the next token only
+ * when it is an explicit literal (`true`/`false`/`1`/`0`/`yes`/`no`); every
+ * other type consumes one token verbatim, so a value may start with `-`. Left
+ * unset — which is the usual case — it is read from the command function's
+ * input schema, then from `default`, and otherwise falls back to `'string'`.
+ * Declare it only where neither can say: an option belonging to no function
+ * input, such as one the config factory reads straight off the CLI data.
+ */
+export type CLIOptionType = 'string' | 'number' | 'boolean' | 'string[]';
 /**
  * CLI option definition
  */
 export interface CLIOption<T = any> {
     description: string;
     short?: string;
+    type?: CLIOptionType;
     default?: T;
     choices?: T[];
-    array?: boolean;
     required?: boolean;
 }
 /**
@@ -149,7 +161,14 @@ export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMi
         [K in keyof ExtractFunctionInput<FuncConfig>]?: {
             description?: string;
             short?: string;
+            type?: CLIOptionType;
             default?: ExtractFunctionInput<FuncConfig>[K];
+            /**
+             * The values this option accepts. Rejected by the parser and listed in
+             * `--help`, so a flag with a fixed vocabulary says so once rather than
+             * repeating itself in its description.
+             */
+            choices?: ReadonlyArray<ExtractFunctionInput<FuncConfig>[K]>;
         };
     };
     middleware?: PikkuMiddleware[];