@pikku/core 0.12.137 → 0.12.139

package/dist/wirings/addon/define-screens.js

@@ -0,0 +1,5 @@
+/**
+ * Declares the screens an addon ships, which the host mounts when it is wired
+ * with `ui: true`. Read statically by `pikku all`, so `path`, `title`, `nav`, `scopes` and `app` must be literals.
+ */
+export const defineScreens = (manifest) => manifest;

package/dist/wirings/addon/index.d.ts

@@ -1,5 +1,7 @@
 export { wireAddon } from './wire-addon.js';
 export type { WireAddonConfig } from './wire-addon.js';
+export { defineScreens } from './define-screens.js';
+export type { ScreensManifest, AddonScreen, AddonComponentScreen, AddonAppScreen, } from './define-screens.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

package/dist/wirings/addon/index.js

@@ -1,3 +1,4 @@
 export { wireAddon } from './wire-addon.js';
+export { defineScreens } from './define-screens.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

package/dist/wirings/addon/wire-addon.d.ts

@@ -41,8 +41,21 @@ export type WireAddonConfig = {
     mcpEndpoint?: boolean | string;
     /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /**
+     * Mounts the screens the addon ships (see `defineScreens`) in the host under
+     * `/addons/<name>`. Without it the addon's screens are ignored. The package
+     * must declare at least one, or `pikku all` rejects the wiring.
+     */
+    ui?: boolean;
     /** Required of every function in the addon, on top of the function's own. */
     scopes?: string[];
+    /**
+     * The other addons this one may call, as `{ '<package>': '<name>' }`: the
+     * package it was written against, and the name that package is wired under
+     * in this app. The addon calls `'<package>:<function>'`; anything it did not
+     * list is refused, whatever else the app has wired.
+     */
+    uses?: Record<string, string>;
     /** Points a secret the addon reads at a different key in this deployment, so two instances can hold different credentials. */
     secretOverrides?: Record<string, string>;
     /** Points a variable the addon reads at a different key in this deployment. */
@@ -65,6 +78,20 @@ export type WireAddonConfig = {
      * deploy manifest, and only the consuming app can grant it.
      */
     globalCredentials?: string;
+    /**
+     * The folder of the content store this instance owns. Everything it stores
+     * lands under it and it cannot see past it. Defaults to `name`.
+     */
+    contentBucket?: string;
+    /**
+     * Paths outside its own folder this instance may use, by path prefix:
+     * `read` allows reads and signed downloads, `write` adds uploads, writes and
+     * deletes. The longest matching prefix decides. The addon names a granted
+     * path by starting its bucket with `@`.
+     */
+    contentGrants?: Record<string, 'read' | 'write'>;
+    /** Hands over the whole `ContentService` unscoped. The value is the reason, recorded in the deploy manifest. */
+    globalContent?: string;
 };
 /**
  * Installs an addon into this project: its functions, wirings and scopes become

package/dist/wirings/addon/wire-addon.js

@@ -14,6 +14,7 @@ export const wireAddon = (config) => {
         tags: config.tags,
         ...(config.expose !== undefined ? { expose: config.expose } : {}),
         ...(config.scopes ? { scopes: config.scopes } : {}),
+        ...(config.uses ? { uses: config.uses } : {}),
         ...(config.secretOverrides
             ? { secretOverrides: config.secretOverrides }
             : {}),
@@ -31,6 +32,9 @@ export const wireAddon = (config) => {
         ...(config.globalCredentials
             ? { globalCredentials: config.globalCredentials }
             : {}),
+        ...(config.contentBucket ? { contentBucket: config.contentBucket } : {}),
+        ...(config.contentGrants ? { contentGrants: config.contentGrants } : {}),
+        ...(config.globalContent ? { globalContent: config.globalContent } : {}),
     });
 };
 /**

package/dist/wirings/agent/agent-agui.js

@@ -27,59 +27,62 @@ export function wrapChannelWithAGUI(inner, options) {
     let sawUsage = false;
     let usageModel;
     const usageTotals = { input: 0, output: 0 };
-    function send(event) {
+    async function send(event) {
         if (!runStartedSent) {
             runStartedSent = true;
-            inner.send({
+            await inner.send({
                 type: 'RUN_STARTED',
                 threadId,
                 runId: resolveRunId(),
             });
         }
-        inner.send(event);
+        await inner.send(event);
     }
-    function endTextMessage() {
+    async function endTextMessage() {
         if (textMessageId) {
-            send({ type: 'TEXT_MESSAGE_END', messageId: textMessageId });
+            await send({ type: 'TEXT_MESSAGE_END', messageId: textMessageId });
             textMessageId = null;
         }
     }
-    function endThinkingMessage() {
+    async function endThinkingMessage() {
         if (thinkingMessageId) {
-            send({ type: 'THINKING_TEXT_MESSAGE_END', messageId: thinkingMessageId });
-            send({ type: 'THINKING_END' });
+            await send({
+                type: 'THINKING_TEXT_MESSAGE_END',
+                messageId: thinkingMessageId,
+            });
+            await send({ type: 'THINKING_END' });
             thinkingMessageId = null;
         }
     }
-    function endStep() {
+    async function endStep() {
         if (openStepName) {
-            send({ type: 'STEP_FINISHED', stepName: openStepName });
+            await send({ type: 'STEP_FINISHED', stepName: openStepName });
             openStepName = null;
         }
     }
-    function ensureTextMessage() {
+    async function ensureTextMessage() {
         if (!textMessageId) {
             textMessageId = randomUUID();
-            send({ type: 'TEXT_MESSAGE_START', messageId: textMessageId });
+            await send({ type: 'TEXT_MESSAGE_START', messageId: textMessageId });
         }
         return textMessageId;
     }
-    function ensureThinkingMessage() {
+    async function ensureThinkingMessage() {
         if (!thinkingMessageId) {
             thinkingMessageId = randomUUID();
-            send({ type: 'THINKING_START' });
-            send({
+            await send({ type: 'THINKING_START' });
+            await send({
                 type: 'THINKING_TEXT_MESSAGE_START',
                 messageId: thinkingMessageId,
             });
         }
         return thinkingMessageId;
     }
-    function finishRun() {
-        endTextMessage();
-        endThinkingMessage();
-        endStep();
-        send({
+    async function finishRun() {
+        await endTextMessage();
+        await endThinkingMessage();
+        await endStep();
+        await send({
             type: 'RUN_FINISHED',
             threadId,
             runId: resolveRunId(),
@@ -110,14 +113,14 @@ export function wrapChannelWithAGUI(inner, options) {
         remote: (funcName, data) => inner.remote(funcName, data),
         sendBinary: (data) => inner.sendBinary(data),
         close: () => inner.close(),
-        send: (event) => {
+        send: async (event) => {
             if (terminal)
                 return;
             switch (event.type) {
                 case 'text-delta': {
-                    endThinkingMessage();
-                    const id = ensureTextMessage();
-                    send({
+                    await endThinkingMessage();
+                    const id = await ensureTextMessage();
+                    await send({
                         type: 'TEXT_MESSAGE_CONTENT',
                         messageId: id,
                         delta: event.text,
@@ -125,9 +128,9 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'reasoning-delta': {
-                    endTextMessage();
-                    const id = ensureThinkingMessage();
-                    send({
+                    await endTextMessage();
+                    const id = await ensureThinkingMessage();
+                    await send({
                         type: 'THINKING_TEXT_MESSAGE_CONTENT',
                         messageId: id,
                         delta: event.text,
@@ -135,19 +138,19 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'tool-call': {
-                    endTextMessage();
-                    endThinkingMessage();
-                    send({
+                    await endTextMessage();
+                    await endThinkingMessage();
+                    await send({
                         type: 'TOOL_CALL_START',
                         toolCallId: event.toolCallId,
                         toolCallName: event.toolName,
                     });
-                    send({
+                    await send({
                         type: 'TOOL_CALL_ARGS',
                         toolCallId: event.toolCallId,
                         delta: resultToString(event.args) || '{}',
                     });
-                    send({
+                    await send({
                         type: 'TOOL_CALL_END',
                         toolCallId: event.toolCallId,
                         toolCallName: event.toolName,
@@ -155,7 +158,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'tool-result': {
-                    send({
+                    await send({
                         type: 'TOOL_CALL_RESULT',
                         messageId: randomUUID(),
                         toolCallId: event.toolCallId,
@@ -165,8 +168,8 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'usage': {
-                    endTextMessage();
-                    endThinkingMessage();
+                    await endTextMessage();
+                    await endThinkingMessage();
                     sawUsage = true;
                     usageTotals.input += event.tokens.input;
                     usageTotals.output += event.tokens.output;
@@ -175,30 +178,30 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'error': {
-                    endTextMessage();
-                    endThinkingMessage();
-                    endStep();
-                    send({ type: 'RUN_ERROR', message: event.message });
+                    await endTextMessage();
+                    await endThinkingMessage();
+                    await endStep();
+                    await send({ type: 'RUN_ERROR', message: event.message });
                     terminal = true;
                     break;
                 }
                 case 'done': {
-                    finishRun();
+                    await finishRun();
                     break;
                 }
                 case 'step-start': {
-                    endTextMessage();
-                    endThinkingMessage();
-                    endStep();
+                    await endTextMessage();
+                    await endThinkingMessage();
+                    await endStep();
                     stepSeq += 1;
                     openStepName = `${event.agent ?? 'step'}#${stepSeq}`;
-                    send({ type: 'STEP_STARTED', stepName: openStepName });
+                    await send({ type: 'STEP_STARTED', stepName: openStepName });
                     break;
                 }
                 case 'approval-request': {
-                    endTextMessage();
-                    endThinkingMessage();
-                    send({
+                    await endTextMessage();
+                    await endThinkingMessage();
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:approval-request',
                         value: {
@@ -214,9 +217,9 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'credential-request': {
-                    endTextMessage();
-                    endThinkingMessage();
-                    send({
+                    await endTextMessage();
+                    await endThinkingMessage();
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:credential-request',
                         value: {
@@ -234,7 +237,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'generative-ui': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:generative-ui',
                         value: { spec: event.spec },
@@ -242,7 +245,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'data': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:data',
                         value: { name: event.name, data: event.data },
@@ -250,7 +253,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'agent-call': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:agent-call',
                         value: {
@@ -262,7 +265,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'agent-result': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:agent-result',
                         value: {
@@ -274,7 +277,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'suspended': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:suspended',
                         value: { reason: event.reason, missingRpcs: event.missingRpcs },
@@ -282,10 +285,10 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'interrupted': {
-                    endTextMessage();
-                    endThinkingMessage();
-                    endStep();
-                    send({
+                    await endTextMessage();
+                    await endThinkingMessage();
+                    await endStep();
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:interrupted',
                         value: {
@@ -298,7 +301,7 @@ export function wrapChannelWithAGUI(inner, options) {
                 }
                 // knowledge: decisions/internals/agent-speech-travels-as-a-custom-agui-event.md
                 case 'audio-delta': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:audio-delta',
                         value: {
@@ -310,11 +313,11 @@ export function wrapChannelWithAGUI(inner, options) {
                     break;
                 }
                 case 'audio-done': {
-                    send({ type: 'CUSTOM', name: 'pikku:audio-done', value: {} });
+                    await send({ type: 'CUSTOM', name: 'pikku:audio-done', value: {} });
                     break;
                 }
                 case 'transcript': {
-                    send({
+                    await send({
                         type: 'CUSTOM',
                         name: 'pikku:transcript',
                         value: { text: event.text },

package/dist/wirings/agent/agent-interrupt.d.ts

@@ -1,3 +1,4 @@
+import { type AbortScope } from '../../function/abort-scope.js';
 import type { AgentStorageService } from '../../services/agent-storage-service.js';
 /**
  * Why an in-flight agent run was cut short.
@@ -126,7 +127,9 @@ export declare const getInFlightTools: (runId: string) => string[];
 export declare const trackToolExecution: <T extends {
     name: string;
     readonly?: boolean;
-    execute: (input: any) => Promise<any>;
+    execute: (input: any, options?: {
+        abortScope?: AbortScope;
+    }) => Promise<any>;
 }>(tools: T[], handle: InterruptibleRunHandle) => T[];
 export declare const trackInterruptNote: (threadId: string, write: Promise<void>) => void;
 /** Await an interrupted tool result still being written to this thread. */

package/dist/wirings/agent/agent-interrupt.js

@@ -1,5 +1,5 @@
 import { randomUUID } from './agent-utils.js';
-import { AbandonedError, runInAbortScope, } from '../../function/abort-scope.js';
+import { AbandonedError } from '../../function/abort-scope.js';
 /**
  * Thrown out of the step loop when a run is interrupted, so an interruption is
  * distinguishable from a genuine failure at the one `catch` that would
@@ -162,7 +162,7 @@ export const trackToolExecution = (tools, handle) => tools.map((tool) => {
     }
     return {
         ...tool,
-        execute: (input) => {
+        execute: (input, options) => {
             // Assumed to have changed something unless it says otherwise — the tool
             // that never declares its checkpoint is the one that cannot be assumed
             // harmless. `beginChanges()` can only ever make this more precise.
@@ -178,7 +178,7 @@ export const trackToolExecution = (tools, handle) => tools.map((tool) => {
                     call.mutating = true;
                 },
             };
-            return handle.trackTool(tool.name, randomUUID(), () => runInAbortScope(scope, () => tool.execute(input)), {
+            return handle.trackTool(tool.name, randomUUID(), () => tool.execute(input, { ...options, abortScope: scope }), {
                 get collectResult() {
                     return call.mutating;
                 },

package/dist/wirings/agent/agent-memory.js

@@ -1,4 +1,3 @@
-import { randomUUID } from 'crypto';
 export function resolveMemoryServices(agent, singletonServices) {
     const memoryConfig = agent.memory;
     const storage = memoryConfig?.storage
@@ -83,7 +82,7 @@ export async function loadContextMessages(memoryConfig, storage, input, workingM
         const workingMem = await workingMemoryStorage.getWorkingMemory(input.threadId, 'thread');
         const prompt = buildWorkingMemoryPrompt(workingMem, workingMemoryJsonSchema);
         contextMessages.push({
-            id: `wm-${randomUUID()}`,
+            id: `wm-${globalThis.crypto.randomUUID()}`,
             role: 'system',
             content: prompt,
             createdAt: new Date(),
@@ -99,9 +98,9 @@ export async function saveMessages(storage, threadId, resourceId, memoryConfig,
         const newMessages = userMessage ? [userMessage] : [];
         for (const step of result.steps) {
             if (step.toolCalls?.length) {
-                const toolCallIds = step.toolCalls.map(() => randomUUID());
+                const toolCallIds = step.toolCalls.map(() => globalThis.crypto.randomUUID());
                 newMessages.push({
-                    id: randomUUID(),
+                    id: globalThis.crypto.randomUUID(),
                     role: 'assistant',
                     toolCalls: step.toolCalls.map((tc, i) => ({
                         id: toolCallIds[i],
@@ -111,7 +110,7 @@ export async function saveMessages(storage, threadId, resourceId, memoryConfig,
                     createdAt: new Date(),
                 });
                 newMessages.push({
-                    id: randomUUID(),
+                    id: globalThis.crypto.randomUUID(),
                     role: 'tool',
                     toolResults: step.toolCalls.map((tc, i) => ({
                         id: toolCallIds[i],
@@ -132,7 +131,7 @@ export async function saveMessages(storage, threadId, resourceId, memoryConfig,
             ]
             : responseText;
         newMessages.push({
-            id: randomUUID(),
+            id: globalThis.crypto.randomUUID(),
             role: 'assistant',
             content: assistantContent || undefined,
             createdAt: new Date(),

package/dist/wirings/agent/agent-model-config.js

@@ -1,9 +1,10 @@
 // knowledge: decisions/internals/agent-model-config-stays-a-single-resolution-seam.md
 import { pikkuState } from '../../pikku-state.js';
+import { readEnvVariable } from '../../env.js';
 const isProviderQualified = (model) => model.includes('/');
 /** `PIKKU_MODEL_ALIASES=cheap:openai/gpt-5-mini,tool:anthropic/claude-sonnet-5` */
 const envAliases = () => {
-    const raw = process.env.PIKKU_MODEL_ALIASES;
+    const raw = readEnvVariable('PIKKU_MODEL_ALIASES');
     if (!raw)
         return {};
     const aliases = {};

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

@@ -247,7 +247,7 @@ export function createScopedChannel(parent, agentName, session) {
         },
         close: () => { },
         sendBinary: (data) => parent.sendBinary(data),
-        send: (event) => {
+        send: async (event) => {
             if (event.type === 'done')
                 return;
             if (event.type === 'approval-request') {
@@ -267,10 +267,14 @@ export function createScopedChannel(parent, agentName, session) {
                 event.type === 'tool-result' ||
                 event.type === 'usage' ||
                 event.type === 'error') {
-                parent.send({ ...event, agent: agentName, session });
+                await parent.send({
+                    ...event,
+                    agent: agentName,
+                    session,
+                });
             }
             else {
-                parent.send(event);
+                await parent.send(event);
             }
         },
         setState: (s) => parent.setState(s),
@@ -385,6 +389,9 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     credentialGrants: capturedAddonConfig?.credentialGrants,
                                     globalSecrets: capturedAddonConfig?.globalSecrets,
                                     globalCredentials: capturedAddonConfig?.globalCredentials,
+                                    contentBucket: capturedAddonConfig?.contentBucket,
+                                    contentGrants: capturedAddonConfig?.contentGrants,
+                                    globalContent: capturedAddonConfig?.globalContent,
                                 }
                                 : undefined;
                             services = await getOrCreatePackageSingletonServices(capturedPkg, singletonServices, addonInstance);
@@ -402,10 +409,12 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 needsApproval: needsApproval || undefined,
                 approvalDescriptionFn,
                 readonly: fnMeta?.readonly || undefined,
-                execute: async (toolInput) => {
+                execute: async (toolInput, options) => {
                     const wire = params.sessionService
                         ? { ...createMiddlewareSessionWireProps(params.sessionService) }
                         : {};
+                    if (options?.abortScope)
+                        wire.abortScope = options.abortScope;
                     const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
                     return rpcService.rpc(toolName, toolInput);
                 },
@@ -457,7 +466,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                             streamContext.delegateState.delegated = true;
                         }
                         const { channel } = streamContext;
-                        channel.send({
+                        await channel.send({
                             type: 'agent-call',
                             agentName: subAgentName,
                             session,
@@ -468,11 +477,11 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                             ? subChannel
                             : {
                                 ...subChannel,
-                                send: (event) => {
+                                send: async (event) => {
                                     if (event.type === 'text-delta' ||
                                         event.type === 'reasoning-delta')
                                         return;
-                                    subChannel.send(event);
+                                    await subChannel.send(event);
                                 },
                             };
                         const resultText = await streamAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
@@ -486,7 +495,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                 subApprovals: subChannel.approvals,
                             };
                         }
-                        channel.send({
+                        await channel.send({
                             type: 'agent-result',
                             agentName: subAgentName,
                             session,
@@ -544,7 +553,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 name: workflowName,
                 description: wfMeta.description || workflowName,
                 inputSchema,
-                execute: async (toolInput) => {
+                execute: async (toolInput, options) => {
                     const workflowService = singletonServices.workflowService;
                     if (!workflowService) {
                         throw new Error(`workflowService is not configured — cannot run workflow tool '${workflowName}'`);
@@ -552,6 +561,8 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                     const wire = params.sessionService
                         ? { ...createMiddlewareSessionWireProps(params.sessionService) }
                         : {};
+                    if (options?.abortScope)
+                        wire.abortScope = options.abortScope;
                     const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
                     return workflowService.runToCompletion(workflowName, toolInput, rpcService, { wire: { type: 'internal' } });
                 },
@@ -560,9 +571,9 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
     }
     for (const tool of tools) {
         const originalExecute = tool.execute;
-        tool.execute = async (toolInput) => {
+        tool.execute = async (toolInput, options) => {
             try {
-                return await originalExecute(toolInput);
+                return await originalExecute(toolInput, options);
             }
             catch (err) {
                 if (err?.payload?.error === 'missing_credential') {
@@ -581,7 +592,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
     if (hasToolHooks) {
         for (const tool of tools) {
             const originalExecute = tool.execute;
-            tool.execute = async (toolInput) => {
+            tool.execute = async (toolInput, options) => {
                 const toolCallId = randomUUID();
                 let args = (toolInput ?? {});
                 for (const mw of agentMiddlewares) {
@@ -600,7 +611,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 let result;
                 let execError;
                 try {
-                    result = await originalExecute(args);
+                    result = await originalExecute(args, options);
                 }
                 catch (err) {
                     execError = err;