@pikku/core 0.12.63 → 0.12.66

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

@@ -100,6 +100,19 @@ export interface AIAgentOutput {
         runId: string;
     }>;
 }
+/**
+ * How an agent's threads/runs are owned and partitioned.
+ * - `'user'` (default): owner is the authenticated `session.userId`; the caller's
+ *   `resourceId` becomes a sub-partition within that user (`userId:resourceId`).
+ * - `'org'`: owner is the authenticated `session.orgId` (`orgId:resourceId`), so
+ *   threads are shared across everyone in the org. Requires a session with an org
+ *   (e.g. Better Auth's `organization` plugin) — otherwise access is denied.
+ *
+ * The trusted principal is always the prefix, so a client-supplied `resourceId`
+ * can sub-divide within the caller's own boundary but can never widen access to
+ * another user's or org's threads.
+ */
+export type SessionScope = 'user' | 'org';
 export interface AIAgentToolDef {
     name: string;
     description: string;
@@ -107,6 +120,14 @@ export interface AIAgentToolDef {
     execute: (input: unknown) => Promise<unknown>;
     needsApproval?: boolean;
     approvalDescriptionFn?: (input: unknown) => Promise<string>;
+    /**
+     * Set only by the framework on sub-agent delegating tools. Such a tool may
+     * legitimately return an `__approvalRequired` marker to forward a nested
+     * sub-agent approval. The marker is honored ONLY from a tool with this flag —
+     * a plain tool's output (which an attacker may influence) can never forge an
+     * approval request. See `checkForApprovals`.
+     */
+    forwardsApproval?: boolean;
 }
 export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
     modifyInput?: (services: Services, ctx: {
@@ -190,7 +211,7 @@ export type AIAgentMemoryConfig = {
     lastMessages?: number;
     workingMemory?: unknown;
 };
-export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string> = {
     name: string;
     description: string;
     summary?: string;
@@ -200,8 +221,11 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     goal: string;
     model: string;
     temperature?: number;
+    /** Ownership/partitioning of this agent's threads and runs. Defaults to `'user'`. */
+    sessionScope?: SessionScope;
     tools?: unknown[];
     agents?: unknown[];
+    workflows?: unknown[];
     agentMode?: 'delegate' | 'supervise';
     memory?: AIAgentMemoryConfig;
     maxSteps?: number;
@@ -220,6 +244,23 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     middleware?: PikkuMiddleware[];
     channelMiddleware?: CorePikkuChannelMiddleware<any, any>[];
     aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[];
+    /**
+     * Whether a session is required to run this agent. Defaults to `false`, since
+     * agents are commonly invoked from an already-authenticated `pikkuFunc` or
+     * from genuinely sessionless contexts (crons, queue workers). Set `true` to
+     * require a session at the agent itself. `scopes` and `permissions` are
+     * enforced either way.
+     */
+    auth?: boolean;
+    /**
+     * Scopes the session must hold to run this agent. All of them are required
+     * (AND), and they are checked before `permissions` — unlike permissions,
+     * 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.
+     */
+    scopes?: Scope[];
     permissions?: CorePermissionGroup<PikkuPermission>;
 };
 export type AIStreamEvent = {
@@ -267,6 +308,7 @@ export type AIStreamEvent = {
     toolName: string;
     args: unknown;
     reason?: string;
+    runId?: string;
     agent?: string;
     session?: string;
 } | {
@@ -388,6 +430,17 @@ export interface AgentRunService {
     listThreads(options?: {
         agentName?: string;
         resourceId?: string;
+        /**
+         * Restrict results to threads owned by one of these session principals. A
+         * thread matches when its `resourceId` is the principal itself or one of its
+         * `principal:` sub-partitions, mirroring the composition
+         * `resolveOwnerResourceId` writes.
+         *
+         * Unlike `resourceId`, which is an optional exact-match filter, this is an
+         * authorization constraint: an empty array matches nothing. Callers exposing
+         * threads over the wire must derive it from the session, never from input.
+         */
+        owners?: string[];
         limit?: number;
         offset?: number;
     }): Promise<AIThread[]>;
@@ -397,9 +450,10 @@ export interface AgentRunService {
     deleteThread(threadId: string): Promise<boolean>;
     getDistinctAgentNames(): Promise<string[]>;
 }
-export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' | 'tools' | 'agents' | 'middleware' | 'channelMiddleware' | 'aiMiddleware' | 'permissions'> & {
+export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' | 'tools' | 'agents' | 'workflows' | 'middleware' | 'channelMiddleware' | 'aiMiddleware' | 'permissions'> & {
     tools?: string[];
     agents?: string[];
+    workflows?: string[];
     inputSchema: string | null;
     outputSchema: string | null;
     workingMemorySchema: string | null;

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

@@ -1,8 +1,9 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { wrapChannelWithAGUI, type AGUIEvent } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
 export { voiceInput } from './voice-input.js';
 export { voiceOutput } from './voice-output.js';
-export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
+export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';
 export type { AIAgentInput, AIAgentInputAttachment, AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AIContentPart, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';

package/dist/wirings/ai-agent/index.js

@@ -1,7 +1,8 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { wrapChannelWithAGUI } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
 export { voiceInput } from './voice-input.js';
 export { voiceOutput } from './voice-output.js';
-export { ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
+export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';

package/dist/wirings/ai-agent/voice-input.d.ts

@@ -6,5 +6,6 @@ export declare const voiceInput: (config?: {
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;

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

@@ -1,4 +1,5 @@
 import { pikkuAIMiddleware } from '../../types/core.types.js';
+import { safeFetch } from '../../utils/safe-fetch.js';
 function base64ToUint8Array(base64) {
     const binary = atob(base64);
     const bytes = new Uint8Array(binary.length);
@@ -8,45 +9,8 @@ function base64ToUint8Array(base64) {
     return bytes;
 }
 const MAX_AUDIO_SIZE = 50 * 1024 * 1024;
-// Portable SSRF guard: @pikku/core runs in edge runtimes (CF Workers) with no
-// Node `dns`, so we cannot resolve hostnames to check for private targets.
-// Reject the obvious internal literals; callers wanting stricter control pass
-// an explicit `allowedAudioHosts` allowlist. (Does not defend against a public
-// hostname that resolves to a private IP / DNS rebinding — out of reach here.)
-function isPrivateHost(hostname) {
-    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
-    if (host === 'localhost' || host === '0.0.0.0' || host === '::1')
-        return true;
-    if (host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd'))
-        return true;
-    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.\d{1,3}$/);
-    if (v4) {
-        const [a, b] = [Number(v4[1]), Number(v4[2])];
-        if (a === 127 || a === 10 || a === 0)
-            return true;
-        if (a === 169 && b === 254)
-            return true; // link-local incl. cloud metadata
-        if (a === 172 && b >= 16 && b <= 31)
-            return true;
-        if (a === 192 && b === 168)
-            return true;
-    }
-    return false;
-}
 async function fetchAsUint8Array(url, allowedAudioHosts) {
-    const parsed = new URL(url);
-    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-        throw new Error('Only HTTP(S) URLs are supported for audio');
-    }
-    if (allowedAudioHosts) {
-        if (!allowedAudioHosts.includes(parsed.hostname)) {
-            throw new Error(`Audio URL host is not allowed: ${parsed.hostname}`);
-        }
-    }
-    else if (isPrivateHost(parsed.hostname)) {
-        throw new Error(`Refusing to fetch audio from a private/internal host: ${parsed.hostname}`);
-    }
-    const response = await fetch(url);
+    const response = await safeFetch(url, {}, { allowedHosts: allowedAudioHosts });
     const contentLength = response.headers.get('content-length');
     if (contentLength && parseInt(contentLength, 10) > MAX_AUDIO_SIZE) {
         throw new Error('Audio file exceeds maximum size');
@@ -59,8 +23,8 @@ async function fetchAsUint8Array(url, allowedAudioHosts) {
 }
 export const voiceInput = (config) => pikkuAIMiddleware({
     modifyInput: async (services, { messages, instructions }) => {
-        const transcribeAudio = services.aiAgentRunner?.transcribe;
-        if (!transcribeAudio)
+        const aiAgentRunner = services.aiAgentRunner;
+        if (!aiAgentRunner?.transcribe)
             return { messages, instructions };
         const last = messages[messages.length - 1];
         if (!last || last.role !== 'user' || typeof last.content === 'string') {
@@ -87,7 +51,7 @@ export const voiceInput = (config) => pikkuAIMiddleware({
             const audioData = p.data
                 ? base64ToUint8Array(p.data)
                 : await fetchAsUint8Array(p.url, config.allowedAudioHosts);
-            const result = await transcribeAudio({
+            const result = await aiAgentRunner.transcribe({
                 model: config.model,
                 audio: audioData,
                 ...(config.language

package/dist/wirings/ai-agent/voice-output.d.ts

@@ -12,6 +12,7 @@ export declare const voiceOutput: (config?: {
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;
 export {};

package/dist/wirings/channel/channel-common.js

@@ -42,7 +42,6 @@ export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, l
             data: () => data,
             wire,
             tags: meta.tags ?? [],
-            inheritedPermissions: meta.permissions,
             packageName: meta.packageName ?? null,
         });
     };

package/dist/wirings/channel/channel-handler.js

@@ -49,7 +49,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             return;
         }
         const routeMeta = getRouteMeta(channelConfig.name, routingProperty, routerValue);
-        const { packageName, middleware: routeInheritedMiddleware, permissions: inheritedPermissions, } = routeMeta;
+        const { packageName, middleware: routeInheritedMiddleware } = routeMeta;
         const pikkuFuncId = routeMeta.pikkuFuncId;
         // Get wire middleware: channel-level middleware + message-specific middleware
         const channelWireMiddleware = channelConfig.middleware || [];
@@ -68,7 +68,6 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
         const wireMiddleware = [...channelWireMiddleware, ...messageWireMiddleware];
         // Inherited middleware comes from metadata (tag groups, non-inline wire)
         const inheritedMiddleware = routeInheritedMiddleware || [];
-        const wirePermissions = isWrapper ? onMessage.permissions : undefined;
         // Create unique cache key that includes routing info to avoid cache collisions
         // when multiple message handlers use the same function
         const cacheKey = routingProperty
@@ -83,8 +82,6 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             wireMiddleware,
             inheritedChannelMiddleware: channelMeta?.channelMiddleware,
             wireChannelMiddleware: wireChannelMiddleware,
-            inheritedPermissions,
-            wirePermissions,
             coerceDataFromSchema: true,
             tags: channelConfig.tags,
             sessionService: userSession,

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

@@ -2,6 +2,18 @@ import type { CoreSingletonServices, MiddlewareMetadata, PikkuRawWire } from '..
 import type { CorePikkuChannelMiddleware } from './channel.types.js';
 export declare const addChannelMiddleware: (tag: string, middleware: CorePikkuChannelMiddleware[], packageName?: string | null) => CorePikkuChannelMiddleware[];
 export declare const clearChannelMiddlewareCache: () => void;
+/**
+ * Combine the inherited (tag/named) channel middleware with any per-run
+ * middleware for a wiring.
+ *
+ * Only the statically-resolved inherited middleware is deterministic per `uid`
+ * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
+ * an AI agent's per-invocation stream middleware holding that run's
+ * thread/session state) and MUST NOT be cached — caching it lets a later run of
+ * the same `uid` reuse an earlier run's closures, leaking that run's state (and
+ * growing memory) across invocations. It is therefore appended fresh on every
+ * call after the cached inherited slice.
+ */
 export declare const combineChannelMiddleware: (wireType: string, uid: string, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName, }?: {
     wireInheritedChannelMiddleware?: MiddlewareMetadata[];
     wireChannelMiddleware?: CorePikkuChannelMiddleware[];

package/dist/wirings/channel/channel-middleware-runner.js

@@ -16,33 +16,48 @@ export const clearChannelMiddlewareCache = () => {
         delete channelMiddlewareCache[key];
     }
 };
+/**
+ * Combine the inherited (tag/named) channel middleware with any per-run
+ * middleware for a wiring.
+ *
+ * Only the statically-resolved inherited middleware is deterministic per `uid`
+ * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
+ * an AI agent's per-invocation stream middleware holding that run's
+ * thread/session state) and MUST NOT be cached — caching it lets a later run of
+ * the same `uid` reuse an earlier run's closures, leaking that run's state (and
+ * growing memory) across invocations. It is therefore appended fresh on every
+ * call after the cached inherited slice.
+ */
 export const combineChannelMiddleware = (wireType, uid, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName = null, } = {}) => {
     const cacheKey = `${wireType}:${uid}`;
-    if (channelMiddlewareCache[cacheKey]) {
-        return channelMiddlewareCache[cacheKey];
-    }
-    const resolved = [];
-    if (wireInheritedChannelMiddleware) {
-        for (const meta of wireInheritedChannelMiddleware) {
-            if (meta.type === 'tag') {
-                const groups = getTagGroups(pikkuState(packageName, 'channelMiddleware', 'tagGroup'), meta.tag);
-                for (const group of groups) {
-                    resolved.push(...group);
+    let inherited = channelMiddlewareCache[cacheKey];
+    if (!inherited) {
+        const resolved = [];
+        if (wireInheritedChannelMiddleware) {
+            for (const meta of wireInheritedChannelMiddleware) {
+                if (meta.type === 'tag') {
+                    const groups = getTagGroups(pikkuState(packageName, 'channelMiddleware', 'tagGroup'), meta.tag);
+                    for (const group of groups) {
+                        resolved.push(...group);
+                    }
                 }
-            }
-            else if (meta.type === 'wire') {
-                const middleware = getChannelMiddlewareByName(meta.name);
-                if (middleware) {
-                    resolved.push(middleware);
+                else if (meta.type === 'wire') {
+                    const middleware = getChannelMiddlewareByName(meta.name);
+                    if (middleware) {
+                        resolved.push(middleware);
+                    }
                 }
             }
         }
+        inherited = channelMiddlewareCache[cacheKey] = freezeDedupe(resolved);
     }
-    if (wireChannelMiddleware) {
-        resolved.push(...wireChannelMiddleware);
+    if (!wireChannelMiddleware?.length) {
+        return inherited;
     }
-    channelMiddlewareCache[cacheKey] = freezeDedupe(resolved);
-    return channelMiddlewareCache[cacheKey];
+    return freezeDedupe([
+        ...inherited,
+        ...wireChannelMiddleware,
+    ]);
 };
 export function wrapChannelWithMiddleware(wire, services, middlewares) {
     if (middlewares.length === 0 || !wire.channel)

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

@@ -1,9 +1,9 @@
 import type { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.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>;
-import type { CorePermissionGroup, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+import type { CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -24,7 +24,6 @@ export interface ChannelMessageMeta {
     errors?: string[];
     tags?: string[];
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
 }
 export interface ChannelMeta {
     name: string;
@@ -43,7 +42,6 @@ export interface ChannelMeta {
     errors?: string[];
     tags?: string[];
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
     channelMiddleware?: MiddlewareMetadata[];
 }
 export type ChannelsMeta = Record<string, ChannelMeta>;
@@ -61,13 +59,11 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
     onMessage?: ChannelFunctionMessage;
     onMessageWiring?: Record<string, Record<string, ChannelFunctionMessage | {
         func: ChannelFunctionMessage;
-        permissions?: CorePermissionGroup<PikkuPermission>;
         auth?: boolean;
         middleware?: PikkuMiddleware[];
     }>>;
     middleware?: PikkuMiddleware[];
     channelMiddleware?: Array<CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory>;
-    permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: boolean;
     binary?: boolean | null;
     onBinaryMessage?: (services: any, data: BinaryData, channel: PikkuChannel<ChannelData, any>) => Promise<BinaryData | void> | BinaryData | void;

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

@@ -253,8 +253,6 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             auth: false,
             inheritedMiddleware: currentCommand.middleware,
             wireMiddleware: allWireMiddleware,
-            inheritedPermissions: currentCommand.permissions,
-            wirePermissions: undefined,
             coerceDataFromSchema: true,
             tags: programData?.tags,
             wire,
@@ -321,6 +319,9 @@ export async function executeCLI({ programName, args, createConfig, createSingle
             console.log(helpText);
             return;
         }
+        // Non-fatal diagnostics (unknown options are still accepted) go to stderr
+        // so they never pollute a command's machine-readable stdout.
+        parsed.warnings.forEach((warning) => console.error(`Warning: ${warning}`));
         if (parsed.errors.length > 0) {
             // Check if any error is about an unknown command
             const hasUnknownCommand = parsed.errors.some((error) => error.startsWith('Unknown command:') ||

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

@@ -1,4 +1,4 @@
-import type { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuFunction, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 /**
@@ -62,7 +62,6 @@ export interface CLICommandMeta {
     tags?: string[];
     subcommands?: Record<string, CLICommandMeta>;
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
     isDefault?: boolean;
 }
 /**

package/dist/wirings/cli/command-parser.d.ts

@@ -8,6 +8,8 @@ export interface ParsedCommand {
     positionals: Record<string, any>;
     options: Record<string, any>;
     errors: string[];
+    /** Non-fatal diagnostics (e.g. unknown options that were accepted+ignored) */
+    warnings: string[];
 }
 /**
  * Parses raw CLI arguments into structured data for a specific program

package/dist/wirings/cli/command-parser.js

@@ -8,6 +8,54 @@ function toCamelCase(str) {
 function toKebabCase(str) {
     return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
+/** Options the runner handles itself — never reported as unknown. */
+const RESERVED_OPTIONS = new Set(['help']);
+/** Levenshtein distance, capped-free and dependency-free. Used only to suggest
+ *  a near-miss option name, so the naive O(n*m) implementation is fine. */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min(row[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/** Finds the closest declared option (distance <= 2) to what the user typed.
+ *  Compares against the kebab-case rendering, since that is what is typed. */
+function suggestOption(typed, availableOptions) {
+    let best = null;
+    let bestDistance = 3;
+    for (const name of Object.keys(availableOptions)) {
+        const kebab = toKebabCase(name);
+        const distance = Math.min(levenshtein(typed, kebab), levenshtein(typed, name));
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = kebab;
+        }
+    }
+    return best;
+}
+/** Records a warning that an unknown long option was accepted but ignored.
+ *  Unknown options stay non-fatal for forward compatibility (a newer command
+ *  version may understand them) — they are just no longer silent. */
+function warnUnknownOption(typed, availableOptions, result) {
+    if (RESERVED_OPTIONS.has(toCamelCase(typed))) {
+        return;
+    }
+    const suggestion = suggestOption(typed, availableOptions);
+    result.warnings.push(`Unknown option: --${typed} (ignored)` +
+        (suggestion ? ` Did you mean --${suggestion}?` : ''));
+}
 /**
  * Parses raw CLI arguments into structured data for a specific program
  */
@@ -18,6 +66,7 @@ export function parseCLIArguments(args, programName, allMeta) {
         positionals: {},
         options: {},
         errors: [],
+        warnings: [],
     };
     const meta = allMeta.programs[programName];
     if (!meta) {
@@ -106,7 +155,11 @@ export function parseCLIArguments(args, programName, allMeta) {
                 // --option=value format
                 const key = toCamelCase(arg.slice(2, equalIndex));
                 const optionDef = availableOptions[key];
-                // Unknown options are allowed for forward compatibility
+                // Unknown options are allowed for forward compatibility, but warned
+                // about so they are not silently dropped by the input schema.
+                if (!optionDef) {
+                    warnUnknownOption(arg.slice(2, equalIndex), availableOptions, result);
+                }
                 const value = arg.slice(equalIndex + 1);
                 optionArgs[key] = parseOptionValue(value, optionDef);
             }
@@ -114,7 +167,11 @@ export function parseCLIArguments(args, programName, allMeta) {
                 // --option value format
                 const key = toCamelCase(arg.slice(2));
                 const optionDef = availableOptions[key];
-                // Unknown options are allowed for forward compatibility
+                // Unknown options are allowed for forward compatibility, but warned
+                // about so they are not silently dropped by the input schema.
+                if (!optionDef) {
+                    warnUnknownOption(arg.slice(2), availableOptions, result);
+                }
                 if (optionDef && optionDef.array) {
                     // Array option - collect all following non-flag values
                     currentIndex++;

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

@@ -5,6 +5,13 @@ export type CoreCredential<T = unknown> = {
     description?: string;
     type: 'singleton' | 'wire';
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig & {
         appCredentialSecretId: string;
     };
@@ -15,6 +22,13 @@ export type CredentialDefinitionMeta = {
     description?: string;
     type: 'singleton' | 'wire';
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig & {
         appCredentialSecretId: string;
     };

package/dist/wirings/credential/validate-credential-definitions.js

@@ -31,6 +31,7 @@ export function validateAndBuildCredentialDefinitionsMeta(definitions, schemaLoo
             type: def.type,
             schema: def.schema,
             oauth2: def.oauth2,
+            docsUrl: def.docsUrl,
             sourceFile: def.sourceFile,
         };
     }