@pikku/core 0.12.64 → 0.12.67

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

@@ -34,6 +34,49 @@ export declare function agentSessionScope(agentName: string): SessionScope;
  * existence oracle) on a mismatch.
  */
 export declare function assertResourceOwner(ownerResourceId: string, storedResourceId: string, kind: 'thread' | 'run'): void;
+/** A session's trusted principals, in the order they may be read as. */
+export declare function sessionPrincipals(session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): string[];
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export declare function isOwnedByPrincipal(storedResourceId: string, principal: string): boolean;
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export declare function threadOwnerConstraint(session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): string[] | undefined;
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export declare function canAccessThread(storedResourceId: string, session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): boolean;
 export type StreamAIAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
     /**
@@ -93,6 +136,27 @@ export declare const resolveAgent: (agentName: string) => {
     packageName: string | null;
     resolvedName: string;
 };
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export declare function assertAgentAuthorized(agent: CoreAIAgent, params: RunAIAgentParams, packageName: string | null): Promise<void>;
 export declare function buildInstructions(agentName: string, packageName: string | null): Promise<string>;
 export type ScopedChannel = AIStreamChannel & {
     approvals: Array<{

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

@@ -1,7 +1,8 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions } from '../../permissions.js';
+import { checkAuthPermissions, runPermissions } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { ForbiddenError } from '../../errors/errors.js';
+import { verifyScopes } from '../../scopes.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from './ai-agent-utils.js';
@@ -62,6 +63,53 @@ export function assertResourceOwner(ownerResourceId, storedResourceId, kind) {
         throw new ForbiddenError(`Not authorized to access this ${kind}`);
     }
 }
+/** A session's trusted principals, in the order they may be read as. */
+export function sessionPrincipals(session) {
+    return [session?.userId, session?.orgId].filter((principal) => Boolean(principal));
+}
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export function isOwnedByPrincipal(storedResourceId, principal) {
+    return (storedResourceId === principal ||
+        storedResourceId.startsWith(`${principal}:`));
+}
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export function threadOwnerConstraint(session) {
+    const principals = sessionPrincipals(session);
+    return principals.length > 0 ? principals : undefined;
+}
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export function canAccessThread(storedResourceId, session) {
+    const principals = sessionPrincipals(session);
+    if (principals.length === 0)
+        return true;
+    return principals.some((principal) => isOwnedByPrincipal(storedResourceId, principal));
+}
 /**
  * Non-forgeable brand for the sub-agent approval marker. Only framework code
  * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
@@ -163,6 +211,47 @@ export const resolveAgent = (agentName) => {
     }
     throw new Error(`AI agent not found: ${agentName}`);
 };
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export async function assertAgentAuthorized(agent, params, packageName) {
+    const session = params.sessionService
+        ? await params.sessionService.get()
+        : undefined;
+    if (agent.auth === true && !session) {
+        throw new ForbiddenError('Authentication required');
+    }
+    verifyScopes(agent.scopes, session);
+    const singletonServices = getSingletonServices();
+    const wire = params.sessionService
+        ? createMiddlewareSessionWireProps(params.sessionService)
+        : { session: undefined };
+    await runPermissions({
+        funcPermissions: agent.permissions,
+        services: singletonServices,
+        wire: wire,
+        data: {},
+        packageName,
+        label: 'agent',
+    });
+}
 export async function buildInstructions(agentName, packageName) {
     const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
     const parts = [];
@@ -279,11 +368,17 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 missingRpcs.push(toolName);
                 continue;
             }
-            // Filter out tools the user doesn't have auth for
+            // Filter out tools the user doesn't have auth for. The `pikkuAuth` brand
+            // only survives on the live permission objects in the function config, so
+            // the check reads those rather than the metadata (whose by-name registry
+            // is never populated, which would let every gated tool through).
             if (fnMeta.permissions?.length) {
                 if (!session)
                     continue;
-                const allowed = await checkAuthPermissions(fnMeta.permissions, session, singletonServices, resolvedPkg);
+                const funcConfig = pikkuFuncId
+                    ? pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId)
+                    : undefined;
+                const allowed = await checkAuthPermissions(funcConfig?.permissions, session, singletonServices, resolvedPkg);
                 if (!allowed)
                     continue;
             }
@@ -351,11 +446,13 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 singletonServices.logger.warn(`Sub-agent '${subAgentName}' not found in agent registry`);
                 continue;
             }
-            // Filter out sub-agents the user doesn't have auth for
+            // Filter out sub-agents the user doesn't have auth for, reading the live
+            // agent config for the same reason the tool path does.
             if (subMeta.permissions?.length) {
                 if (!session)
                     continue;
-                const allowed = await checkAuthPermissions(subMeta.permissions, session, singletonServices);
+                const subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName);
+                const allowed = await checkAuthPermissions(subAgent?.permissions, session, singletonServices);
                 if (!allowed)
                     continue;
             }
@@ -567,6 +664,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
 export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
     const singletonServices = getSingletonServices();
     const { agent, packageName, resolvedName } = resolveAgent(agentName);
+    await assertAgentAuthorized(agent, params, packageName);
     let agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
         throw new AIProviderNotConfiguredError();

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

@@ -1,5 +1,5 @@
 import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, } from './ai-agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
@@ -293,6 +293,10 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         throw new Error(`Run ${runId} is not suspended (status: ${run.status})`);
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
+    // Resuming re-runs the agent, so it re-runs the agent's gate. Run ownership
+    // alone is not enough: a grant revoked while the run was suspended must stop
+    // the caller from approving its pending tool calls.
+    await assertAgentAuthorized(agent, params, packageName);
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;

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

@@ -3,9 +3,9 @@ import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
-function createPersistingChannel(parent, storage, threadId) {
+function createPersistingChannel(parent, storage, threadId, logger) {
     let fullText = '';
     let stepText = '';
     let stepGenerativeUI = null;
@@ -51,6 +51,22 @@ function createPersistingChannel(parent, storage, threadId) {
             await storage.saveMessages(threadId, messages);
         }
     };
+    /**
+     * `send` is synchronous and so cannot await the flush. A rejection would have
+     * nothing to propagate to and would take the process down as an unhandled
+     * rejection — a model reusing a toolCallId, which is a primary key in AI
+     * storage, is enough to trigger it. Persistence from inside `send` is
+     * therefore best-effort: the run carries on, and the awaited `flush()` on the
+     * suspend paths still surfaces failures to its caller.
+     */
+    const flushDetached = () => {
+        void flushStep().catch((error) => {
+            logger?.error('Failed to persist agent messages', {
+                threadId,
+                error,
+            });
+        });
+    };
     const channel = {
         channelId: parent.channelId,
         openingData: parent.openingData,
@@ -97,10 +113,10 @@ function createPersistingChannel(parent, storage, threadId) {
                         totalUsage.outputTokens += event.tokens.output;
                         if (event.model)
                             totalUsage.model = event.model;
-                        flushStep();
+                        flushDetached();
                         break;
                     case 'done':
-                        flushStep();
+                        flushDetached();
                         break;
                 }
             }
@@ -469,7 +485,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             ...streamMiddleware,
         ],
     });
-    const persistingChannel = createPersistingChannel(channel, storage, threadId);
+    const persistingChannel = createPersistingChannel(channel, storage, threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;
@@ -578,8 +594,13 @@ export async function resumeAIAgent(input, channel, params, options) {
     if (!pending) {
         throw new Error(`No pending approval for toolCallId ${input.toolCallId} on run ${input.runId}`);
     }
-    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
+    // Gate before resolving the approval: recording it is a persisted side
+    // effect, so an unauthorized caller must not reach it. Run ownership alone is
+    // not enough — a grant revoked while the run was suspended must stop the
+    // caller from approving its pending tool calls.
+    await assertAgentAuthorized(agent, params, packageName);
+    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
@@ -807,7 +828,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             ...streamMiddleware,
         ],
     });
-    const persistingChannel = createPersistingChannel(channel, storage, run.threadId);
+    const persistingChannel = createPersistingChannel(channel, storage, run.threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;

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

@@ -211,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;
@@ -244,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 = {
@@ -413,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[]>;

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

@@ -4,6 +4,6 @@ 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

@@ -4,5 +4,5 @@ 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.js

@@ -23,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') {
@@ -51,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/cli/cli-runner.js

@@ -319,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/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,
         };
     }