@pikku/core 0.12.72 → 0.12.77

package/src/wirings/ai-agent/ai-agent-prepare.test.ts

@@ -3,8 +3,10 @@ import assert from 'node:assert/strict'
 
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
 import {
+  CREDENTIAL_REQUIRED,
   agentSessionScope,
   assertResourceOwner,
+  assertResourcePrincipalOwner,
   canAccessThread,
   buildInstructions,
   buildSubAgentRunInput,
@@ -17,7 +19,7 @@ import {
   sessionPrincipals,
   threadOwnerConstraint,
 } from './ai-agent-prepare.js'
-import { ForbiddenError } from '../../errors/errors.js'
+import { ForbiddenError, MissingCredentialError } from '../../errors/errors.js'
 import { pikkuAuth } from '../../function/functions.types.js'
 import type {
   AIStreamChannel,
@@ -300,9 +302,6 @@ describe('ai-agent-prepare', () => {
         `Delete the todo called "${todoStore.get(id)?.title ?? id}"`,
     })
 
-    // The addon builds `todoStore` in its own singleton services, which are NOT
-    // in the root services and are only cached the first time the addon runs.
-    // The approval is raised before the tool executes, so the cache is cold.
     pikkuState('@test/todos-addon', 'package', 'factories', {
       createSingletonServices: async () => ({
         todoStore: {
@@ -376,6 +375,53 @@ describe('ai-agent-prepare', () => {
     assert.match(String(errorCalls[0][0]), /searchInventory.*execute/)
   })
 
+  test('buildToolDefs turns a MissingCredentialError into a Symbol-branded credential result', async () => {
+    addAgent('creds-agent')
+    pikkuState(null, 'agent', 'agentsMeta')['creds-agent'] = {
+      ...pikkuState(null, 'agent', 'agentsMeta')['creds-agent'],
+      tools: ['listRepos'],
+    } as any
+    pikkuState(null, 'rpc', 'meta').listRepos = 'listRepos'
+    pikkuState(null, 'function', 'meta').listRepos = {
+      description: 'List repos',
+      inputSchemaName: 'ListReposInput',
+      sessionless: true,
+    }
+    pikkuState(null, 'misc', 'schemas').set('ListReposInput', {
+      type: 'object',
+    })
+    pikkuState(null, 'function', 'functions').set('listRepos', {
+      func: async () => {
+        throw new MissingCredentialError('github', 'oauth2', '/connect/github')
+      },
+    })
+
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { warn: () => {}, error: () => {} },
+    } as any)
+
+    const { tools } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'creds-agent',
+      null
+    )
+
+    assert.equal(tools.length, 1)
+    const result = (await tools[0].execute({})) as Record<string | symbol, any>
+
+    assert.equal(
+      result[CREDENTIAL_REQUIRED],
+      true,
+      'the producer must stamp the non-forgeable brand'
+    )
+    assert.equal(result.__credentialRequired, true)
+    assert.equal(result.credentialName, 'github')
+    assert.equal(result.credentialType, 'oauth2')
+    assert.equal(result.connectUrl, '/connect/github')
+  })
+
   test('buildToolDefs skips permissioned tools without a session and adds sub-agent tools', async () => {
     addAgent('manager', {
       agents: ['assistant'],
@@ -431,13 +477,6 @@ describe('ai-agent-prepare', () => {
     })
   })
 
-  /**
-   * The permission's `pikkuAuth` brand survives only on the live objects in the
-   * function config, not on the metadata. Reading the metadata's by-name
-   * reference resolves against a registry nothing populates, so it collects no
-   * predicate and lets every gated tool through — this pins that the live config
-   * is what gets evaluated.
-   */
   const addFilterAgent = (allow: boolean) => {
     addAgent('gatekeeper', { tools: ['gated'] })
     pikkuState(null, 'agent', 'agentsMeta').gatekeeper = {
@@ -629,14 +668,75 @@ describe('C2 thread/run ownership + sessionScope', () => {
     )
   })
 
-  test('user scope falls back to the bare requested resourceId when sessionless', () => {
-    assert.equal(resolveOwnerResourceId({}, 'user', 'resource-1'), 'resource-1')
-    assert.equal(
+  test('a sessionless caller never owns the resourceId it asked for', () => {
+    assert.notEqual(
+      resolveOwnerResourceId({}, 'user', 'resource-1'),
+      'resource-1'
+    )
+    assert.notEqual(
       resolveOwnerResourceId(params(undefined), 'user', 'resource-1'),
       'resource-1'
     )
   })
 
+  test('a sessionless owner id is stable within a request and unique across requests', () => {
+    const request = params(undefined)
+    assert.equal(
+      resolveOwnerResourceId(request, 'user', 'a'),
+      resolveOwnerResourceId(request, 'user', 'b')
+    )
+    assert.notEqual(
+      resolveOwnerResourceId(params(undefined), 'user', 'a'),
+      resolveOwnerResourceId(params(undefined), 'user', 'a')
+    )
+  })
+
+  test('a sessionless caller cannot claim an existing resource by replaying its owner id', () => {
+    const owner = resolveOwnerResourceId(params(undefined), 'user', 'default')
+    assert.notEqual(
+      resolveOwnerResourceId(params(undefined), 'user', owner),
+      owner
+    )
+  })
+
+  test('assertResourcePrincipalOwner refuses every resource when there is no principal', () => {
+    assert.throws(
+      () =>
+        assertResourcePrincipalOwner(
+          params(undefined),
+          'user',
+          'resource-1',
+          'run'
+        ),
+      (e: unknown) => e instanceof ForbiddenError
+    )
+    assert.throws(
+      () => assertResourcePrincipalOwner({}, 'user', 'anon-abc', 'thread'),
+      (e: unknown) => e instanceof ForbiddenError
+    )
+  })
+
+  test('assertResourcePrincipalOwner admits the owning principal and refuses others', () => {
+    assert.doesNotThrow(() =>
+      assertResourcePrincipalOwner(
+        params({ userId: 'alice' }),
+        'user',
+        'alice:default',
+        'run'
+      )
+    )
+    assert.throws(
+      () =>
+        assertResourcePrincipalOwner(
+          params({ userId: 'bob' }),
+          'user',
+          'alice:default',
+          'run'
+        ),
+      (e: unknown) => e instanceof ForbiddenError
+    )
+  })
+
   test('org scope composes the trusted orgId with the requested resourceId', () => {
     assert.equal(
       resolveOwnerResourceId(
@@ -712,12 +812,10 @@ describe('thread-read ownership (session principals)', () => {
     )
   })
 
-  // A deployment with no session has explicitly opted out of authorization
-  // (agent `no-auth`), so there is no ownership model to enforce — matching
-  // resolveOwnerResourceId's own sessionless fallback to a bare resourceId.
-  test('a sessionless deployment has no ownership model and is not gated', () => {
-    assert.equal(canAccessThread('anything', undefined), true)
-    assert.equal(canAccessThread('anything', {}), true)
+  test('a sessionless caller can read no thread at all', () => {
+    assert.equal(canAccessThread('anything', undefined), false)
+    assert.equal(canAccessThread('anything', {}), false)
+    assert.equal(canAccessThread('anon-abc', undefined), false)
   })
 
   test('sessionPrincipals lists the userId and orgId a caller can read as', () => {
@@ -736,11 +834,9 @@ describe('thread-read ownership (session principals)', () => {
     )
   })
 
-  // undefined, not [] — [] means "match nothing", which would hide every thread
-  // from a no-auth deployment that never had an ownership model to begin with.
-  test('threadOwnerConstraint is undefined for a sessionless caller', () => {
-    assert.equal(threadOwnerConstraint(undefined), undefined)
-    assert.equal(threadOwnerConstraint({}), undefined)
+  test('threadOwnerConstraint matches nothing for a sessionless caller', () => {
+    assert.deepEqual(threadOwnerConstraint(undefined), [])
+    assert.deepEqual(threadOwnerConstraint({}), [])
   })
 })
 
@@ -778,12 +874,6 @@ describe('C2 sessionScope + resume ownership', () => {
 })
 
 describe('buildSubAgentRunInput (parent context forwarding)', () => {
-  // A delegated sub-agent's tool-call schema only carries { message, session }.
-  // If its run input does not inherit the parent's `context` (the identifier
-  // block with organizationId / project ids), the sub-agent never sees the
-  // authoritative ids and depends on the model re-typing them into `message` —
-  // which weak models botch, causing schema/permission rejections and retry
-  // loops. These pin that the parent context is always forwarded.
   test('forwards the parent context onto the sub-agent run input', () => {
     const input = buildSubAgentRunInput(
       'find failing functions',
@@ -804,3 +894,84 @@ describe('buildSubAgentRunInput (parent context forwarding)', () => {
     assert.equal(input.context, undefined)
   })
 })
+
+test('a tool description survives being stripped from the meta registered at boot', async () => {
+  addAgent('described-agent')
+  pikkuState(null, 'agent', 'agentsMeta')['described-agent'] = {
+    ...pikkuState(null, 'agent', 'agentsMeta')['described-agent'],
+    tools: ['archiveRecord'],
+  } as any
+  pikkuState(null, 'rpc', 'meta').archiveRecord = 'archiveRecord'
+
+  // What the bundled copy actually looks like: `stripVerboseFields` removes
+  // `description` and `title`, so the boot-time meta carries neither.
+  pikkuState(null, 'function', 'meta').archiveRecord = {
+    inputSchemaName: 'ArchiveInput',
+    sessionless: true,
+  }
+  pikkuState(null, 'misc', 'schemas').set('ArchiveInput', { type: 'object' })
+  pikkuState(null, 'function', 'functions').set('archiveRecord', {
+    func: async () => 'ok',
+  })
+
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: { warn: () => {} },
+    metaService: {
+      getFunctionsMeta: async () => ({
+        archiveRecord: {
+          description: 'Archive a record so it stops appearing in searches',
+        },
+      }),
+    },
+  } as any)
+
+  const { tools } = await buildToolDefs(
+    {},
+    new Map<string, string>(),
+    'resource-described',
+    'described-agent',
+    null
+  )
+
+  assert.equal(tools.length, 1)
+  assert.equal(
+    tools[0].description,
+    'Archive a record so it stops appearing in searches'
+  )
+})
+
+test('a tool with no description anywhere is still offered, under its own name', async () => {
+  addAgent('undescribed-agent')
+  pikkuState(null, 'agent', 'agentsMeta')['undescribed-agent'] = {
+    ...pikkuState(null, 'agent', 'agentsMeta')['undescribed-agent'],
+    tools: ['bareTool'],
+  } as any
+  pikkuState(null, 'rpc', 'meta').bareTool = 'bareTool'
+  // A title is deliberately not a description: it labels the tool in a UI, it
+  // does not tell a model when to reach for it.
+  pikkuState(null, 'function', 'meta').bareTool = {
+    title: 'Bare Tool',
+    inputSchemaName: 'BareInput',
+    sessionless: true,
+  }
+  pikkuState(null, 'misc', 'schemas').set('BareInput', { type: 'object' })
+  pikkuState(null, 'function', 'functions').set('bareTool', {
+    func: async () => 'ok',
+  })
+
+  // No metaService at all — a bundle with no readable .pikku directory.
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: { warn: () => {} },
+  } as any)
+
+  const { tools } = await buildToolDefs(
+    {},
+    new Map<string, string>(),
+    'resource-undescribed',
+    'undescribed-agent',
+    null
+  )
+
+  assert.equal(tools.length, 1)
+  assert.equal(tools[0].description, 'bareTool')
+})