@pikku/core 0.12.82 → 0.12.84

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

@@ -0,0 +1,15 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import { type ScorerInput } from './agent-scorer.types.js';
+/**
+ * Grade one finished run on live traffic.
+ *
+ * Called as the terminal step of `finalizeAgentRun`, so it is structurally last
+ * — a developer cannot register anything after it, and cannot reorder it. It is
+ * also strictly best-effort: the client already has its answer, so nothing here
+ * may fail the run.
+ */
+export declare const scoreFinishedRun: (run: ScorerInput, services: Pick<CoreSingletonServices, "logger"> & {
+    queueService?: {
+        add: (queueName: string, data: unknown) => Promise<any>;
+    };
+}) => Promise<void>;

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

@@ -0,0 +1,38 @@
+import { scorersForAgent } from './agent-scorer-registry.js';
+import { isSampled } from './agent-scorer-sampling.js';
+import { SCORER_LANE_QUEUES } from './agent-scorer.types.js';
+/**
+ * Grade one finished run on live traffic.
+ *
+ * Called as the terminal step of `finalizeAgentRun`, so it is structurally last
+ * — a developer cannot register anything after it, and cannot reorder it. It is
+ * also strictly best-effort: the client already has its answer, so nothing here
+ * may fail the run.
+ */
+export const scoreFinishedRun = async (run, services) => {
+    const scorers = scorersForAgent(run.agentName, services.logger).filter(
+    // A reference-based judge grades against an answer key, and live traffic
+    // has none.
+    (scorer) => !scorer.requiresReference);
+    if (scorers.length === 0)
+        return;
+    if (!services.queueService) {
+        services.logger?.warn(`[pikku] Agent '${run.agentName}' declares scorers but no queue service is registered — skipping live scoring`);
+        return;
+    }
+    const sampled = scorers.filter((scorer) => isSampled(run.runId, scorer.name, scorer.sampleRate));
+    // One message per scorer, so each gets its own retry, isolation and lane.
+    await Promise.all(sampled.map(async (scorer) => {
+        try {
+            await services.queueService.add(SCORER_LANE_QUEUES[scorer.lane], {
+                ...run,
+                scorerName: scorer.name,
+                // No reference: a live run has no answer key.
+                reference: undefined,
+            });
+        }
+        catch (error) {
+            services.logger?.error(`[pikku] Failed to enqueue the '${scorer.name}' grade of run ${run.runId}`, { error });
+        }
+    }));
+};

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

@@ -0,0 +1,18 @@
+import type { PikkuAgentScorer } from './agent-scorer.types.js';
+export declare const addAgentScorer: (scorerName: string, scorer: PikkuAgentScorer<any>, packageName?: string | null) => void;
+export declare const getAgentScorers: () => Map<string, PikkuAgentScorer>;
+export declare const getAgentScorersMeta: () => import("./agent-scorer.types.js").ScorerMeta;
+/**
+ * Resolve a scorer by name across every registered package, the way an agent's
+ * tools are resolved: a scorer declared in an addon is nameable by an app agent.
+ */
+export declare const resolveAgentScorer: (scorerName: string) => PikkuAgentScorer<any>;
+/**
+ * The scorers an agent asked to be graded by.
+ *
+ * A name that resolves to nothing is warned about rather than thrown: a missing
+ * scorer must not take down a run that has already answered the user.
+ */
+export declare const scorersForAgent: (agentName: string, logger?: {
+    warn: (message: string) => void;
+}) => PikkuAgentScorer<any>[];

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

@@ -0,0 +1,46 @@
+import { pikkuState } from '../../pikku-state.js';
+export const addAgentScorer = (scorerName, scorer, packageName = null) => {
+    const scorersMeta = pikkuState(packageName, 'agent', 'scorersMeta');
+    if (!scorersMeta[scorerName]) {
+        console.warn(`[pikku] Skipping AI scorer '${scorerName}' — metadata not found. Scorers must be declared in a *.scorer.ts file.`);
+        return;
+    }
+    const scorers = pikkuState(packageName, 'agent', 'scorers');
+    if (scorers.has(scorerName)) {
+        throw new Error(`AI scorer already exists: ${scorerName}`);
+    }
+    scorers.set(scorerName, scorer);
+};
+export const getAgentScorers = () => pikkuState(null, 'agent', 'scorers');
+export const getAgentScorersMeta = () => pikkuState(null, 'agent', 'scorersMeta');
+/**
+ * Resolve a scorer by name across every registered package, the way an agent's
+ * tools are resolved: a scorer declared in an addon is nameable by an app agent.
+ */
+export const resolveAgentScorer = (scorerName) => {
+    const scorer = pikkuState(null, 'agent', 'scorers').get(scorerName);
+    if (!scorer) {
+        throw new Error(`AI scorer not found: ${scorerName}`);
+    }
+    return scorer;
+};
+/**
+ * The scorers an agent asked to be graded by.
+ *
+ * A name that resolves to nothing is warned about rather than thrown: a missing
+ * scorer must not take down a run that has already answered the user.
+ */
+export const scorersForAgent = (agentName, logger) => {
+    const agent = pikkuState(null, 'agent', 'agents').get(agentName);
+    const names = agent?.scorers ?? [];
+    const scorers = [];
+    for (const name of names) {
+        const scorer = pikkuState(null, 'agent', 'scorers').get(name);
+        if (!scorer) {
+            logger?.warn(`[pikku] Agent '${agentName}' names scorer '${name}', which is not registered — skipping it`);
+            continue;
+        }
+        scorers.push(scorer);
+    }
+    return scorers;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Decide whether one run is in a scorer's sample.
+ *
+ * Deterministic on `(runId, scorerName)` rather than random, so re-running the
+ * decision — a retried job, a replayed run, a test — always lands the same way,
+ * and so two scorers at the same rate do not sample the same runs.
+ */
+export declare const isSampled: (runId: string, scorerName: string, sampleRate: number) => boolean;

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

@@ -0,0 +1,31 @@
+/**
+ * Decide whether one run is in a scorer's sample.
+ *
+ * Deterministic on `(runId, scorerName)` rather than random, so re-running the
+ * decision — a retried job, a replayed run, a test — always lands the same way,
+ * and so two scorers at the same rate do not sample the same runs.
+ */
+export const isSampled = (runId, scorerName, sampleRate) => {
+    if (sampleRate >= 1)
+        return true;
+    if (sampleRate <= 0)
+        return false;
+    const key = `${scorerName}:${runId}`;
+    // FNV-1a: no crypto dependency, and stable across processes and platforms,
+    // which a language-level string hash is not guaranteed to be.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        hash ^= key.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    // FNV-1a alone leaves its high bits barely moved between keys that differ
+    // only in their last characters — sequential run ids being exactly that —
+    // which biases the fraction actually sampled well away from the rate asked
+    // for. MurmurHash3's finalizer spreads the low bits back over the whole word.
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x85ebca6b) >>> 0;
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 0xc2b2ae35) >>> 0;
+    hash ^= hash >>> 16;
+    return (hash >>> 0) / 0x100000000 < sampleRate;
+};

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

@@ -0,0 +1,10 @@
+import type { ScorerInput } from './agent-scorer.types.js';
+/**
+ * Start retaining snapshots. Called where the scenario grading RPC is
+ * registered, so the buffer exists in exactly the processes that can read it —
+ * a development server — and never in a deployed bundle.
+ */
+export declare const enableScoreSnapshots: (maxRuns?: number) => void;
+export declare const recordScoreSnapshot: (run: ScorerInput) => void;
+export declare const getScoreSnapshot: (runId: string) => ScorerInput | undefined;
+export declare const resetScoreSnapshots: () => void;

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

@@ -0,0 +1,40 @@
+/**
+ * The last few finished runs, held so a scenario can grade one.
+ *
+ * A scenario cannot rebuild a `ScorerInput` from storage: the run record holds
+ * status and usage, and the prompt, answer and tool calls are spread across the
+ * thread's messages, where the boundary of a single run is not recoverable. So
+ * the runtime keeps the snapshot it already took at finalize — which is also
+ * what makes a scenario's grade comparable to a live one, since both grade the
+ * identical object, redactions included.
+ *
+ * Off unless something turns it on, and bounded when it is. A process that
+ * grades no scenarios holds nothing, and one that does cannot accumulate run
+ * content without limit.
+ */
+const snapshots = new Map();
+let limit = 0;
+/**
+ * Start retaining snapshots. Called where the scenario grading RPC is
+ * registered, so the buffer exists in exactly the processes that can read it —
+ * a development server — and never in a deployed bundle.
+ */
+export const enableScoreSnapshots = (maxRuns = 50) => {
+    limit = maxRuns;
+};
+export const recordScoreSnapshot = (run) => {
+    if (limit === 0)
+        return;
+    snapshots.set(run.runId, run);
+    while (snapshots.size > limit) {
+        const oldest = snapshots.keys().next().value;
+        if (oldest === undefined)
+            break;
+        snapshots.delete(oldest);
+    }
+};
+export const getScoreSnapshot = (runId) => snapshots.get(runId);
+export const resetScoreSnapshots = () => {
+    snapshots.clear();
+    limit = 0;
+};

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

@@ -0,0 +1,15 @@
+import { type ScoreJob } from './agent-scorer.types.js';
+/**
+ * The one worker behind both lanes: it resolves the scorer by name and grades.
+ * The lane a job arrived on decides nothing except how long it may take.
+ */
+export declare function pikkuAgentScoreWorkerFunc(_services: Record<string, unknown>, job: ScoreJob): Promise<void>;
+/**
+ * Bind the two lane queues to the shared worker.
+ *
+ * Registered programmatically rather than emitted into the user's bootstrap:
+ * `wireQueueWorker` warns and returns for a name codegen produced no metadata
+ * for, so the metadata is synthesised here alongside the registration. This
+ * mirrors how workflows wire their own queues.
+ */
+export declare const wireAgentScorerQueueWorkers: () => void;

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

@@ -0,0 +1,60 @@
+import { pikkuState } from '../../pikku-state.js';
+import { addFunction } from '../../function/function-runner.js';
+import { wireQueueWorker } from '../queue/queue-runner.js';
+import { gradeRun } from './agent-scorer-grade.js';
+import { SCORER_LANE_QUEUES } from './agent-scorer.types.js';
+/**
+ * The one worker behind both lanes: it resolves the scorer by name and grades.
+ * The lane a job arrived on decides nothing except how long it may take.
+ */
+export async function pikkuAgentScoreWorkerFunc(_services, job) {
+    const services = pikkuState(null, 'package', 'singletonServices');
+    if (!services) {
+        throw new Error(`Singleton services not initialized: cannot run the '${job.scorerName}' grade of run ${job.runId}`);
+    }
+    await gradeRun(job, services, { persist: true });
+}
+const SCORE_WORKER_FUNC_ID = 'pikkuAgentScoreWorker';
+/**
+ * Bind the two lane queues to the shared worker.
+ *
+ * Registered programmatically rather than emitted into the user's bootstrap:
+ * `wireQueueWorker` warns and returns for a name codegen produced no metadata
+ * for, so the metadata is synthesised here alongside the registration. This
+ * mirrors how workflows wire their own queues.
+ */
+export const wireAgentScorerQueueWorkers = () => {
+    // No scorers means no lanes: a deployment that grades nothing should not be
+    // left holding two queues nothing ever writes to.
+    if (pikkuState(null, 'agent', 'scorers').size === 0)
+        return;
+    const functions = pikkuState(null, 'function', 'functions');
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    const queueMeta = pikkuState(null, 'queue', 'meta');
+    if (!functions.has(SCORE_WORKER_FUNC_ID)) {
+        addFunction(SCORE_WORKER_FUNC_ID, {
+            func: pikkuAgentScoreWorkerFunc,
+        });
+    }
+    if (!functionsMeta[SCORE_WORKER_FUNC_ID]) {
+        functionsMeta[SCORE_WORKER_FUNC_ID] = {
+            pikkuFuncId: SCORE_WORKER_FUNC_ID,
+            sessionless: true,
+            functionType: 'helper',
+            inputSchemaName: null,
+            outputSchemaName: null,
+        };
+    }
+    for (const queueName of Object.values(SCORER_LANE_QUEUES)) {
+        if (!queueMeta[queueName]) {
+            queueMeta[queueName] = {
+                pikkuFuncId: SCORE_WORKER_FUNC_ID,
+                name: queueName,
+            };
+        }
+        wireQueueWorker({
+            name: queueName,
+            func: { func: pikkuAgentScoreWorkerFunc },
+        });
+    }
+};

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

@@ -0,0 +1,39 @@
+import type { 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.
+ */
+export declare const pikkuAgentScorer: <Services = any>(config: {
+    name: string;
+    description: string;
+    /** 0..1 fraction of live runs to grade. Defaults to all of them. */
+    sampleRate?: number;
+    /**
+     * Grades against a known-correct answer. Such a scorer is test-only — live
+     * traffic has no answer key, so the runtime never samples it.
+     */
+    requiresReference?: boolean;
+    score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>;
+}) => PikkuAgentScorer<Services>;
+/**
+ * An LLM-judge scorer: the runtime makes the model call and forces a structured
+ * `{ score, reason }`, so a judge is a rubric rather than a prompt to parse.
+ *
+ * The rubric field is `goal`, matching `pikkuAgent`'s prompt vocabulary — a
+ * judge is a degenerate agent, and should use the same word for the same thing.
+ * `prompt` is the escape hatch for non-standard framing.
+ */
+export declare const pikkuAgentJudge: <Services = any>(config: {
+    name: string;
+    description: string;
+    /** 0..1 fraction of live runs to grade. Defaults to all of them. */
+    sampleRate?: number;
+    /**
+     * Grades against a known-correct answer. Such a judge is test-only — live
+     * traffic has no answer key, so the runtime never samples it.
+     */
+    requiresReference?: boolean;
+    model: string;
+    goal: string;
+    prompt?: (input: ScorerInput) => string;
+}) => PikkuAgentScorer<Services>;

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

@@ -0,0 +1,40 @@
+const assertSampleRate = (name, sampleRate) => {
+    if (sampleRate === undefined)
+        return 1;
+    if (sampleRate < 0 || sampleRate > 1) {
+        throw new Error(`Scorer '${name}' has a sampleRate of ${sampleRate} — it is a fraction of live runs to grade, so it must be between 0 and 1`);
+    }
+    return sampleRate;
+};
+/**
+ * A heuristic scorer: pure code over the finished run, no model call, so it
+ * grades on the fast lane.
+ */
+export const pikkuAgentScorer = (config) => ({
+    name: config.name,
+    description: config.description,
+    lane: 'fast',
+    sampleRate: assertSampleRate(config.name, config.sampleRate),
+    requiresReference: config.requiresReference ?? false,
+    score: config.score,
+});
+/**
+ * An LLM-judge scorer: the runtime makes the model call and forces a structured
+ * `{ score, reason }`, so a judge is a rubric rather than a prompt to parse.
+ *
+ * The rubric field is `goal`, matching `pikkuAgent`'s prompt vocabulary — a
+ * judge is a degenerate agent, and should use the same word for the same thing.
+ * `prompt` is the escape hatch for non-standard framing.
+ */
+export const pikkuAgentJudge = (config) => ({
+    name: config.name,
+    description: config.description,
+    lane: 'slow',
+    sampleRate: assertSampleRate(config.name, config.sampleRate),
+    requiresReference: config.requiresReference ?? false,
+    judge: {
+        model: config.model,
+        goal: config.goal,
+        ...(config.prompt ? { prompt: config.prompt } : {}),
+    },
+});

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

@@ -0,0 +1,90 @@
+/**
+ * What a scorer is shown about a finished run.
+ *
+ * One snapshot, taken after the output middleware has resolved, so a scorer and
+ * the persisted run record see the same thing — including the redactions.
+ */
+export interface ScorerInput {
+    runId: string;
+    agentName: string;
+    threadId?: string;
+    resourceId?: string;
+    /** The user prompt the run answered. */
+    input: string;
+    /** The agent's final text answer. */
+    output: string;
+    /**
+     * The known-correct answer. Supplied by a scenario for a reference-based
+     * judge; never set on live traffic, which has no answer key.
+     */
+    reference?: string;
+    toolCalls: {
+        name: string;
+        args: unknown;
+        result?: unknown;
+        error?: string;
+    }[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        model?: string;
+    };
+}
+export interface ScorerOutput {
+    /** 0..1, so grades are comparable across scorers. */
+    score: number;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The queue a scorer's jobs go to. Two lanes exist only so a flood of slow
+ * LLM-judge jobs cannot starve the cheap heuristic ones; within a lane it is
+ * plain FIFO.
+ */
+export type ScorerLane = 'fast' | 'slow';
+export declare const SCORER_LANE_QUEUES: Record<ScorerLane, string>;
+/**
+ * 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
+ * two is set, which is what the two constructors exist to guarantee.
+ */
+export type ScorerJudgeConfig = {
+    model: string;
+    goal: string;
+    prompt?: (input: ScorerInput) => string;
+};
+export type PikkuAgentScorer<Services = any> = {
+    name: string;
+    description: string;
+    lane: ScorerLane;
+    /** 0..1 fraction of live runs to grade. */
+    sampleRate: number;
+    /**
+     * Grades against a known-correct answer, so it is test-only: live traffic has
+     * no answer key and the runtime never samples it.
+     */
+    requiresReference: boolean;
+    score?: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>;
+    judge?: ScorerJudgeConfig;
+};
+export type ScorerMeta = Record<string, {
+    name: string;
+    description: string;
+    lane: ScorerLane;
+    sampleRate: number;
+    requiresReference: boolean;
+    sourceFile?: string;
+    exportedName?: string;
+}>;
+/** A single scorer's job on a lane queue. */
+export type ScoreJob = ScorerInput & {
+    scorerName: string;
+};
+export type AgentRunScore = {
+    runId: string;
+    scorerName: string;
+    score: number;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+};

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

@@ -0,0 +1,4 @@
+export const SCORER_LANE_QUEUES = {
+    fast: 'agent-score-fast',
+    slow: 'agent-score-slow',
+};

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

@@ -0,0 +1,6 @@
+export { pikkuAgentScorer, pikkuAgentJudge } from './agent-scorer.js';
+export { addAgentScorer, getAgentScorers, getAgentScorersMeta, } from './agent-scorer-registry.js';
+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';

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

@@ -0,0 +1,5 @@
+export { pikkuAgentScorer, pikkuAgentJudge } from './agent-scorer.js';
+export { addAgentScorer, getAgentScorers, getAgentScorersMeta, } from './agent-scorer-registry.js';
+export { gradeRun } from './agent-scorer-grade.js';
+export { enableScoreSnapshots, getScoreSnapshot, } from './agent-scorer-snapshots.js';
+export { wireAgentScorerQueueWorkers } from './agent-scorer-worker.js';

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

@@ -357,6 +357,8 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     secretOverrides: capturedAddonConfig?.secretOverrides,
                                     variableOverrides: capturedAddonConfig?.variableOverrides,
                                     credentialOverrides: capturedAddonConfig?.credentialOverrides,
+                                    secretGrants: capturedAddonConfig?.secretGrants,
+                                    credentialGrants: capturedAddonConfig?.credentialGrants,
                                     globalSecrets: capturedAddonConfig?.globalSecrets,
                                     globalCredentials: capturedAddonConfig?.globalCredentials,
                                 }

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

@@ -1,4 +1,4 @@
-type VoiceOutputState = {
+export type VoiceOutputState = {
     textBuffer?: string;
     /**
      * The audio emitted so far, as a chain.
@@ -83,4 +83,3 @@ export declare const voiceOutput: (config?: {
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;
-export {};

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

@@ -51,7 +51,7 @@ export declare class ChannelRPCError extends Error {
  * Whether a callable exposed to a remote decider needs a human to agree before
  * it runs, and how to describe the invocation while asking.
  *
- * Shared with `AIAgentToolDef`: both are an allowlist of named callables
+ * Shared with `AgentToolDef`: both are an allowlist of named callables
  * invoked by something other than the code that wrote them. The runtime around
  * them is not shared — an agent suspends and resumes, a reverse call is a live
  * await.
@@ -62,7 +62,7 @@ export interface ApprovalPolicy {
 }
 export type CapabilityHandler = (data: any) => Promise<unknown> | unknown;
 /**
- * `needsApproval` is required here on purpose. On `AIAgentToolDef` the same
+ * `needsApproval` is required here on purpose. On `AgentToolDef` the same
  * field is optional and absence means "do not ask"; here absence means the
  * opposite, so it must not be expressible — a bare function is the
  * unclassified form.

package/dist/wirings/rpc/addon-runner.d.ts

@@ -4,6 +4,10 @@ export type AddonInstance = {
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;
     credentialOverrides?: Record<string, string>;
+    /** Set by the consuming app: secrets it lends this instance, as the addon names them. */
+    secretGrants?: string[];
+    /** Set by the consuming app: credentials it lends this instance, as the addon names them. */
+    credentialGrants?: string[];
     /** Set by the consuming app to opt this instance out of secret scoping. */
     globalSecrets?: string;
     /** Set by the consuming app to opt this instance out of credential scoping. */

package/dist/wirings/rpc/addon-runner.js

@@ -1,6 +1,16 @@
 import { pikkuState } from '../../pikku-state.js';
 import { ScopedSecretService } from '../../services/scoped-secret-service.js';
 import { ScopedCredentialService } from '../../services/scoped-credential-service.js';
+/**
+ * What the addon declared, plus what the host lent it. Scoping runs outside the
+ * aliaser, so every name here is the one the addon reads — which is why an
+ * override's *key* grants, and its value does not.
+ */
+const allowedNames = (declared, grants, overrides) => new Set([
+    ...(declared ?? []),
+    ...(grants ?? []),
+    ...Object.keys(overrides ?? {}),
+]);
 const aliasSecretService = (secrets, overrides) => {
     const map = (key) => overrides[key] ?? key;
     return {
@@ -97,13 +107,13 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
     if (!addonInstance?.globalSecrets && existingServices.secrets) {
         existingServices = {
             ...existingServices,
-            secrets: new ScopedSecretService(existingServices.secrets, new Set(pikkuState(packageName, 'package', 'declaredSecrets') ?? [])),
+            secrets: new ScopedSecretService(existingServices.secrets, allowedNames(pikkuState(packageName, 'package', 'declaredSecrets'), addonInstance?.secretGrants, addonInstance?.secretOverrides)),
         };
     }
     if (!addonInstance?.globalCredentials && existingServices.credentialService) {
         existingServices = {
             ...existingServices,
-            credentialService: new ScopedCredentialService(existingServices.credentialService, new Set(Object.keys(pikkuState(packageName, 'package', 'credentialsMeta') ?? {}))),
+            credentialService: new ScopedCredentialService(existingServices.credentialService, allowedNames(Object.keys(pikkuState(packageName, 'package', 'credentialsMeta') ?? {}), addonInstance?.credentialGrants, addonInstance?.credentialOverrides)),
         };
     }
     if (!factories || !factories.createSingletonServices) {
@@ -132,6 +142,8 @@ export const addonInstanceForNamespace = (namespace, expectedPackage) => {
         secretOverrides: cfg.secretOverrides,
         variableOverrides: cfg.variableOverrides,
         credentialOverrides: cfg.credentialOverrides,
+        secretGrants: cfg.secretGrants,
+        credentialGrants: cfg.credentialGrants,
         globalSecrets: cfg.globalSecrets,
         globalCredentials: cfg.globalCredentials,
     };

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

@@ -52,7 +52,7 @@ export declare class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `ai-agent/agent-rpc.ts` so the agent surface is
+     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
      * one file rather than a wing of this one; a getter rather than a field so a
      * request that never touches an agent never builds it.
      */

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

@@ -4,7 +4,7 @@ import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 import { resolveRemoteAddonToken } from './remote-addon-auth.js';
-import { createAgentRPC } from '../ai-agent/agent-rpc.js';
+import { createAgentRPC } from '../agent/agent-rpc.js';
 /**
  * The session for a wire: read through `getSession` when a runner attached one,
  * otherwise whatever was placed on the wire directly.
@@ -203,6 +203,8 @@ export class ContextAwareRPCService {
                 secretOverrides: resolved.addonConfig?.secretOverrides,
                 variableOverrides: resolved.addonConfig?.variableOverrides,
                 credentialOverrides: resolved.addonConfig?.credentialOverrides,
+                secretGrants: resolved.addonConfig?.secretGrants,
+                credentialGrants: resolved.addonConfig?.credentialGrants,
                 globalSecrets: resolved.addonConfig?.globalSecrets,
                 globalCredentials: resolved.addonConfig?.globalCredentials,
             },
@@ -312,7 +314,7 @@ export class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `ai-agent/agent-rpc.ts` so the agent surface is
+     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
      * one file rather than a wing of this one; a getter rather than a field so a
      * request that never touches an agent never builds it.
      */

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,5 +1,5 @@
 import type { PikkuRawWire } from '../../types/core.types.js';
-import type { AgentInterruptResult } from '../ai-agent/ai-agent-interrupt.js';
+import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
     depth: number;
     global: boolean;
@@ -48,6 +48,10 @@ export interface ResolvedFunction {
         secretOverrides?: Record<string, string>;
         variableOverrides?: Record<string, string>;
         credentialOverrides?: Record<string, string>;
+        /** Set by the consuming app: secrets it lends this instance, as the addon names them */
+        secretGrants?: string[];
+        /** Set by the consuming app: credentials it lends this instance, as the addon names them */
+        credentialGrants?: string[];
         /** Set by the consuming app: hand this instance the unscoped `SecretService` */
         globalSecrets?: string;
         /** Set by the consuming app: hand this instance the unscoped `CredentialService` */