@pikku/core 0.12.64 → 0.12.66

package/CHANGELOG.md

@@ -1,3 +1,224 @@
+## 0.12.66
+
+### Patch Changes
+
+- 5f19016: Widen the generated agent HTTP surface, and guard attachment downloads against SSRF.
+
+  `agentCaller` and `agentStreamCaller` declared only `message`, `threadId` and
+  `resourceId` (plus `context` on the stream route), so `attachments`, `model`,
+  `temperature` — all accepted by `AIAgentInput` — were unreachable over the
+  shipped HTTP contract. No deployed app could send an attachment or a per-request
+  model override. Both callers now share an `AgentCallerInput` type covering every
+  optional field and forward each one to the RPC.
+
+  Both callers declare that shape **inline** in the generic position rather than
+  behind a shared named alias: the schema extractor only reads type literals there
+  and synthesises the schema name from the function name. Behind an alias it
+  records an `inputSchemaName` with no schema generated for it, and every agent
+  HTTP call then fails at runtime with `MissingSchemaError`.
+
+  Widening that surface makes caller-supplied attachment URLs reachable, which is
+  an SSRF vector: the AI SDK downloads attachment URLs **server-side** whenever the
+  model cannot consume them natively, using an unguarded `fetch`. A caller could
+  point an attachment at the cloud metadata endpoint or another internal host and
+  have the response relayed into the model's context. `VercelAIAgentRunner` now
+  passes an `experimental_download` implementation backed by `safeFetch` (which
+  refuses private/internal hosts and non-HTTP schemes, and re-validates every
+  redirect hop) to both `streamText` and `generateText`. URLs the model supports
+  natively are passed through untouched, so the provider still fetches those
+  itself.
+
+  The runner takes an optional `allowedAttachmentHosts` allowlist, carried across
+  `withApiKey`. `safeFetch` is now exported from `@pikku/core/safe-fetch`.
+
+- 78e4778: Stop a failed message persist during an agent stream from killing the process.
+
+  The persisting channel flushes from inside `send`, which is synchronous and so cannot await the flush. Any rejection — a dropped storage connection, or a model reusing a `toolCallId`, which is a primary key in AI storage — escaped as an unhandled rejection and took the whole server down. Persistence from `send` is now best-effort and logged; the awaited `flush()` on the suspend paths still surfaces failures to its caller.
+
+- 4324652: Scope AI agent thread reads to the calling session.
+
+  The generated thread-management functions (`getAgentThreads`,
+  `getAgentThreadMessages`, `getAgentThreadRuns`, `deleteAgentThread`) keyed purely
+  off a caller-supplied `threadId` and treated `resourceId` as an optional filter,
+  so omitting it enumerated every tenant's threads.
+  - `listThreads` gains an `owners` **authorization constraint** (distinct from the
+    `resourceId` filter): an empty array matches nothing, and it is always derived
+    from the session, never from input. Implemented across the Kysely, Redis and
+    MongoDB agent run services, with LIKE/regex metacharacter escaping so an owner
+    id containing `_` or `%` cannot match a foreign owner.
+  - The three `threadId`-keyed functions are now guarded by an `isThreadOwner`
+    `pikkuPermission` rather than an in-body check. A thread that does not exist is
+    denied rather than 404'd, so it is indistinguishable from one owned by someone
+    else.
+  - New `@pikku/core/ai-agent` helpers: `canAccessThread`, `threadOwnerConstraint`,
+    `sessionPrincipals`, `isOwnedByPrincipal`.
+
+  Services destructured by a wired function are now non-optional inside it.
+
+  The inspector already aggregated the services used by every wired `func`,
+  `permissions` and `middleware` into `RequiredSingletonServices`, but the
+  generated function types defaulted their service parameter to the raw `Services`
+  — so a service declared `foo?: Foo` still arrived as possibly-undefined, forcing
+  `if (!foo) throw new MissingServiceError(...)` guards that could never fire.
+  Generated types now expose `WiredSingletonServices` / `WiredServices`
+  (`RequiredSingletonServices & Services`) and default the `RequiredServices`
+  generic of functions, permissions, middleware, auth and approval-description
+  helpers to them. Optionality now means only what it should: "this service may
+  not be created, because nothing uses it".
+
+- de044f8: Fix the agent tool-list permission filter failing open.
+
+  `buildToolDefs` filtered permission-gated tools by resolving `checkAuthPermissions` from a function's _metadata_ — a by-name lookup into the `misc/permissions` state that nothing ever populates. It therefore collected no predicate and returned `true`, so every auth-gated tool was offered to the model regardless of session (its input schema and description leaked, and the model could attempt calls that then failed at invocation).
+
+  `checkAuthPermissions` now takes the live `CorePermissionGroup` from the function/agent config, where the `pikkuAuth` brand actually survives — matching how the agent's own gate and the function runner already resolve permissions by reference. The dead by-name lookup (`getPermissionByName`) is removed. Enforcement on invocation was never affected; this closes the exposure gap in the offered tool list.
+
+- cd1a811: warn instead of silently ignoring unknown long CLI options
+
+  An unknown long option (`--sektion functions` or `--sektion=functions`) was parsed
+  into the options object and then silently dropped by the command's input schema —
+  the command ran with the real option at its default and produced plausible-but-wrong
+  output. Unknown long options are still accepted (forward compatibility is preserved),
+  but the parser now records a warning that the runner prints to stderr, e.g.
+  `Warning: Unknown option: --sektion (ignored) Did you mean --section?`.
+
+- 19fa6f0: Fix `HTTPRouteConfig` and `HTTPRoutesGroupConfig`'s default `PikkuPermission`/`PikkuMiddleware` type parameters under-specifying their own generic arguments (e.g. `CorePikkuPermission<any>` instead of `CorePikkuPermission<any, any, any>`). The missing arguments silently fell back to `CorePikkuPermission`'s own defaults (`CoreServices`, with `schema` optional) instead of `any`, so a project whose generated services type guarantees `schema` is always present (any project using `WiredServices`-style non-optional services) failed to type-check against `defineHTTPRoutes`/`wireHTTPRoutes` with a misleading `index signature` error.
+- b501612: Enforce authorization consistently across `pikku*` primitives.
+  - `pikkuAIAgent` now enforces `permissions` (previously accepted but never
+    checked) and gains `auth` and `scopes`. Scopes are checked before permissions.
+    `auth` defaults to `false`, matching `pikkuSessionlessFunc`, since agents are
+    typically invoked from an already-authenticated function or from sessionless
+    contexts such as crons and queue workers.
+  - `pikkuWorkflowFunc` / `pikkuWorkflowComplexFunc` schema config gains `auth`
+    and `scopes` alongside `permissions`.
+  - `pikkuScenario` no longer accepts `auth`, `scopes`, or `permissions` —
+    scenarios drive the app as actors and authorize per step.
+  - `wireGateway` no longer accepts `permissions`. A gateway proxies to an agent,
+    so access is governed by normal auth plus the target agent's own rules.
+  - Removed the dead `permissions` field from `CoreWorkflow`, which was never read.
+
+  Closed two paths that reached user code without authorization:
+  - Gateway handlers were invoked directly, so a handler's own `auth`, `scopes`
+    and `permissions` were never evaluated. Webhook, websocket and listener
+    gateways now invoke the handler through the function runner. Handlers are
+    sessionless by default (inbound gateway traffic is platform-authenticated by
+    the adapter, not session-bearing); declare `auth: true` to require a session.
+    A gateway's own `auth` field is now honoured too — it was previously ignored.
+    Gateway middleware runs before the gate, so `wire.setSession()` in gateway
+    middleware — the idiomatic way to map a verified platform sender to a user —
+    is visible to the handler's `auth` and `scopes`.
+  - Resuming a suspended agent run (`resumeAIAgentSync`, `resumeAIAgent`) checked
+    run ownership but never re-ran the agent's own gate, so a scope or permission
+    revoked while a run was suspended did not prevent the caller from resuming it
+    and approving its pending tool calls. Both now re-run `assertAgentAuthorized`
+    before any state is mutated.
+
+- eb37b1e: Fix `voiceInput` middleware losing the runner receiver: it grabbed
+  `aiAgentRunner.transcribe` as a bare method reference, so calling it left `this`
+  undefined and threw `Cannot read properties of undefined (reading 'getModel')`
+  on the first audio attachment. It now calls `aiAgentRunner.transcribe(...)`
+  directly, preserving the receiver.
+
+## 0.12.65
+
+### Patch Changes
+
+- 1a86d3f: Fix a fanout collapsing into a single step, and preserve graph node config.
+  - A fanout took its `stepName` from the first step of its body. Node ids _are_
+    step names, so the loop and that step got the same id and the step overwrote
+    the loop: `await Promise.all(users.map(...))` rendered as one plain call, and
+    everything after the loop became unreachable. A fanout is not itself a cached
+    step, so it no longer borrows a name.
+  - A `workflow.sleep` or `workflow.suspend` inside a fanout body was dropped at
+    extraction — `FanoutStepMeta.body` was typed RPC-only. It now admits sleep and
+    suspend, and the regenerated body emits them.
+  - Regenerating a `pikkuWorkflowGraph` dropped `onError`, `retries` and
+    `retryDelay` from every node, and graph-level `notes`. All four are honoured
+    at runtime, so the round trip silently changed behaviour.
+
+- 1a86d3f: Support multi-step fanout bodies in DSL workflows.
+
+  A `Promise.all(array.map(...))` (or `for...of`) body containing more than one
+  `workflow.do` call previously extracted only a single step: `const`-captured
+  steps were skipped entirely by the parallel extractor, so a body like
+
+  ```ts
+  await Promise.all(
+    users.map(async (u) => {
+      const digestData = await workflow.do('Get pipeline', 'getDigestData', {
+        userId: u.id,
+      })
+      await workflow.do('Send digest', 'sendDigestEmail', { ...digestData })
+    })
+  )
+  ```
+
+  produced a graph with `getDigestData` missing and `sendDigestEmail` referencing
+  an unregistered variable. `FanoutStepMeta.child` is replaced by
+  `FanoutStepMeta.body: RpcStepMeta[]`, holding the per-iteration steps inline in
+  the same workflow — no sub-workflow boundary. Per-iteration `const` bindings are
+  now registered so later steps in the same iteration can reference them, and the
+  sequential path no longer hard-errors on bodies with more than one step.
+
+- 1a86d3f: Add `onError` compensation to DSL workflows.
+
+  A DSL workflow had no way to express error handling at all — `try/catch` is not
+  an allowed statement, and step options carried only `retries`/`retryDelay`. A
+  step can now name a compensation RPC:
+
+  ```ts
+  await workflow.do(
+    'Charge',
+    'chargeCard',
+    { id },
+    {
+      retries: 3,
+      onError: 'refundOrder',
+    }
+  )
+  ```
+
+  Semantics mirror a graph node's `onError` exactly: once the step's retries are
+  exhausted the handler is invoked with `{ error: { message } }` and the original
+  error is still thrown. This is compensation, not recovery — the workflow fails
+  either way. The handler runs as its own durable step, so a replay cannot
+  compensate twice, and it does not inherit `onError` itself.
+
+  The handler is materialised as a real graph node, so it is wired like any other
+  RPC and the console draws a dashed red "on error" edge to it rather than the
+  route being invisible.
+
+- 1a86d3f: Stop silently dropping switch cases and spread returns from workflow graphs.
+  - A fall-through case (`case 'a': case 'b': ...`) recorded only the last value.
+    A run entering on `'a'` therefore appeared to match no case at all. Empty
+    clauses now carry through to the entry they fall into — the next non-empty
+    case, otherwise `default`, otherwise the switch exit.
+  - `return { ...r, extra: 1 }` produced a return node listing only `extra`, so
+    the graph claimed an output shape the workflow does not have, with no
+    diagnostic. `return r` produced no return node at all. `ReturnStepMeta` now
+    records a `spread` list, and the regenerated code emits it.
+
+- 1a86d3f: Stop corrupting values when regenerating a workflow from its graph.
+  - A numeric `workflow.sleep('Wait', 5000)` came back as `'5000'`, and a numeric
+    `retryDelay` likewise. Durations are `string | number`; only strings are
+    quoted now.
+  - An assignment to a context variable was stored as an opaque `value`, so
+    `count = count + 1` regenerated as `count = 'count + 1'` — an expression
+    turned into a string literal. `SetStepMeta` now carries a separate
+    `expression` field (mirroring `SwitchCaseMeta`), so a string literal and a
+    code expression are no longer indistinguishable in the meta.
+  - A `next` that was not a single node id was coerced with a string cast: an
+    array became the bogus id `'a,b'` and a branch-key record became
+    `'[object Object]'`, severing every downstream node. Arrays, key-based
+    routing tables and condition lists now each render in their own shape.
+  - A `filter`/`some`/`every` node with no `outputVar` emitted
+    `const undefined = ...`, which does not parse.
+
+- 1a86d3f: Keep a `workflow.sleep` whose duration is only known at runtime (a loop
+  variable, a field off the input). The closure evaluates it, so it is legal DSL;
+  its source text is recorded as an `expression` and emitted raw when regenerating
+  code, as a set step already does.
+- 3d76f51: Add an optional `docsUrl` to `wireSecret`, `wireVariable`, and `wireCredential`, so a console or deploy UI reporting a missing value can link the user to where they obtain it instead of showing a bare identifier.
+
 ## 0.12.64
 
 ### Patch Changes

package/dist/permissions.d.ts

@@ -1,4 +1,4 @@
-import type { CoreServices, CoreUserSession, PermissionMetadata, PikkuWire } from './types/core.types.js';
+import type { CoreServices, CoreUserSession, PikkuWire } from './types/core.types.js';
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
 /**
@@ -36,12 +36,14 @@ export declare const addTagPermission: (_tag: string, _permissions: CorePermissi
  * A passing global requirement never contributes to the function gate, so a
  * broad global like `signedIn` can't satisfy an admin-only function.
  */
-export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, }: {
+export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];
     services: CoreServices;
     wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>;
     data: any;
     packageName?: string | null;
+    /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */
+    label?: string;
 }) => Promise<void>;
 /**
  * Checks whether a session passes the auth checks (pikkuAuth only) for a
@@ -49,10 +51,16 @@ export declare const runPermissions: ({ funcPermissions, services, wire, data, p
  * request data which isn't available at filter time. Global auth requirements
  * are included so a filtered list honours app-wide auth.
  *
- * @param funcPermissions - The PermissionMetadata[] from function or agent metadata
+ * `funcPermissions` is the live {@link CorePermissionGroup} from the function or
+ * agent config, not the metadata form: the `pikkuAuth` brand only survives on
+ * the actual predicate objects, and the by-name registry those metadata entries
+ * would resolve against is never populated. Passing metadata here would silently
+ * collect nothing and let every gated tool through.
+ *
+ * @param funcPermissions - The live permission group from the func/agent config
  * @param session - The user's session
  * @param services - Singleton services
  * @param packageName - Optional package namespace
  * @returns true if the session passes the auth checks (or no auth checks exist)
  */
-export declare const checkAuthPermissions: (funcPermissions: PermissionMetadata[] | undefined, session: CoreUserSession, services: CoreServices, packageName?: string | null) => Promise<boolean>;
+export declare const checkAuthPermissions: (funcPermissions: CorePermissionGroup | undefined, session: CoreUserSession, services: CoreServices, packageName?: string | null) => Promise<boolean>;

package/dist/permissions.js

@@ -40,26 +40,6 @@ const verifyPermissions = async (permissions, services, data, wire) => {
     }
     return false;
 };
-/**
- * Retrieves a registered permission function by its name.
- *
- * This function looks up permissions that was registered with registerPermission.
- * It's used internally by the framework to resolve permission references in metadata.
- *
- * @param {string} name - The unique name (pikkuFuncId) of the permission function.
- * @param {string | null} packageName - Optional package namespace.
- * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
- *
- * @internal
- */
-const getPermissionByName = (name, packageName = null) => {
-    const permissionStore = pikkuState(packageName, 'misc', 'permissions');
-    const permission = permissionStore[name];
-    if (Array.isArray(permission) && permission.length === 1) {
-        return permission[0];
-    }
-    return undefined;
-};
 const globalPermissionsCache = {};
 export const clearPermissionsCache = () => {
     for (const key of Object.keys(globalPermissionsCache)) {
@@ -131,7 +111,7 @@ const asGroup = (entry) => typeof entry === 'function' ? { permission: entry } :
  * A passing global requirement never contributes to the function gate, so a
  * broad global like `signedIn` can't satisfy an admin-only function.
  */
-export const runPermissions = async ({ funcPermissions, services, wire, data, packageName = null, }) => {
+export const runPermissions = async ({ funcPermissions, services, wire, data, packageName = null, label = 'function', }) => {
     const globals = resolveGlobalPermissions(packageName);
     for (const entry of globals) {
         if (!(await verifyPermissions(asGroup(entry), services, data, wire))) {
@@ -145,7 +125,7 @@ export const runPermissions = async ({ funcPermissions, services, wire, data, pa
             : funcPermissions;
         if (group && Object.keys(group).length > 0) {
             if (!(await verifyPermissions(group, services, data, wire))) {
-                services.logger.debug('Permission denied - function permission');
+                services.logger.debug(`Permission denied - ${label} permission`);
                 throw new ForbiddenError('Permission denied');
             }
         }
@@ -157,7 +137,13 @@ export const runPermissions = async ({ funcPermissions, services, wire, data, pa
  * request data which isn't available at filter time. Global auth requirements
  * are included so a filtered list honours app-wide auth.
  *
- * @param funcPermissions - The PermissionMetadata[] from function or agent metadata
+ * `funcPermissions` is the live {@link CorePermissionGroup} from the function or
+ * agent config, not the metadata form: the `pikkuAuth` brand only survives on
+ * the actual predicate objects, and the by-name registry those metadata entries
+ * would resolve against is never populated. Passing metadata here would silently
+ * collect nothing and let every gated tool through.
+ *
+ * @param funcPermissions - The live permission group from the func/agent config
  * @param session - The user's session
  * @param services - Singleton services
  * @param packageName - Optional package namespace
@@ -189,15 +175,8 @@ export const checkAuthPermissions = async (funcPermissions, session, services, p
     for (const entry of resolveGlobalPermissions(packageName)) {
         collect(entry);
     }
-    if (funcPermissions?.length) {
-        for (const meta of funcPermissions) {
-            if (meta.type === 'wire') {
-                const permission = getPermissionByName(meta.name, packageName);
-                if (permission) {
-                    collect(permission);
-                }
-            }
-        }
+    if (funcPermissions) {
+        collect(funcPermissions);
     }
     // No auth permissions = allowed (only data-dependent permissions exist)
     if (authPerms.length === 0)

package/dist/testing/service-tests.js

@@ -742,6 +742,43 @@ export function defineServiceTests(config) {
                 const threads = await agentService.listThreads();
                 assert.ok(Array.isArray(threads));
             });
+            if (services.aiStorageService) {
+                const storageFactory = services.aiStorageService;
+                // The `owners` constraint is what keeps the generated thread-management
+                // functions from leaking across tenants: a caller may only list threads
+                // owned by one of their session principals, matching the
+                // `principal:sub-partition` composition resolveOwnerResourceId writes.
+                test('listThreads scopes to the given owners, including sub-partitions', async () => {
+                    const storage = await storageFactory();
+                    await storage.createThread('owner-alice');
+                    await storage.createThread('owner-alice:project-1');
+                    await storage.createThread('owner-bob:secret');
+                    const threads = await agentService.listThreads({
+                        owners: ['owner-alice'],
+                    });
+                    const ids = threads.map((t) => t.resourceId);
+                    assert.ok(ids.includes('owner-alice'));
+                    assert.ok(ids.includes('owner-alice:project-1'));
+                    assert.ok(!ids.some((id) => id.startsWith('owner-bob')), "another owner's threads must not be listed");
+                });
+                test('listThreads with an owner does not match a lookalike prefix', async () => {
+                    const storage = await storageFactory();
+                    await storage.createThread('owner-al');
+                    await storage.createThread('owner-alice-evil:p');
+                    const threads = await agentService.listThreads({
+                        owners: ['owner-al'],
+                    });
+                    const ids = threads.map((t) => t.resourceId);
+                    assert.ok(ids.includes('owner-al'));
+                    assert.ok(!ids.includes('owner-alice-evil:p'));
+                });
+                test('listThreads with an empty owners list returns nothing', async () => {
+                    const storage = await storageFactory();
+                    await storage.createThread('owner-empty-check');
+                    const threads = await agentService.listThreads({ owners: [] });
+                    assert.deepEqual(threads, []);
+                });
+            }
             test('getThread returns null for missing', async () => {
                 const thread = await agentService.getThread('missing-thread');
                 assert.equal(thread, null);

package/dist/wirings/ai-agent/ai-agent-prepare.d.ts

@@ -34,6 +34,49 @@ export declare function agentSessionScope(agentName: string): SessionScope;
  * existence oracle) on a mismatch.
  */
 export declare function assertResourceOwner(ownerResourceId: string, storedResourceId: string, kind: 'thread' | 'run'): void;
+/** A session's trusted principals, in the order they may be read as. */
+export declare function sessionPrincipals(session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): string[];
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export declare function isOwnedByPrincipal(storedResourceId: string, principal: string): boolean;
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export declare function threadOwnerConstraint(session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): string[] | undefined;
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export declare function canAccessThread(storedResourceId: string, session: {
+    userId?: string;
+    orgId?: string;
+} | undefined): boolean;
 export type StreamAIAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
     /**
@@ -93,6 +136,27 @@ export declare const resolveAgent: (agentName: string) => {
     packageName: string | null;
     resolvedName: string;
 };
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export declare function assertAgentAuthorized(agent: CoreAIAgent, params: RunAIAgentParams, packageName: string | null): Promise<void>;
 export declare function buildInstructions(agentName: string, packageName: string | null): Promise<string>;
 export type ScopedChannel = AIStreamChannel & {
     approvals: Array<{

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -1,7 +1,8 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions } from '../../permissions.js';
+import { checkAuthPermissions, runPermissions } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { ForbiddenError } from '../../errors/errors.js';
+import { verifyScopes } from '../../scopes.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from './ai-agent-utils.js';
@@ -62,6 +63,53 @@ export function assertResourceOwner(ownerResourceId, storedResourceId, kind) {
         throw new ForbiddenError(`Not authorized to access this ${kind}`);
     }
 }
+/** A session's trusted principals, in the order they may be read as. */
+export function sessionPrincipals(session) {
+    return [session?.userId, session?.orgId].filter((principal) => Boolean(principal));
+}
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export function isOwnedByPrincipal(storedResourceId, principal) {
+    return (storedResourceId === principal ||
+        storedResourceId.startsWith(`${principal}:`));
+}
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export function threadOwnerConstraint(session) {
+    const principals = sessionPrincipals(session);
+    return principals.length > 0 ? principals : undefined;
+}
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export function canAccessThread(storedResourceId, session) {
+    const principals = sessionPrincipals(session);
+    if (principals.length === 0)
+        return true;
+    return principals.some((principal) => isOwnedByPrincipal(storedResourceId, principal));
+}
 /**
  * Non-forgeable brand for the sub-agent approval marker. Only framework code
  * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
@@ -163,6 +211,47 @@ export const resolveAgent = (agentName) => {
     }
     throw new Error(`AI agent not found: ${agentName}`);
 };
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export async function assertAgentAuthorized(agent, params, packageName) {
+    const session = params.sessionService
+        ? await params.sessionService.get()
+        : undefined;
+    if (agent.auth === true && !session) {
+        throw new ForbiddenError('Authentication required');
+    }
+    verifyScopes(agent.scopes, session);
+    const singletonServices = getSingletonServices();
+    const wire = params.sessionService
+        ? createMiddlewareSessionWireProps(params.sessionService)
+        : { session: undefined };
+    await runPermissions({
+        funcPermissions: agent.permissions,
+        services: singletonServices,
+        wire: wire,
+        data: {},
+        packageName,
+        label: 'agent',
+    });
+}
 export async function buildInstructions(agentName, packageName) {
     const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
     const parts = [];
@@ -279,11 +368,17 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 missingRpcs.push(toolName);
                 continue;
             }
-            // Filter out tools the user doesn't have auth for
+            // Filter out tools the user doesn't have auth for. The `pikkuAuth` brand
+            // only survives on the live permission objects in the function config, so
+            // the check reads those rather than the metadata (whose by-name registry
+            // is never populated, which would let every gated tool through).
             if (fnMeta.permissions?.length) {
                 if (!session)
                     continue;
-                const allowed = await checkAuthPermissions(fnMeta.permissions, session, singletonServices, resolvedPkg);
+                const funcConfig = pikkuFuncId
+                    ? pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId)
+                    : undefined;
+                const allowed = await checkAuthPermissions(funcConfig?.permissions, session, singletonServices, resolvedPkg);
                 if (!allowed)
                     continue;
             }
@@ -351,11 +446,13 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 singletonServices.logger.warn(`Sub-agent '${subAgentName}' not found in agent registry`);
                 continue;
             }
-            // Filter out sub-agents the user doesn't have auth for
+            // Filter out sub-agents the user doesn't have auth for, reading the live
+            // agent config for the same reason the tool path does.
             if (subMeta.permissions?.length) {
                 if (!session)
                     continue;
-                const allowed = await checkAuthPermissions(subMeta.permissions, session, singletonServices);
+                const subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName);
+                const allowed = await checkAuthPermissions(subAgent?.permissions, session, singletonServices);
                 if (!allowed)
                     continue;
             }
@@ -567,6 +664,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
 export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
     const singletonServices = getSingletonServices();
     const { agent, packageName, resolvedName } = resolveAgent(agentName);
+    await assertAgentAuthorized(agent, params, packageName);
     let agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
         throw new AIProviderNotConfiguredError();

package/dist/wirings/ai-agent/ai-agent-runner.js

@@ -1,5 +1,5 @@
 import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, } from './ai-agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
@@ -293,6 +293,10 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         throw new Error(`Run ${runId} is not suspended (status: ${run.status})`);
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
+    // Resuming re-runs the agent, so it re-runs the agent's gate. Run ownership
+    // alone is not enough: a grant revoked while the run was suspended must stop
+    // the caller from approving its pending tool calls.
+    await assertAgentAuthorized(agent, params, packageName);
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;