@pikku/core 0.12.64 → 0.12.66

package/dist/wirings/variable/validate-variable-definitions.js

@@ -24,6 +24,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                     description: def.description,
                     variableId: def.variableId,
                     schema: def.schema,
+                    docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -37,6 +38,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                 description: def.description,
                 variableId: def.variableId,
                 schema: def.schema,
+                docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };
         }

package/dist/wirings/variable/variable.types.d.ts

@@ -4,6 +4,13 @@ export type CoreVariable<T = unknown> = {
     description?: string;
     variableId: string;
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
     name: string;
@@ -11,6 +18,13 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     sourceFile?: string;
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -15,6 +15,13 @@ export interface WorkflowStepOptions {
     retries?: number;
     /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
     retryDelay?: string | number;
+    /**
+     * RPC to invoke for compensation when this step fails after exhausting its
+     * retries. Mirrors a graph node's `onError`: the handler receives
+     * `{ error: { message } }` and the original error is still thrown, so the
+     * workflow fails — this is compensation, not recovery.
+     */
+    onError?: string;
     /**
      * Run this step as an actor (scenarios). The RPC is sent through the
      * actor's authenticated client over the REAL transport — never dispatched
@@ -214,16 +221,20 @@ export interface ParallelGroupStepMeta {
  */
 export interface FanoutStepMeta {
     type: 'fanout';
-    /** Step name for this fanout */
-    stepName: string;
+    /**
+     * Step name for this fanout. Optional: a fanout is not itself a cached step,
+     * and node ids are step names — borrowing a body step's name would give the
+     * loop and that step the same id, collapsing one onto the other.
+     */
+    stepName?: string;
     /** Source array variable name */
     sourceVar: string;
     /** Iterator variable name */
     itemVar: string;
     /** Execution mode */
     mode: 'parallel' | 'sequential';
-    /** Child step to execute per iteration */
-    child: RpcStepMeta;
+    /** Steps to execute inline per iteration, in order */
+    body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>;
     /** Time between iterations (sequential mode only) */
     timeBetween?: string;
 }
@@ -234,6 +245,12 @@ export interface ReturnStepMeta {
     type: 'return';
     /** Output bindings */
     outputs: Record<string, OutputBinding>;
+    /**
+     * Variables spread into the returned object (`return { ...r }`), or the sole
+     * returned variable (`return r`). Their fields are not enumerable statically,
+     * so they are recorded by name rather than expanded into `outputs`.
+     */
+    spread?: string[];
 }
 /**
  * Inline step metadata (legacy support)
@@ -258,6 +275,13 @@ export interface SleepStepMeta {
     stepName: string;
     /** Sleep duration */
     duration: string | number;
+    /**
+     * Source text of a duration only known at runtime (e.g. a loop variable).
+     * The closure evaluates it, so it is legal DSL; it is kept separate from
+     * `duration` so regenerated code emits it raw rather than as a string
+     * literal, exactly as `expression` does on a set step.
+     */
+    expression?: string;
 }
 /**
  * Cancel step metadata
@@ -276,8 +300,14 @@ export interface SetStepMeta {
     type: 'set';
     /** Variable name to set (must be in context) */
     variable: string;
-    /** Value to assign (literal or expression) */
-    value: unknown;
+    /** Literal value to assign. Mutually exclusive with `expression`. */
+    value?: unknown;
+    /**
+     * Source text of a non-literal assignment (e.g. `count + 1`). Kept separate
+     * from `value` so regenerated code can emit it raw — a string `value` is a
+     * string literal, an `expression` is code.
+     */
+    expression?: string;
 }
 /**
  * Switch case metadata

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -443,6 +443,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * loop exits immediately without recording a step error or retrying.
      */
     private runInlineRetryLoop;
+    /**
+     * Run a failed step's compensation handler as a durable step of its own.
+     *
+     * Durable rather than a bare invoke so a replay does not compensate twice —
+     * a handler is typically a refund or a rollback. `onError` is deliberately
+     * not forwarded: a compensation handler cannot itself compensate.
+     */
+    private runStepCompensation;
     private rpcStep;
     private inlineStep;
     private sleepStep;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -1156,6 +1156,16 @@ export class PikkuWorkflowService {
             }
         }
     }
+    /**
+     * Run a failed step's compensation handler as a durable step of its own.
+     *
+     * Durable rather than a bare invoke so a replay does not compensate twice —
+     * a handler is typically a refund or a rollback. `onError` is deliberately
+     * not forwarded: a compensation handler cannot itself compensate.
+     */
+    async runStepCompensation(runId, stepName, onErrorRpcName, rpcService, error) {
+        await this.rpcStep(runId, `${stepName}:onError`, onErrorRpcName, { error: { message: error.message } }, rpcService, { retries: 0 });
+    }
     async rpcStep(runId, logicalStepName, rpcName, data, rpcService, stepOptions) {
         // Capture the predecessor before nextStepKey advances the lineage to us.
         const fromStepName = this.lastStepName(runId);
@@ -1168,6 +1178,7 @@ export class PikkuWorkflowService {
             retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: stepOptions?.retryDelay,
             actor: stepOptions?.actor,
+            onError: stepOptions?.onError,
         };
         // Check if step already exists
         let stepState;
@@ -1186,6 +1197,11 @@ export class PikkuWorkflowService {
             // Step failed with retries exhausted - throw error to fail the workflow
             const error = new Error(stepState.error?.message ||
                 `Step '${stepName}' failed after exhausting all retries`);
+            // Compensation, mirroring a graph node's onError: run the handler, then
+            // still throw — the workflow fails either way.
+            if (resolvedStepOptions.onError) {
+                await this.runStepCompensation(runId, stepName, resolvedStepOptions.onError, rpcService, error);
+            }
             // Preserve original error properties if available
             if (stepState.error) {
                 Object.assign(error, stepState.error);

package/dist/wirings/workflow/workflow.types.d.ts

@@ -194,8 +194,6 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     func: PikkuFunctionConfig;
     /** Middleware chain for this workflow */
     middleware?: PikkuFunctionConfig['middleware'];
-    /** Permission requirements */
-    permissions?: PikkuFunctionConfig['permissions'];
     /** Tags for organization and filtering */
     tags?: string[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.64",
+  "version": "0.12.66",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -33,6 +33,7 @@
     "./scheduler": "./dist/wirings/scheduler/index.js",
     "./trigger": "./dist/wirings/trigger/index.js",
     "./rpc": "./dist/wirings/rpc/index.js",
+    "./safe-fetch": "./dist/utils/safe-fetch.js",
     "./mcp": "./dist/wirings/mcp/index.js",
     "./ai-agent": "./dist/wirings/ai-agent/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",

package/src/permissions.test.ts

@@ -6,7 +6,7 @@ import {
   clearPermissionsCache,
   checkAuthPermissions,
 } from './permissions.js'
-import { pikkuState, resetPikkuState } from './pikku-state.js'
+import { resetPikkuState } from './pikku-state.js'
 import { pikkuAuth } from './function/functions.types.js'
 import type { CoreServices, CoreUserSession } from './types/core.types.js'
 import type { CorePermissionGroup } from './function/functions.types.js'
@@ -190,25 +190,31 @@ describe('checkAuthPermissions', () => {
     )
   })
 
-  test('resolves a function-referenced (wire) auth predicate by name', async () => {
-    const store = pikkuState(null, 'misc', 'permissions')
-    store['isAdmin'] = [pikkuAuth(async () => false)] as any
+  test('evaluates a live pikkuAuth predicate from the config group', async () => {
     assert.equal(
       await checkAuthPermissions(
-        [{ type: 'wire', name: 'isAdmin' }],
+        { admin: pikkuAuth(async () => false) as any },
         mockSession,
         mockServices
       ),
       false
     )
+    assert.equal(
+      await checkAuthPermissions(
+        { admin: pikkuAuth(async () => true) as any },
+        mockSession,
+        mockServices
+      ),
+      true
+    )
   })
 
   test('ignores data-dependent permissions (no auth marker)', async () => {
-    const store = pikkuState(null, 'misc', 'permissions')
-    store['ownsRow'] = [async () => false] as any
+    // A bare pikkuPermission carries no __pikkuAuth brand, so it cannot be
+    // evaluated at filter time and must not gate the tool list.
     assert.equal(
       await checkAuthPermissions(
-        [{ type: 'wire', name: 'ownsRow' }],
+        { ownsRow: (async () => false) as any },
         mockSession,
         mockServices
       ),

package/src/permissions.ts

@@ -1,7 +1,6 @@
 import type {
   CoreServices,
   CoreUserSession,
-  PermissionMetadata,
   PikkuWire,
 } from './types/core.types.js'
 import type {
@@ -60,29 +59,6 @@ const verifyPermissions = async (
   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: string,
-  packageName: string | null = null
-): CorePikkuPermission | undefined => {
-  const permissionStore = pikkuState(packageName, 'misc', 'permissions')
-  const permission = permissionStore[name]
-  if (Array.isArray(permission) && permission.length === 1) {
-    return permission[0]
-  }
-  return undefined
-}
 
 const globalPermissionsCache: Record<
   string,
@@ -190,12 +166,15 @@ export const runPermissions = async ({
   wire,
   data,
   packageName = null,
+  label = 'function',
 }: {
   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
 }) => {
   const globals = resolveGlobalPermissions(packageName)
   for (const entry of globals) {
@@ -211,7 +190,7 @@ export const runPermissions = async ({
       : 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')
       }
     }
@@ -224,14 +203,20 @@ export const runPermissions = async ({
  * 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 const checkAuthPermissions = async (
-  funcPermissions: PermissionMetadata[] | undefined,
+  funcPermissions: CorePermissionGroup | undefined,
   session: CoreUserSession,
   services: CoreServices,
   packageName: string | null = null
@@ -271,15 +256,8 @@ export const checkAuthPermissions = async (
     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)

package/src/testing/service-tests.ts

@@ -1086,6 +1086,55 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         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/src/wirings/ai-agent/ai-agent-authorization.test.ts

@@ -0,0 +1,204 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  resetPikkuState,
+  pikkuState,
+  setSingletonServices,
+} from '../../pikku-state.js'
+import { assertAgentAuthorized } from './ai-agent-prepare.js'
+import { clearPermissionsCache } from '../../permissions.js'
+import { ForbiddenError, MissingScopeError } from '../../errors/errors.js'
+import type { CoreAIAgent } from './ai-agent.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as any
+
+beforeEach(() => {
+  resetPikkuState()
+  clearPermissionsCache()
+  setSingletonServices({ logger } as any)
+})
+
+const addAgent = (
+  agentName: string,
+  overrides: Partial<CoreAIAgent> = {}
+): CoreAIAgent => {
+  const agent: CoreAIAgent = {
+    name: agentName,
+    description: `${agentName} description`,
+    goal: `${agentName} goal`,
+    instructions: `${agentName} instructions`,
+    model: 'test/test-model',
+    ...overrides,
+  } as CoreAIAgent
+
+  pikkuState(null, 'agent', 'agents').set(agentName, agent)
+  return agent
+}
+
+const sessionService = (session: CoreUserSession | undefined) =>
+  ({
+    get: () => session,
+    setInitial: () => {},
+    sessionChanged: false,
+  }) as any
+
+describe('assertAgentAuthorized', () => {
+  test('resolves when the agent declares no authorization and a session exists', async () => {
+    const agent = addAgent('open')
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService({ userId: 'u1' }) },
+      null
+    )
+  })
+
+  test('does not require a session unless auth is explicitly true', async () => {
+    const agent = addAgent('sessionless')
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService(undefined) },
+      null
+    )
+  })
+
+  test('resolves with no sessionService at all (cron / queue invocation)', async () => {
+    const agent = addAgent('no-session-service')
+    await assertAgentAuthorized(agent, {}, null)
+  })
+
+  test('throws ForbiddenError when auth is explicitly true and no session exists', async () => {
+    const agent = addAgent('needs-session', { auth: true })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService(undefined) },
+          null
+        ),
+      ForbiddenError
+    )
+  })
+
+  test('enforces scopes even when auth is not required', async () => {
+    const agent = addAgent('scoped-sessionless', { scopes: ['reports:read'] })
+    await assert.rejects(
+      () => assertAgentAuthorized(agent, {}, null),
+      MissingScopeError
+    )
+  })
+
+  test('throws ForbiddenError when the permission group denies', async () => {
+    const agent = addAgent('guarded', {
+      permissions: { admin: async () => false },
+    })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService({ userId: 'u1' }) },
+          null
+        ),
+      ForbiddenError
+    )
+  })
+
+  test('resolves when at least one permission branch passes', async () => {
+    const agent = addAgent('or-group', {
+      permissions: {
+        admin: async () => false,
+        owner: async () => true,
+      },
+    })
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService({ userId: 'u1' }) },
+      null
+    )
+  })
+
+  test('passes the session through to permission functions', async () => {
+    let seen: CoreUserSession | undefined
+    const agent = addAgent('sees-session', {
+      permissions: {
+        admin: async (_services: any, _data: any, wire: any) => {
+          seen = wire.session
+          return true
+        },
+      },
+    })
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService({ userId: 'u1' }) },
+      null
+    )
+    assert.equal(seen?.userId, 'u1')
+  })
+
+  test('throws MissingScopeError when a required scope is not held', async () => {
+    const agent = addAgent('scoped', { scopes: ['reports:read'] })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService({ userId: 'u1', scopes: [] }) },
+          null
+        ),
+      MissingScopeError
+    )
+  })
+
+  test('resolves when the session holds the required scope', async () => {
+    const agent = addAgent('scoped-ok', { scopes: ['reports:read'] })
+    await assertAgentAuthorized(
+      agent,
+      {
+        sessionService: sessionService({
+          userId: 'u1',
+          scopes: ['reports:read'],
+        }),
+      },
+      null
+    )
+  })
+
+  test('resolves when an ancestor scope grant covers the requirement', async () => {
+    const agent = addAgent('scoped-parent', { scopes: ['reports:read'] })
+    await assertAgentAuthorized(
+      agent,
+      {
+        sessionService: sessionService({ userId: 'u1', scopes: ['reports'] }),
+      },
+      null
+    )
+  })
+
+  test('checks scopes before permissions', async () => {
+    let permissionRan = false
+    const agent = addAgent('scope-first', {
+      scopes: ['reports:read'],
+      permissions: {
+        admin: async () => {
+          permissionRan = true
+          return true
+        },
+      },
+    })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService({ userId: 'u1', scopes: [] }) },
+          null
+        ),
+      MissingScopeError
+    )
+    assert.equal(permissionRan, false)
+  })
+})