@pikku/core 0.12.106 → 0.12.111

package/src/wirings/virtual-user/virtual-user-agents.test.ts

@@ -1,72 +0,0 @@
-import assert from 'node:assert/strict'
-import { describe, test } from 'node:test'
-import { reachableAgents } from './virtual-user-agents.js'
-
-const AGENTS = {
-  'router-agent': {
-    description: 'Routes requests to the right domain agent',
-  },
-  'social-poster': {
-    description: 'Drafts and schedules posts',
-    scopes: ['content:write'],
-  },
-  'refund-agent': {
-    scopes: ['billing:write'],
-  },
-}
-
-describe('reachableAgents', () => {
-  test('offers every agent when the persona holds no scopes to filter by', () => {
-    assert.deepEqual(
-      reachableAgents(AGENTS).map((a) => a.name),
-      ['router-agent', 'social-poster', 'refund-agent']
-    )
-  })
-
-  test('an agent gating itself with scopes is offered only to a persona holding them', () => {
-    assert.deepEqual(
-      reachableAgents(AGENTS, ['content:write']).map((a) => a.name),
-      ['router-agent', 'social-poster']
-    )
-  })
-
-  // Undeclared is not denied. A function gating itself with no scopes is open
-  // to everybody, and an agent has to read the same way — inventing a denial
-  // here would hide precisely the surfaces that really are open.
-  test('an agent declaring no scopes stays open to everybody', () => {
-    assert.deepEqual(
-      reachableAgents(AGENTS, []).map((a) => a.name),
-      ['router-agent']
-    )
-  })
-
-  test('carries the description through, which is what the model chooses on', () => {
-    const [router] = reachableAgents(AGENTS, ['content:write'])
-    assert.equal(
-      router!.description,
-      'Routes requests to the right domain agent'
-    )
-  })
-
-  test('omits description rather than passing undefined', () => {
-    const refund = reachableAgents(AGENTS, ['billing:write']).find(
-      (a) => a.name === 'refund-agent'
-    )
-    assert.deepEqual(refund, { name: 'refund-agent' })
-  })
-
-  test('offers the registration key, not the display name the agent declares', () => {
-    assert.deepEqual(
-      reachableAgents({ adminAgent: { description: 'Runs the place' } }),
-      [{ name: 'adminAgent', description: 'Runs the place' }]
-    )
-  })
-
-  test('an agent carrying nothing but a key is still offered under it', () => {
-    assert.deepEqual(reachableAgents({ orphan: {} }), [{ name: 'orphan' }])
-  })
-
-  test('a project with no agents offers none', () => {
-    assert.deepEqual(reachableAgents({}, ['admin']), [])
-  })
-})

package/src/wirings/virtual-user/virtual-user-agents.ts

@@ -1,62 +0,0 @@
-import { hasScopes } from '../../scopes.js'
-
-/**
- * Which of the product's agents a persona can actually talk to.
- *
- * An agent is not something a persona declares. It is something a persona
- * *reaches*, under exactly the rule an RPC is reached by: `CoreAgent.scopes`
- * is checked against the session, so a persona holding the scopes an agent
- * requires finds it in front of them, and one that does not, does not.
- *
- * That is the whole reason a persona has no `agent:` field. Naming one would
- * add no capability the roles do not already confer, and would narrow the
- * persona to a single brain when the interesting behaviour is the choice
- * between calling the API directly and handing the work to a specialist.
- */
-
-/** The part of an agent's meta this needs. */
-export interface AgentReachability {
-  description?: string
-  scopes?: readonly string[]
-  auth?: boolean
-}
-
-/** One agent, as it is offered to a virtual user. */
-export interface ReachableAgent {
-  name: string
-  description?: string
-}
-
-/**
- * The agents to offer, named by the key they are registered under.
- *
- * That key is the export's own name, which is what `addAgent` stores and what
- * `resolveAgent` looks up. The `name` an agent declares in its config is a
- * display label and is frequently something else entirely — offering that one
- * hands the persona a name the server cannot resolve, and the run dies on a
- * 500 the moment it takes the offer.
- *
- * Like {@link reachableCatalogue}, this narrows *what is offered* and never
- * what is enforced: the server decides who may talk to what, and an agent
- * answering a persona this filter would have withheld is a finding rather than
- * a bug here.
- *
- * An agent declaring no scopes is offered to everybody, on the same terms as a
- * function that gates itself with none — undeclared is not the same as denied,
- * and inventing a denial here would hide the endpoints that really are open.
- */
-export const reachableAgents = (
-  agents: Readonly<Record<string, AgentReachability>>,
-  scopes?: readonly string[]
-): ReachableAgent[] =>
-  Object.entries(agents)
-    .filter(([, agent]) => {
-      if (!scopes || !agent.scopes?.length) {
-        return true
-      }
-      return hasScopes(agent.scopes, scopes)
-    })
-    .map(([id, agent]) => ({
-      name: id,
-      ...(agent.description ? { description: agent.description } : {}),
-    }))

package/src/wirings/virtual-user/virtual-user-catalogue.test.ts

@@ -1,215 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import {
-  catalogueClassification,
-  catalogueIndex,
-  catalogueLookup,
-  describeEntry,
-  isReadOnly,
-  reachableCatalogue,
-  unreachableCatalogue,
-  renderCatalogue,
-} from './virtual-user-catalogue.js'
-import type { ApiCatalogueEntry } from './virtual-user.types.js'
-
-const entry = (
-  name: string,
-  extra: Partial<ApiCatalogueEntry> = {}
-): ApiCatalogueEntry => ({ name, ...extra })
-
-describe('read/write classification', () => {
-  test('an explicit annotation always wins over the name', () => {
-    assert.equal(isReadOnly(entry('getProject', { readonly: false })), false)
-    assert.equal(isReadOnly(entry('deleteProject', { readonly: true })), true)
-  })
-
-  test('without one, the name decides', () => {
-    for (const name of [
-      'getProject',
-      'listProjects',
-      'searchUsers',
-      'findOrg',
-      'countDeployments',
-      'isMember',
-      'hasAccess',
-    ]) {
-      assert.equal(isReadOnly(entry(name)), true, name)
-    }
-    for (const name of [
-      'createProject',
-      'deployStage',
-      'inviteMember',
-      'rollbackDeployment',
-      'updateOrg',
-    ]) {
-      assert.equal(isReadOnly(entry(name)), false, name)
-    }
-  })
-
-  test('a read prefix only counts on a word boundary', () => {
-    // 'checkoutCart' starts with 'check' but is emphatically not a read.
-    assert.equal(isReadOnly(entry('checkoutCart')), false)
-    assert.equal(isReadOnly(entry('issueRefund')), false)
-    assert.equal(isReadOnly(entry('countersignContract')), false)
-  })
-
-  test('how much of the split is guess is reported rather than hidden', () => {
-    const classification = catalogueClassification([
-      entry('getProject', { readonly: true }),
-      entry('createProject', { readonly: false }),
-      entry('deployStage'),
-      entry('listStages'),
-    ])
-    assert.deepEqual(classification, { total: 4, annotated: 2, inferred: 2 })
-  })
-})
-
-describe('catalogue rendering', () => {
-  test('an entry renders as name(inputs) -> outputs — description', () => {
-    const rendered = renderCatalogue([
-      entry('createProject', {
-        inputKeys: ['name', 'orgId'],
-        outputKeys: ['projectId'],
-        description: 'Create a project',
-      }),
-    ])
-    assert.equal(
-      rendered,
-      'createProject(name,orgId) -> projectId — Create a project'
-    )
-  })
-
-  test('missing meta degrades quietly instead of rendering undefined', () => {
-    assert.equal(renderCatalogue([entry('ping')]), 'ping()')
-  })
-
-  test('only the first line of a description is used', () => {
-    const rendered = renderCatalogue([
-      entry('getOrg', { description: 'Read an org.\nWith more detail below.' }),
-    ])
-    assert.equal(rendered, 'getOrg() — Read an org.')
-  })
-
-  test('every reachable endpoint is listed — nothing is ranked away', () => {
-    const entries = Array.from({ length: 50 }, (_, i) => entry(`getThing${i}`))
-    assert.equal(renderCatalogue(entries).split('\n').length, 50)
-  })
-})
-
-describe('what a given user is offered', () => {
-  const entries = [
-    entry('getProject'),
-    entry('createProject'),
-    entry('deployStage', { approvalRequired: true }),
-    entry('listOrgs', { scopes: ['platform:admin'] }),
-    entry('getOrgMembers', { scopes: ['org:read'] }),
-  ]
-
-  test('approval-gated calls are withheld by default', () => {
-    const names = reachableCatalogue(entries).map((e) => e.name)
-    assert.ok(!names.includes('deployStage'))
-  })
-
-  test('and offered when the run opts in', () => {
-    const names = reachableCatalogue(entries, {
-      allowApprovalRequired: true,
-    }).map((e) => e.name)
-    assert.ok(names.includes('deployStage'))
-  })
-
-  test('a read-only user is offered no mutations at all', () => {
-    const names = reachableCatalogue(entries, { readOnly: true }).map(
-      (e) => e.name
-    )
-    assert.deepEqual(names, ['getProject', 'listOrgs', 'getOrgMembers'])
-  })
-
-  test('a scope the persona does not hold is left out', () => {
-    const names = reachableCatalogue(entries, {
-      scopes: ['org:read'],
-    }).map((e) => e.name)
-    assert.deepEqual(names, ['getProject', 'createProject', 'getOrgMembers'])
-  })
-
-  // The adversarial oracle: what it is NOT entitled to reach, so a 2xx from one
-  // of these is the finding rather than a pass.
-  test('the same split, the other way round', () => {
-    const names = unreachableCatalogue(entries, ['org:read']).map((e) => e.name)
-    assert.deepEqual(names, ['listOrgs'])
-  })
-
-  // Every scope a persona holds means the whole surface is entitled, which is
-  // what an unscoped project looks like — and an empty oracle is the honest
-  // answer there, not a catalogue of everything.
-  test('an unscoped catalogue has nothing to withhold', () => {
-    assert.deepEqual(
-      unreachableCatalogue([entry('getProject')], ['anything']),
-      []
-    )
-  })
-
-  test('omitting scopes keeps everything — narrowing is opt-in', () => {
-    assert.equal(
-      reachableCatalogue(entries, { allowApprovalRequired: true }).length,
-      5
-    )
-  })
-})
-
-describe('describing an endpoint before calling it', () => {
-  test('hands back the full input schema, not just the key names', () => {
-    const described = describeEntry(
-      entry('createProject', {
-        description: 'Create a project',
-        inputSchema: {
-          type: 'object',
-          properties: { name: { type: 'string' } },
-          required: ['name'],
-        },
-        outputSchema: { type: 'object', properties: { projectId: {} } },
-      })
-    )
-    assert.equal(described.name, 'createProject')
-    assert.equal(described.readonly, false)
-    assert.equal(described.approvalRequired, false)
-    assert.deepEqual(described.input, {
-      type: 'object',
-      properties: { name: { type: 'string' } },
-      required: ['name'],
-    })
-    assert.ok(described.output)
-  })
-
-  test('an endpoint with no schema still describes as callable with nothing', () => {
-    const described = describeEntry(entry('ping'))
-    assert.deepEqual(described.input, { type: 'object', properties: {} })
-    assert.equal(described.output, null)
-  })
-})
-
-describe('catalogue index', () => {
-  test('looks endpoints up by name', () => {
-    const index = catalogueIndex([entry('getProject'), entry('createProject')])
-    assert.equal(index.get('getProject')?.name, 'getProject')
-    assert.equal(index.get('nonsense'), undefined)
-  })
-
-  // Found by running one: a model that has just read `whoAmI() -> userId,scopes`
-  // off the catalogue will sometimes hand the whole line back as the name.
-  test('an rpc name given with the signature the catalogue printed still resolves', () => {
-    const index = catalogueIndex([entry('getProject'), entry('createProject')])
-    assert.equal(catalogueLookup(index, 'getProject')?.name, 'getProject')
-    assert.equal(
-      catalogueLookup(index, 'getProject(id) -> project')?.name,
-      'getProject'
-    )
-    assert.equal(catalogueLookup(index, '  getProject()  ')?.name, 'getProject')
-  })
-
-  test('a name that is genuinely not there is still not there', () => {
-    const index = catalogueIndex([entry('getProject'), entry('createProject')])
-    assert.equal(catalogueLookup(index, 'nope'), undefined)
-    assert.equal(catalogueLookup(index, 'nope(x) -> y'), undefined)
-  })
-})

package/src/wirings/virtual-user/virtual-user-catalogue.ts

@@ -1,184 +0,0 @@
-import { hasScopes } from '../../scopes.js'
-import type { ApiCatalogueEntry } from './virtual-user.types.js'
-
-/**
- * Endpoint names that only read, by convention. Used when nobody annotated
- * `readonly` — which in a real project is most of them.
- */
-const READ_PREFIXES = [
-  'get',
-  'list',
-  'lookup',
-  'search',
-  'find',
-  'read',
-  'fetch',
-  'check',
-  'count',
-  'query',
-  'preview',
-  'describe',
-  'has',
-  'is',
-]
-
-/**
- * Whether a call only reads.
- *
- * An explicit annotation always wins. Without one, the name decides — because
- * an unannotated function means "nobody said", not "safe", and silently
- * treating 395 unannotated endpoints as read-only is how a virtual user
- * deploys something. {@link catalogueClassification} reports how much of the
- * catalogue rests on this guess so the gap is visible rather than assumed.
- */
-export const isReadOnly = (entry: ApiCatalogueEntry): boolean => {
-  if (typeof entry.readonly === 'boolean') return entry.readonly
-  const name = entry.name
-  return READ_PREFIXES.some(
-    (prefix) =>
-      name.startsWith(prefix) &&
-      (name.length === prefix.length ||
-        name[prefix.length] === name[prefix.length]?.toUpperCase())
-  )
-}
-
-/** How much of a catalogue's read/write split is annotation and how much is guess. */
-export const catalogueClassification = (
-  entries: readonly ApiCatalogueEntry[]
-) => {
-  const annotated = entries.filter(
-    (entry) => typeof entry.readonly === 'boolean'
-  ).length
-  return {
-    total: entries.length,
-    annotated,
-    inferred: entries.length - annotated,
-  }
-}
-
-/** One catalogue line: `name(inputKeys) -> outputKeys — description`. */
-const renderEntry = (entry: ApiCatalogueEntry): string => {
-  const inputs = (entry.inputKeys ?? []).join(',')
-  const outputs = (entry.outputKeys ?? []).join(',')
-  const description = entry.description
-    ? ` — ${entry.description.split('\n')[0]!.slice(0, 120)}`
-    : ''
-  return `${entry.name}(${inputs})${outputs ? ` -> ${outputs}` : ''}${description}`
-}
-
-/**
- * The whole reachable API as one compact index, for the instructions.
- *
- * Every endpoint is listed rather than retrieved against. Measured on a 430-RPC
- * project this is ~8k tokens, cached for the life of the run — cheaper than any
- * retrieval step, and it hides nothing. A ranking function would make the
- * virtual user only as adventurous as the ranking, which loses exactly the
- * endpoints worth stumbling into.
- */
-export const renderCatalogue = (
-  entries: readonly ApiCatalogueEntry[]
-): string => entries.map(renderEntry).join('\n')
-
-/**
- * The entries a given user may reach: approval-gated calls dropped unless the
- * run opted in, mutations dropped for a read-only disposition, and anything the
- * actor's tier cannot satisfy dropped when the caller supplied one.
- *
- * This narrows *what is offered*, never what is enforced — the server is the
- * only thing that decides who may call what, and a call this filter would have
- * denied still going through is a finding rather than a bug in the filter.
- */
-export const reachableCatalogue = (
-  entries: readonly ApiCatalogueEntry[],
-  {
-    readOnly = false,
-    allowApprovalRequired = false,
-    scopes,
-  }: {
-    readOnly?: boolean
-    allowApprovalRequired?: boolean
-    /**
-     * The scopes this persona holds, resolved from its roles. Omit to keep
-     * every entry.
-     *
-     * Scopes rather than permission-function names: a function's `scopes` are
-     * declared and checkable, whereas a permission is arbitrary code whose
-     * verdict nobody can predict without running it. Narrowing by something
-     * unpredictable produced a catalogue that was wrong in both directions.
-     */
-    scopes?: readonly string[]
-  } = {}
-): ApiCatalogueEntry[] =>
-  entries.filter((entry) => {
-    if (entry.approvalRequired && !allowApprovalRequired) return false
-    if (readOnly && !isReadOnly(entry)) return false
-    if (scopes && entry.scopes?.length) {
-      return hasScopes(entry.scopes, scopes)
-    }
-    return true
-  })
-
-/**
- * Endpoints this persona is *not* entitled to reach.
- *
- * The adversarial oracle. Withheld from the catalogue, so reaching one takes
- * initiative — and a 2xx from one is the finding, because the server is the
- * only thing that decides who may call what.
- */
-export const unreachableCatalogue = (
-  entries: readonly ApiCatalogueEntry[],
-  scopes: readonly string[]
-): ApiCatalogueEntry[] =>
-  entries.filter(
-    (entry) => !!entry.scopes?.length && !hasScopes(entry.scopes, scopes)
-  )
-
-/** Index a catalogue by name for the engine's lookups. */
-export const catalogueIndex = (
-  entries: readonly ApiCatalogueEntry[]
-): Map<string, ApiCatalogueEntry> =>
-  new Map(entries.map((entry) => [entry.name, entry]))
-
-/**
- * Find an entry by the name a model gave, forgiving the signature it just read.
- *
- * The catalogue renders as `name(inputs) -> outputs`, and a model that has the
- * line in front of it will sometimes hand the whole line back — `whoAmI() ->
- * userId,scopes` instead of `whoAmI`. Measured on a live run, 8 of 24 steps
- * went that way and every one of them was answered with "there is no endpoint
- * called that", which is true and useless.
- *
- * Forgiving it is not the same as guessing: an rpc name never contains a
- * bracket, so everything from the first one is the signature the catalogue
- * printed, and taking it off is unambiguous.
- */
-export const catalogueLookup = (
-  index: Map<string, ApiCatalogueEntry>,
-  rpcName: string
-): ApiCatalogueEntry | undefined => {
-  const exact = index.get(rpcName)
-  if (exact) {
-    return exact
-  }
-  const [head] = rpcName.trim().split('(')
-  return head && head !== rpcName ? index.get(head.trim()) : undefined
-}
-
-/**
- * What `describe` hands back: the full schemas, so the next call can be made
- * correctly rather than guessed at.
- *
- * Guessing field names is unproductive fuzz — every 400 becomes a typo and
- * nothing is learned from any of them. Reading the schema first is also what a
- * person does, since the form tells them the fields. It makes a subsequent 400
- * mean something: either the schema and the implementation disagree, or the
- * misuse is genuine and worth seeing.
- */
-export const describeEntry = (entry: ApiCatalogueEntry) => ({
-  name: entry.name,
-  description: entry.description,
-  readonly: isReadOnly(entry),
-  approvalRequired: entry.approvalRequired ?? false,
-  input: entry.inputSchema ?? { type: 'object', properties: {} },
-  output: entry.outputSchema ?? null,
-})