@pikku/core 0.12.98 → 0.12.100

package/src/services/typed-secret-service.test.ts

@@ -137,7 +137,10 @@ describe('TypedSecretService', () => {
         optional: true,
       },
     })
-    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), undefined)
+    assert.strictEqual(
+      await service.getSecret('SCENARIO_ACTOR_SECRET'),
+      undefined
+    )
   })
 
   test('an optional secret that IS set resolves its value', async () => {
@@ -159,6 +162,28 @@ describe('TypedSecretService', () => {
     await assert.rejects(() => service.getSecret('STRIPE_KEY'))
   })
 
+  test('a resolved-absent optional secret still reports hasSecret false', async () => {
+    // The cache stores `undefined` to remember the absence, so a `has(key)`
+    // test on it answers "we have looked", not "there is a value". Reading an
+    // optional secret must not turn its own absence into a claim it is set.
+    const service = new TypedSecretService(createMockSecrets(), {
+      OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true },
+    })
+    assert.strictEqual(await service.getSecret('OPTIONAL'), undefined)
+    assert.strictEqual(await service.hasSecret('OPTIONAL'), false)
+  })
+
+  test('an optional secret set after an absent read is picked up', async () => {
+    const store = new Map<string, string>()
+    const service = new TypedSecretService(createMockSecrets(store), {
+      OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true },
+    })
+    assert.strictEqual(await service.getSecret('OPTIONAL'), undefined)
+    await service.setSecret('OPTIONAL', 'later')
+    assert.strictEqual(await service.hasSecret('OPTIONAL'), true)
+    assert.strictEqual(await service.getSecret('OPTIONAL'), 'later')
+  })
+
   test('an optional secret does not re-hit the store once resolved', async () => {
     let reads = 0
     const base = createMockSecrets()

package/src/services/typed-secret-service.ts

@@ -64,8 +64,11 @@ export class TypedSecretService<
   }
 
   async hasSecret(key: string): Promise<boolean> {
+    // `undefined` is cached for an optional secret that resolved absent, so a
+    // cache hit means "already looked", not "there is a value". Reporting true
+    // for it would let a read of an optional secret assert its own presence.
     if (this.cache.has(key)) {
-      return true
+      return this.cache.get(key) !== undefined
     }
     return this.secrets.hasSecret(key)
   }

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

@@ -22,7 +22,9 @@ const assertSampleRate = (name: string, sampleRate: number | undefined) => {
  * @example snippet: agentScorer
  */
 export const pikkuAgentScorer = <Services = any>(config: {
+  /** Identifies the scorer in results and in the Console. Unique per project. */
   name: string
+  /** What this scorer grades, in one line, for whoever reads the score later. */
   description: string
   /** 0..1 fraction of live runs to grade. Defaults to all of them. */
   sampleRate?: number
@@ -31,6 +33,10 @@ export const pikkuAgentScorer = <Services = any>(config: {
    * traffic has no answer key, so the runtime never samples it.
    */
   requiresReference?: boolean
+  /**
+   * The grade itself: read the finished run and return `{ score, reason }`.
+   * Runs in-process, so it may use your own services.
+   */
   score: (
     input: ScorerInput,
     services: Services
@@ -55,7 +61,9 @@ export const pikkuAgentScorer = <Services = any>(config: {
  * @example snippet: agentJudge
  */
 export const pikkuAgentJudge = <Services = any>(config: {
+  /** Identifies the judge in results and in the Console. Unique per project. */
   name: string
+  /** What this judge grades, in one line, for whoever reads the score later. */
   description: string
   /** 0..1 fraction of live runs to grade. Defaults to all of them. */
   sampleRate?: number
@@ -64,7 +72,9 @@ export const pikkuAgentJudge = <Services = any>(config: {
    * traffic has no answer key, so the runtime never samples it.
    */
   requiresReference?: boolean
+  /** The model that grades, e.g. `'claude-sonnet-4-5'`. Not the model under test. */
   model: string
+  /** The rubric: what a good answer looks like, phrased as the goal it should meet. */
   goal: string
   /**
    * How much of the run's trajectory to disclose to the judge. Defaults to
@@ -72,6 +82,10 @@ export const pikkuAgentJudge = <Services = any>(config: {
    * sending a third-party model the rows the tools returned.
    */
   toolCalls?: JudgeToolCallDisclosure
+  /**
+   * Replaces the generated rubric prompt outright, for framing `goal` cannot
+   * express. The `{ score, reason }` response is still forced.
+   */
   prompt?: (input: ScorerInput) => string
 }): PikkuAgentScorer<Services> => ({
   name: config.name,

package/src/wirings/gateway/gateway.types.ts

@@ -24,9 +24,13 @@ export interface GatewayAttachment {
 export interface GatewayInboundMessage {
   /** Platform-specific: a phone number, a Slack user id, and so on. */
   senderId: string
+  /** What they said, as plain text, with the provider's markup stripped. */
   text: string
+  /** The provider's own event, untouched, for anything this shape drops. */
   raw: unknown
+  /** Files and media that came with the message. */
   attachments?: GatewayAttachment[]
+  /** Anything else the adapter wants to carry through to the wiring. */
   metadata?: Record<string, unknown>
 }
 
@@ -35,8 +39,11 @@ export interface GatewayInboundMessage {
  * own rich content.
  */
 export interface GatewayOutboundMessage {
+  /** The reply as plain text. Every provider can render this. */
   text?: string
+  /** The provider's own rich payload, e.g. Slack blocks. Passed through as-is. */
   richContent?: Record<string, unknown>
+  /** Files and media to send alongside. */
   attachments?: GatewayAttachment[]
 }
 
@@ -45,19 +52,31 @@ export interface GatewayOutboundMessage {
  * provider expects back, or not.
  */
 export type WebhookVerificationResult =
-  { verified: true; response: unknown } | { verified: false }
+  | {
+      /** True when the request really came from the provider. */
+      verified: true
+      /** What to echo back, e.g. Meta's hub.challenge. */
+      response: unknown
+    }
+  | {
+      /** False when the signature or challenge did not check out. */
+      verified: false
+    }
 
 /**
  * What a gateway integration implements: parse an incoming event into a
  * message, send one back, and open and close the connection.
  */
 export interface GatewayAdapter {
+  /** Identifies the gateway in wirings and logs, e.g. `'slack'`. */
   name: string
   /** Return null to ignore the event, e.g. a delivery receipt. */
   parse(data: unknown): GatewayInboundMessage | null
+  /** Deliver a reply back to the sender the message came from. */
   send(senderId: string, message: GatewayOutboundMessage): Promise<void>
   /** Called by GatewayService.start(); must call onMessage per incoming event. */
   init(onMessage: (data: unknown) => Promise<void>): Promise<void>
+  /** Called by GatewayService.stop(); release the connection init() opened. */
   close(): Promise<void>
   /** Receives the GET query params, or the POST body when called from the POST handler. */
   verifyWebhook?(

package/src/wirings/persona/index.ts

@@ -55,10 +55,20 @@ export {
   OperatorSignIn,
   establishOperatorSession,
   IMPERSONATE_USER_ID_HEADER,
+  type ActorSecretResolver,
   type PersonaSignIn,
   type OperatorSignInOptions,
   type OperatorSessionResult,
+  authMount,
 } from '../../services/persona-sign-in.js'
+export {
+  ACTOR_ROOT_SECRET_MIN_LENGTH,
+  ACTOR_SECRET_INFO,
+  ACTOR_SECRET_NAME,
+  actorSecretSubject,
+  deriveActorSecret,
+  verifyActorSecret,
+} from '../../services/persona-actor-secret.js'
 export {
   postScenarioJson,
   readScenarioHttpResponse,

package/src/wirings/secret/secret.types.ts

@@ -1,8 +1,16 @@
 export type CoreSecret<T = unknown> = {
+  /** The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE. */
   name: string
+  /** How the secret is labelled wherever a person is asked to supply it. */
   displayName: string
+  /** What this secret is for, shown beside the field someone has to fill in. */
   description?: string
+  /** The id under the backing store, which is where the value actually lives. */
   secretId: string
+  /**
+   * The shape of the value, as a schema. This is what types `getSecret`'s
+   * result — pass the schema itself, not an instance of it.
+   */
   schema: T
   /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
   optional?: boolean