@pikku/core 0.12.71 → 0.12.74

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

@@ -0,0 +1,65 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+import { reachableAgents } from './virtual-user-agents.js'
+
+const AGENTS = {
+  'router-agent': {
+    name: 'router-agent',
+    description: 'Routes requests to the right domain agent',
+  },
+  'social-poster': {
+    name: 'social-poster',
+    description: 'Drafts and schedules posts',
+    scopes: ['content:write'],
+  },
+  'refund-agent': {
+    name: '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('falls back to the declaration key when an agent has no name', () => {
+    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

@@ -0,0 +1,57 @@
+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: `CoreAIAgent.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 {
+  name?: string
+  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, keyed by the name they are declared under.
+ *
+ * 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: agent.name ?? id,
+      ...(agent.description ? { description: agent.description } : {}),
+    }))

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

@@ -0,0 +1,215 @@
+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

@@ -0,0 +1,184 @@
+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,
+})