@pikku/core 0.12.82 → 0.12.84

package/src/wirings/{ai-scorer/ai-scorer-live.test.ts → agent-scorer/agent-scorer-live.test.ts}

@@ -1,11 +1,11 @@
 import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-import { scoreFinishedRun } from './ai-scorer-live.js'
-import { pikkuAIJudge, pikkuAIScorer } from './ai-scorer.js'
-import type { PikkuAIScorer, ScorerInput } from './ai-scorer.types.js'
+import { scoreFinishedRun } from './agent-scorer-live.js'
+import { pikkuAgentJudge, pikkuAgentScorer } from './agent-scorer.js'
+import type { PikkuAgentScorer, ScorerInput } from './agent-scorer.types.js'
 
-const register = (agentName: string, scorers: PikkuAIScorer[]) => {
+const register = (agentName: string, scorers: PikkuAgentScorer[]) => {
   pikkuState(null, 'agent', 'agents').set(agentName, {
     name: agentName,
     scorers: scorers.map((scorer) => scorer.name),
@@ -49,7 +49,7 @@ const collectingServices = () => {
   }
 }
 
-const alwaysOne = pikkuAIScorer({
+const alwaysOne = pikkuAgentScorer({
   name: 'brevity',
   description: 'Shorter is better',
   score: () => ({ score: 1 }),
@@ -61,7 +61,7 @@ describe('scoreFinishedRun', () => {
   })
 
   test('sends one message per scorer, each to its own lane', async () => {
-    const judge = pikkuAIJudge({
+    const judge = pikkuAgentJudge({
       name: 'helpfulness',
       description: 'Is the answer useful',
       model: 'claude-opus-5',
@@ -75,14 +75,14 @@ describe('scoreFinishedRun', () => {
     assert.deepEqual(
       added.map((entry) => [entry.queueName, entry.data.scorerName]),
       [
-        ['ai-score-fast', 'brevity'],
-        ['ai-score-slow', 'helpfulness'],
+        ['agent-score-fast', 'brevity'],
+        ['agent-score-slow', 'helpfulness'],
       ]
     )
   })
 
   test('never grades a reference-based judge, because live traffic has no answer key', async () => {
-    const correctness = pikkuAIJudge({
+    const correctness = pikkuAgentJudge({
       name: 'correctness',
       description: 'Is the answer right',
       model: 'claude-opus-5',
@@ -98,7 +98,7 @@ describe('scoreFinishedRun', () => {
   })
 
   test('honours the sample rate rather than grading every run', async () => {
-    const sampled = pikkuAIScorer({
+    const sampled = pikkuAgentScorer({
       name: 'brevity',
       description: 'Shorter is better',
       sampleRate: 0,
@@ -138,7 +138,7 @@ describe('scoreFinishedRun', () => {
   })
 
   test('one scorer that cannot be enqueued does not stop the others', async () => {
-    const judge = pikkuAIJudge({
+    const judge = pikkuAgentJudge({
       name: 'helpfulness',
       description: 'Is the answer useful',
       model: 'claude-opus-5',

package/src/wirings/{ai-scorer/ai-scorer-live.ts → agent-scorer/agent-scorer-live.ts}

@@ -1,7 +1,7 @@
 import type { CoreSingletonServices } from '../../types/core.types.js'
-import { scorersForAgent } from './ai-scorer-registry.js'
-import { isSampled } from './ai-scorer-sampling.js'
-import { SCORER_LANE_QUEUES, type ScorerInput } from './ai-scorer.types.js'
+import { scorersForAgent } from './agent-scorer-registry.js'
+import { isSampled } from './agent-scorer-sampling.js'
+import { SCORER_LANE_QUEUES, type ScorerInput } from './agent-scorer.types.js'
 
 /**
  * Grade one finished run on live traffic.

package/src/wirings/{ai-scorer/ai-scorer-registry.ts → agent-scorer/agent-scorer-registry.ts}

@@ -1,9 +1,9 @@
 import { pikkuState } from '../../pikku-state.js'
-import type { PikkuAIScorer } from './ai-scorer.types.js'
+import type { PikkuAgentScorer } from './agent-scorer.types.js'
 
-export const addAIScorer = (
+export const addAgentScorer = (
   scorerName: string,
-  scorer: PikkuAIScorer<any>,
+  scorer: PikkuAgentScorer<any>,
   packageName: string | null = null
 ) => {
   const scorersMeta = pikkuState(packageName, 'agent', 'scorersMeta')
@@ -20,15 +20,18 @@ export const addAIScorer = (
   scorers.set(scorerName, scorer)
 }
 
-export const getAIScorers = () => pikkuState(null, 'agent', 'scorers')
+export const getAgentScorers = () => pikkuState(null, 'agent', 'scorers')
 
-export const getAIScorersMeta = () => pikkuState(null, 'agent', 'scorersMeta')
+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 resolveAIScorer = (scorerName: string): PikkuAIScorer<any> => {
+export const resolveAgentScorer = (
+  scorerName: string
+): PikkuAgentScorer<any> => {
   const scorer = pikkuState(null, 'agent', 'scorers').get(scorerName)
   if (!scorer) {
     throw new Error(`AI scorer not found: ${scorerName}`)
@@ -45,10 +48,10 @@ export const resolveAIScorer = (scorerName: string): PikkuAIScorer<any> => {
 export const scorersForAgent = (
   agentName: string,
   logger?: { warn: (message: string) => void }
-): PikkuAIScorer<any>[] => {
+): PikkuAgentScorer<any>[] => {
   const agent = pikkuState(null, 'agent', 'agents').get(agentName)
   const names = agent?.scorers ?? []
-  const scorers: PikkuAIScorer<any>[] = []
+  const scorers: PikkuAgentScorer<any>[] = []
   for (const name of names) {
     const scorer = pikkuState(null, 'agent', 'scorers').get(name)
     if (!scorer) {

package/src/wirings/{ai-scorer/ai-scorer-sampling.test.ts → agent-scorer/agent-scorer-sampling.test.ts}

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
-import { isSampled } from './ai-scorer-sampling.js'
+import { isSampled } from './agent-scorer-sampling.js'
 
 describe('isSampled', () => {
   test('grades every run at a rate of 1 and none at 0', () => {

package/src/wirings/{ai-scorer/ai-scorer-snapshots.test.ts → agent-scorer/agent-scorer-snapshots.test.ts}

@@ -6,8 +6,8 @@ import {
   getScoreSnapshot,
   recordScoreSnapshot,
   resetScoreSnapshots,
-} from './ai-scorer-snapshots.js'
-import type { ScorerInput } from './ai-scorer.types.js'
+} from './agent-scorer-snapshots.js'
+import type { ScorerInput } from './agent-scorer.types.js'
 
 const run = (runId: string): ScorerInput => ({
   runId,

package/src/wirings/{ai-scorer/ai-scorer-snapshots.ts → agent-scorer/agent-scorer-snapshots.ts}

@@ -1,4 +1,4 @@
-import type { ScorerInput } from './ai-scorer.types.js'
+import type { ScorerInput } from './agent-scorer.types.js'
 
 /**
  * The last few finished runs, held so a scenario can grade one.

package/src/wirings/{ai-scorer/ai-scorer-worker.test.ts → agent-scorer/agent-scorer-worker.test.ts}

@@ -1,9 +1,9 @@
 import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-import { pikkuAIScoreWorkerFunc } from './ai-scorer-worker.js'
-import { pikkuAIJudge, pikkuAIScorer } from './ai-scorer.js'
-import type { PikkuAIScorer, ScoreJob } from './ai-scorer.types.js'
+import { pikkuAgentScoreWorkerFunc } from './agent-scorer-worker.js'
+import { pikkuAgentJudge, pikkuAgentScorer } from './agent-scorer.js'
+import type { PikkuAgentScorer, ScoreJob } from './agent-scorer.types.js'
 
 const job = (overrides: Partial<ScoreJob> = {}): ScoreJob => ({
   scorerName: 'brevity',
@@ -16,28 +16,28 @@ const job = (overrides: Partial<ScoreJob> = {}): ScoreJob => ({
   ...overrides,
 })
 
-const install = (scorer: PikkuAIScorer, aiAgentRunner?: unknown) => {
+const install = (scorer: PikkuAgentScorer, agentRunner?: unknown) => {
   pikkuState(null, 'agent', 'scorers').set(scorer.name, scorer)
   const saved: unknown[] = []
   pikkuState(null, 'package', 'singletonServices', {
-    aiRunState: {
+    agentRunState: {
       saveScore: async (score: unknown) => {
         saved.push(score)
       },
     },
-    aiAgentRunner,
+    agentRunner,
   } as never)
   return saved
 }
 
-describe('pikkuAIScoreWorkerFunc', () => {
+describe('pikkuAgentScoreWorkerFunc', () => {
   beforeEach(() => {
     resetPikkuState()
   })
 
   test('records what a heuristic scorer graded, against the run it graded', async () => {
     const saved = install(
-      pikkuAIScorer({
+      pikkuAgentScorer({
         name: 'brevity',
         description: 'Shorter is better',
         score: (input) => ({
@@ -47,7 +47,7 @@ describe('pikkuAIScoreWorkerFunc', () => {
       })
     )
 
-    await pikkuAIScoreWorkerFunc({}, job())
+    await pikkuAgentScoreWorkerFunc({}, job())
 
     assert.deepEqual(saved, [
       {
@@ -61,7 +61,7 @@ describe('pikkuAIScoreWorkerFunc', () => {
 
   test('hands a judge to the model rather than calling a score function it has not got', async () => {
     const saved = install(
-      pikkuAIJudge({
+      pikkuAgentJudge({
         name: 'helpfulness',
         description: 'Is the answer useful',
         model: 'claude-opus-5',
@@ -75,7 +75,7 @@ describe('pikkuAIScoreWorkerFunc', () => {
       }
     )
 
-    await pikkuAIScoreWorkerFunc({}, job({ scorerName: 'helpfulness' }))
+    await pikkuAgentScoreWorkerFunc({}, job({ scorerName: 'helpfulness' }))
 
     assert.deepEqual(saved, [
       {
@@ -91,7 +91,7 @@ describe('pikkuAIScoreWorkerFunc', () => {
   test('fails the job when there is nowhere to record the grade, so it is retried rather than lost', async () => {
     pikkuState(null, 'agent', 'scorers').set(
       'brevity',
-      pikkuAIScorer({
+      pikkuAgentScorer({
         name: 'brevity',
         description: 'Shorter is better',
         score: () => ({ score: 1 }),
@@ -100,14 +100,14 @@ describe('pikkuAIScoreWorkerFunc', () => {
     pikkuState(null, 'package', 'singletonServices', {} as never)
 
     await assert.rejects(
-      () => pikkuAIScoreWorkerFunc({}, job()),
+      () => pikkuAgentScoreWorkerFunc({}, job()),
       /AI run state service not initialized/
     )
   })
 
   test('fails on a scorer name that resolves to nothing', async () => {
     install(
-      pikkuAIScorer({
+      pikkuAgentScorer({
         name: 'brevity',
         description: 'Shorter is better',
         score: () => ({ score: 1 }),
@@ -115,7 +115,7 @@ describe('pikkuAIScoreWorkerFunc', () => {
     )
 
     await assert.rejects(
-      () => pikkuAIScoreWorkerFunc({}, job({ scorerName: 'gone' })),
+      () => pikkuAgentScoreWorkerFunc({}, job({ scorerName: 'gone' })),
       /AI scorer not found: gone/
     )
   })

package/src/wirings/{ai-scorer/ai-scorer-worker.ts → agent-scorer/agent-scorer-worker.ts}

@@ -1,14 +1,14 @@
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction } from '../../function/function-runner.js'
 import { wireQueueWorker } from '../queue/queue-runner.js'
-import { gradeRun } from './ai-scorer-grade.js'
-import { SCORER_LANE_QUEUES, type ScoreJob } from './ai-scorer.types.js'
+import { gradeRun } from './agent-scorer-grade.js'
+import { SCORER_LANE_QUEUES, 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 async function pikkuAIScoreWorkerFunc(
+export async function pikkuAgentScoreWorkerFunc(
   _services: Record<string, unknown>,
   job: ScoreJob
 ): Promise<void> {
@@ -22,7 +22,7 @@ export async function pikkuAIScoreWorkerFunc(
   await gradeRun(job, services, { persist: true })
 }
 
-const SCORE_WORKER_FUNC_ID = 'pikkuAIScoreWorker'
+const SCORE_WORKER_FUNC_ID = 'pikkuAgentScoreWorker'
 
 /**
  * Bind the two lane queues to the shared worker.
@@ -32,7 +32,7 @@ const SCORE_WORKER_FUNC_ID = 'pikkuAIScoreWorker'
  * for, so the metadata is synthesised here alongside the registration. This
  * mirrors how workflows wire their own queues.
  */
-export const wireAIScorerQueueWorkers = (): void => {
+export const wireAgentScorerQueueWorkers = (): void => {
   // 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
@@ -42,7 +42,9 @@ export const wireAIScorerQueueWorkers = (): void => {
   const queueMeta = pikkuState(null, 'queue', 'meta')
 
   if (!functions.has(SCORE_WORKER_FUNC_ID)) {
-    addFunction(SCORE_WORKER_FUNC_ID, { func: pikkuAIScoreWorkerFunc } as never)
+    addFunction(SCORE_WORKER_FUNC_ID, {
+      func: pikkuAgentScoreWorkerFunc,
+    } as never)
   }
   if (!functionsMeta[SCORE_WORKER_FUNC_ID]) {
     functionsMeta[SCORE_WORKER_FUNC_ID] = {
@@ -63,7 +65,7 @@ export const wireAIScorerQueueWorkers = (): void => {
     }
     wireQueueWorker({
       name: queueName,
-      func: { func: pikkuAIScoreWorkerFunc },
+      func: { func: pikkuAgentScoreWorkerFunc },
     } as never)
   }
 }

package/src/wirings/{ai-scorer/ai-scorer.ts → agent-scorer/agent-scorer.ts}

@@ -1,8 +1,8 @@
 import type {
-  PikkuAIScorer,
+  PikkuAgentScorer,
   ScorerInput,
   ScorerOutput,
-} from './ai-scorer.types.js'
+} from './agent-scorer.types.js'
 
 const assertSampleRate = (name: string, sampleRate: number | undefined) => {
   if (sampleRate === undefined) return 1
@@ -18,7 +18,7 @@ const assertSampleRate = (name: string, sampleRate: number | undefined) => {
  * A heuristic scorer: pure code over the finished run, no model call, so it
  * grades on the fast lane.
  */
-export const pikkuAIScorer = <Services = any>(config: {
+export const pikkuAgentScorer = <Services = any>(config: {
   name: string
   description: string
   /** 0..1 fraction of live runs to grade. Defaults to all of them. */
@@ -32,7 +32,7 @@ export const pikkuAIScorer = <Services = any>(config: {
     input: ScorerInput,
     services: Services
   ) => ScorerOutput | Promise<ScorerOutput>
-}): PikkuAIScorer<Services> => ({
+}): PikkuAgentScorer<Services> => ({
   name: config.name,
   description: config.description,
   lane: 'fast',
@@ -45,11 +45,11 @@ export const pikkuAIScorer = <Services = any>(config: {
  * 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 `pikkuAIAgent`'s prompt vocabulary — a
+ * 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 pikkuAIJudge = <Services = any>(config: {
+export const pikkuAgentJudge = <Services = any>(config: {
   name: string
   description: string
   /** 0..1 fraction of live runs to grade. Defaults to all of them. */
@@ -62,7 +62,7 @@ export const pikkuAIJudge = <Services = any>(config: {
   model: string
   goal: string
   prompt?: (input: ScorerInput) => string
-}): PikkuAIScorer<Services> => ({
+}): PikkuAgentScorer<Services> => ({
   name: config.name,
   description: config.description,
   lane: 'slow',

package/src/wirings/{ai-scorer/ai-scorer.types.ts → agent-scorer/agent-scorer.types.ts}

@@ -46,13 +46,13 @@ export interface ScorerOutput {
 export type ScorerLane = 'fast' | 'slow'
 
 export const SCORER_LANE_QUEUES: Record<ScorerLane, string> = {
-  fast: 'ai-score-fast',
-  slow: 'ai-score-slow',
+  fast: 'agent-score-fast',
+  slow: 'agent-score-slow',
 }
 
 /**
- * A judge's model call. Present only on a scorer built with `pikkuAIJudge`;
- * `score` is present only on one built with `pikkuAIScorer`. Exactly one of the
+ * 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 = {
@@ -61,7 +61,7 @@ export type ScorerJudgeConfig = {
   prompt?: (input: ScorerInput) => string
 }
 
-export type PikkuAIScorer<Services = any> = {
+export type PikkuAgentScorer<Services = any> = {
   name: string
   description: string
   lane: ScorerLane
@@ -97,7 +97,7 @@ export type ScoreJob = ScorerInput & {
   scorerName: string
 }
 
-export type AIRunScore = {
+export type AgentRunScore = {
   runId: string
   scorerName: string
   score: number

package/src/wirings/agent-scorer/index.ts

@@ -0,0 +1,22 @@
+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/src/wirings/channel/channel-rpc.types.ts

@@ -92,7 +92,7 @@ export 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.
@@ -105,7 +105,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/src/wirings/rpc/addon-runner.ts

@@ -13,12 +13,32 @@ 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. */
   globalCredentials?: string
 }
 
+/**
+ * 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: string[] | null | undefined,
+  grants: string[] | undefined,
+  overrides: Record<string, string> | undefined
+): Set<string> =>
+  new Set([
+    ...(declared ?? []),
+    ...(grants ?? []),
+    ...Object.keys(overrides ?? {}),
+  ])
+
 const aliasSecretService = (
   secrets: SecretService,
   overrides: Record<string, string>
@@ -142,7 +162,11 @@ export const getOrCreatePackageSingletonServices = async (
       ...existingServices,
       secrets: new ScopedSecretService(
         existingServices.secrets,
-        new Set(pikkuState(packageName, 'package', 'declaredSecrets') ?? [])
+        allowedNames(
+          pikkuState(packageName, 'package', 'declaredSecrets'),
+          addonInstance?.secretGrants,
+          addonInstance?.secretOverrides
+        )
       ),
     }
   }
@@ -151,10 +175,12 @@ export const getOrCreatePackageSingletonServices = async (
       ...existingServices,
       credentialService: new ScopedCredentialService(
         existingServices.credentialService,
-        new Set(
+        allowedNames(
           Object.keys(
             pikkuState(packageName, 'package', 'credentialsMeta') ?? {}
-          )
+          ),
+          addonInstance?.credentialGrants,
+          addonInstance?.credentialOverrides
         )
       ),
     }
@@ -202,6 +228,8 @@ export const addonInstanceForNamespace = (
     secretOverrides: cfg.secretOverrides,
     variableOverrides: cfg.variableOverrides,
     credentialOverrides: cfg.credentialOverrides,
+    secretGrants: cfg.secretGrants,
+    credentialGrants: cfg.credentialGrants,
     globalSecrets: cfg.globalSecrets,
     globalCredentials: cfg.globalCredentials,
   }

package/src/wirings/rpc/addon-secrets.test.ts

@@ -259,3 +259,133 @@ describe('addon credentials are scoped to what the addon declared', () => {
     assert.deepEqual(await credentials.getAllUsers(), ['user-1'])
   })
 })
+
+/**
+ * An addon whose secret names come off its input rather than its own source
+ * declares nothing, so the host lends it names it could not have derived.
+ *
+ * knowledge: decisions/security/decision-secretless-functions.md
+ */
+describe('the host grants an addon secrets it could not declare', () => {
+  beforeEach(() => {
+    resetPikkuState()
+  })
+
+  test('a granted secret is readable', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(await secrets.getSecret('STRIPE_KEY'), 'value-of-STRIPE_KEY')
+  })
+
+  test('a secret the host did not grant is still denied', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    await assert.rejects(() => secrets.getSecret('DATABASE_URL'), /denied/i)
+  })
+
+  test('a grant adds to what the addon declared rather than replacing it', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(await secrets.getSecret('ADDON_KEY'), 'value-of-ADDON_KEY')
+    assert.equal(await secrets.getSecret('STRIPE_KEY'), 'value-of-STRIPE_KEY')
+  })
+
+  test('an overridden secret is granted by the override itself', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretOverrides: { MAILGUN_KEY: 'PROD_EMAIL_KEY' },
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(
+      await secrets.getSecret('MAILGUN_KEY'),
+      'value-of-PROD_EMAIL_KEY'
+    )
+  })
+
+  test('a grant is checked before the override renames it', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['MAILGUN_KEY'],
+      secretOverrides: { MAILGUN_KEY: 'PROD_EMAIL_KEY' },
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(
+      await secrets.getSecret('MAILGUN_KEY'),
+      'value-of-PROD_EMAIL_KEY'
+    )
+    await assert.rejects(() => secrets.getSecret('PROD_EMAIL_KEY'), /denied/i)
+  })
+
+  test('a granted credential is readable', async () => {
+    registerAddon([], [])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      credentialGrants: ['stripe'],
+    })
+
+    const credentials = await credentialsHandedToAddon('example')
+    assert.equal(await credentials.get('stripe'), 'credential-of-stripe')
+    await assert.rejects(() => credentials.get('slack'), /denied/i)
+  })
+
+  test('a granted credential does not widen the rest of the service', async () => {
+    registerAddon([], [])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      credentialGrants: ['stripe'],
+    })
+
+    const credentials = await credentialsHandedToAddon('example')
+    await assert.rejects(() => credentials.getAllUsers(), /denied/i)
+  })
+
+  test('an addon without a singleton factory is granted too', async () => {
+    pikkuState(ADDON_PACKAGE, 'package', 'declaredSecrets', [])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const services = await getOrCreatePackageSingletonServices(
+      ADDON_PACKAGE,
+      createParentServices(),
+      pikkuState(null, 'addons', 'packages').get('example') as never
+    )
+
+    assert.equal(
+      await services.secrets.getSecret('STRIPE_KEY'),
+      'value-of-STRIPE_KEY'
+    )
+    await assert.rejects(
+      () => services.secrets.getSecret('DATABASE_URL'),
+      /denied/i
+    )
+  })
+})