@pikku/core 0.12.78 → 0.12.80

package/dist/types/core.types.d.ts

@@ -233,6 +233,11 @@ export interface CoreUserSession {
      * Populated by whoever builds the session — core reads them, never fetches.
      */
     scopes?: string[];
+    /**
+     * Restricts the session to functions declared `readonly`. The function runner
+     * throws `ReadonlySessionError` for anything else.
+     */
+    readonly?: boolean;
 }
 /**
  * Kept structural so core stays independent of any one auth package —
@@ -299,12 +304,17 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      */
     auth?: () => Promise<AuthInstance>;
 }
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
 } & Partial<{
     wireType: PikkuWiringTypes;
     wireId: string;
+    /**
+     * A logger scoped to this invocation, when a host attaches one. Core never
+     * sets it; services that log fall back to the singleton logger.
+     */
+    logger: Logger;
     /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
     traceId: string;
     functionId: string;

package/dist/types/state.types.d.ts

@@ -63,7 +63,7 @@ export interface PikkuPackageState {
         meta: HTTPWiringsMeta;
     };
     channel: {
-        channels: Map<string, CoreChannel<any, any>>;
+        channels: Map<string, CoreChannel<any, any, any, any, any>>;
         meta: ChannelsMeta;
     };
     scheduler: {

package/dist/utils/node-host-resolver.d.ts

@@ -0,0 +1,12 @@
+import { type HostResolver } from './safe-fetch.js';
+/**
+ * Resolves a hostname through the platform resolver, returning every address it
+ * points at so `safeFetch` can reject a public name aimed at an internal one.
+ *
+ * This module is Node-only and is never imported by core itself — Workers has no
+ * DNS API, and a static `node:dns` import in the shared path would break that
+ * build.
+ */
+export declare const nodeHostResolver: HostResolver;
+/** Installs {@link nodeHostResolver} as the default for every `safeFetch`. */
+export declare const installNodeHostResolver: () => void;

package/dist/utils/node-host-resolver.js

@@ -0,0 +1,16 @@
+import { lookup } from 'node:dns/promises';
+import { setDefaultHostResolver } from './safe-fetch.js';
+/**
+ * Resolves a hostname through the platform resolver, returning every address it
+ * points at so `safeFetch` can reject a public name aimed at an internal one.
+ *
+ * This module is Node-only and is never imported by core itself — Workers has no
+ * DNS API, and a static `node:dns` import in the shared path would break that
+ * build.
+ */
+export const nodeHostResolver = async (hostname) => {
+    const results = await lookup(hostname, { all: true, verbatim: true });
+    return results.map(({ address }) => address);
+};
+/** Installs {@link nodeHostResolver} as the default for every `safeFetch`. */
+export const installNodeHostResolver = () => setDefaultHostResolver(nodeHostResolver);

package/dist/utils/safe-fetch.d.ts

@@ -4,6 +4,18 @@
  * private IP.
  */
 export declare function isPrivateHost(hostname: string): boolean;
+/** Resolves a hostname to the IP addresses it points at. */
+export type HostResolver = (hostname: string) => Promise<string[]>;
+/**
+ * Installs the resolver {@link safeFetch} uses when a call passes no
+ * `resolveHost` of its own.
+ *
+ * Core cannot resolve DNS itself — Workers has no DNS API — so without a
+ * resolver the guard is literal-only and a public name pointing at
+ * `169.254.169.254` passes. Node runtimes install
+ * `nodeHostResolver` from `@pikku/core/node-host-resolver` at startup.
+ */
+export declare function setDefaultHostResolver(resolver: HostResolver | undefined): void;
 export interface SafeFetchOptions {
     /**
      * When set, the host of every hop must appear in this allowlist. When omitted,
@@ -12,6 +24,12 @@ export interface SafeFetchOptions {
     allowedHosts?: string[];
     /** Maximum redirect hops to follow (each re-validated). Defaults to 3. */
     maxRedirects?: number;
+    /**
+     * Resolves a hostname so a *public* name pointing at a private address is
+     * refused. Defaults to whatever {@link setDefaultHostResolver} installed;
+     * pass `null` to opt a call out of resolution entirely.
+     */
+    resolveHost?: HostResolver | null;
 }
 export declare function assertFetchableUrl(url: string, options?: SafeFetchOptions): URL;
 /**

package/dist/utils/safe-fetch.js

@@ -34,6 +34,120 @@ function parseIPv4Octets(host) {
     }
     return octets;
 }
+/**
+ * IPv4 blocks that must never be reachable from user-supplied URLs: private,
+ * loopback, link-local (cloud metadata), carrier-grade NAT (Alibaba's
+ * `100.100.100.200` metadata endpoint), IETF protocol assignments, benchmarking,
+ * 6to4 anycast, the documentation TEST-NETs, multicast and reserved space.
+ */
+const PRIVATE_IPV4_BLOCKS = [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.88.99.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+];
+const toUint32 = (octets) => ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+const PRIVATE_IPV4_RANGES = PRIVATE_IPV4_BLOCKS.map(([base, prefix]) => {
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    return [(toUint32(parseIPv4Octets(base)) & mask) >>> 0, mask];
+});
+const isPrivateIPv4 = (octets) => {
+    const addr = toUint32(octets);
+    return PRIVATE_IPV4_RANGES.some(([base, mask]) => (addr & mask) >>> 0 === base);
+};
+/**
+ * Expands an IPv6 literal into its eight 16-bit groups, handling `::` elision
+ * and a trailing dotted-quad. `null` when not a well-formed IPv6 literal.
+ */
+function parseIPv6Groups(host) {
+    const zoneless = host.split('%')[0];
+    const halves = zoneless.split('::');
+    if (halves.length > 2)
+        return null;
+    const parseSide = (side) => {
+        if (side === '')
+            return [];
+        const parts = side.split(':');
+        const groups = [];
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (i === parts.length - 1 && part.includes('.')) {
+                const v4 = parseIPv4Octets(part);
+                if (!v4)
+                    return null;
+                groups.push((v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]);
+                continue;
+            }
+            if (!/^[0-9a-f]{1,4}$/.test(part))
+                return null;
+            groups.push(parseInt(part, 16));
+        }
+        return groups;
+    };
+    const head = parseSide(halves[0]);
+    if (head === null)
+        return null;
+    if (halves.length === 1) {
+        return head.length === 8 ? head : null;
+    }
+    const tail = parseSide(halves[1]);
+    if (tail === null)
+        return null;
+    if (head.length + tail.length > 7)
+        return null;
+    return [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+}
+const embeddedIPv4 = (hi, lo) => [
+    (hi >> 8) & 0xff,
+    hi & 0xff,
+    (lo >> 8) & 0xff,
+    lo & 0xff,
+];
+function isPrivateIPv6(groups) {
+    const [g0, g1, g2, g3, g4, g5, g6, g7] = groups;
+    if (groups.every((g) => g === 0))
+        return true; // :: unspecified
+    if (groups.slice(0, 7).every((g) => g === 0) && g7 === 1)
+        return true; // ::1
+    // IPv4-mapped ::ffff:0:0/96 and IPv4-compatible ::/96
+    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0) {
+        if (g5 === 0xffff || g5 === 0)
+            return isPrivateIPv4(embeddedIPv4(g6, g7));
+    }
+    // NAT64 well-known prefix 64:ff9b::/96
+    if (g0 === 0x64 &&
+        g1 === 0xff9b &&
+        g2 === 0 &&
+        g3 === 0 &&
+        g4 === 0 &&
+        g5 === 0)
+        return isPrivateIPv4(embeddedIPv4(g6, g7));
+    // 6to4 2002::/16 carries the IPv4 address in the next 32 bits
+    if (g0 === 0x2002)
+        return isPrivateIPv4(embeddedIPv4(g1, g2));
+    if (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0)
+        return true; // discard-only 100::/64
+    if ((g0 & 0xffc0) === 0xfe80)
+        return true; // link-local fe80::/10
+    if ((g0 & 0xfe00) === 0xfc00)
+        return true; // unique-local fc00::/7
+    if ((g0 & 0xffc0) === 0xfec0)
+        return true; // deprecated site-local fec0::/10
+    if ((g0 & 0xff00) === 0xff00)
+        return true; // multicast ff00::/8
+    return false;
+}
 /**
  * Whether a hostname is an obvious internal target. Best-effort literal
  * matching only: it cannot catch a public hostname that *resolves* to a
@@ -47,36 +161,56 @@ export function isPrivateHost(hostname) {
     if (host === '' || host === 'localhost' || host.endsWith('.localhost'))
         return true;
     if (host.includes(':')) {
-        if (host === '::' || host === '::1')
-            return true;
-        const mappedV4 = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-        if (mappedV4)
-            return isPrivateHost(mappedV4[1]);
-        const mappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-        if (mappedHex) {
-            const hi = parseInt(mappedHex[1], 16);
-            const lo = parseInt(mappedHex[2], 16);
-            return isPrivateHost(`${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`);
-        }
-        if (/^fe[89ab]/.test(host))
-            return true; // link-local fe80::/10
-        if (host.startsWith('fc') || host.startsWith('fd'))
-            return true; // unique-local fc00::/7
-        return false;
+        const groups = parseIPv6Groups(host);
+        return groups ? isPrivateIPv6(groups) : false;
     }
     const v4 = parseIPv4Octets(host);
-    if (v4) {
-        const [a, b] = v4;
-        if (a === 127 || a === 10 || a === 0)
-            return true;
-        if (a === 169 && b === 254)
-            return true; // link-local incl. cloud metadata
-        if (a === 172 && b >= 16 && b <= 31)
-            return true;
-        if (a === 192 && b === 168)
-            return true;
+    return v4 ? isPrivateIPv4(v4) : false;
+}
+let defaultHostResolver;
+/**
+ * Installs the resolver {@link safeFetch} uses when a call passes no
+ * `resolveHost` of its own.
+ *
+ * Core cannot resolve DNS itself — Workers has no DNS API — so without a
+ * resolver the guard is literal-only and a public name pointing at
+ * `169.254.169.254` passes. Node runtimes install
+ * `nodeHostResolver` from `@pikku/core/node-host-resolver` at startup.
+ */
+export function setDefaultHostResolver(resolver) {
+    defaultHostResolver = resolver;
+}
+/** Whether a hostname is already an IP literal, which the sync check covers. */
+function isIpLiteral(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    if (host.includes(':'))
+        return parseIPv6Groups(host.toLowerCase()) !== null;
+    return parseIPv4Octets(host) !== null;
+}
+/**
+ * Rejects a hostname that resolves to an internal address.
+ *
+ * Resolution happens once per hop and the connection is not pinned to the
+ * address checked, so a rebind between this check and the socket connecting is
+ * still possible; catching that needs a runtime-level connect hook.
+ */
+async function assertResolvedHostAllowed(hostname, options) {
+    if (options.allowedHosts)
+        return;
+    const resolver = options.resolveHost === null
+        ? undefined
+        : (options.resolveHost ?? defaultHostResolver);
+    if (!resolver || isIpLiteral(hostname))
+        return;
+    const addresses = await resolver(hostname);
+    if (addresses.length === 0) {
+        throw new Error(`Refusing to fetch: '${hostname}' resolved to no addresses`);
+    }
+    for (const address of addresses) {
+        if (isPrivateHost(address)) {
+            throw new Error(`Refusing to fetch from a private/internal host: '${hostname}' resolves to ${address}`);
+        }
     }
-    return false;
 }
 export function assertFetchableUrl(url, options = {}) {
     const parsed = new URL(url);
@@ -126,7 +260,9 @@ function redirectInit(status, init) {
  */
 export async function safeFetch(url, init = {}, options = {}) {
     const maxRedirects = options.maxRedirects ?? 3;
-    let currentUrl = assertFetchableUrl(url, options).toString();
+    const initial = assertFetchableUrl(url, options);
+    await assertResolvedHostAllowed(initial.hostname, options);
+    let currentUrl = initial.toString();
     let currentInit = init;
     for (let hop = 0;; hop++) {
         const response = await fetch(currentUrl, {
@@ -140,7 +276,9 @@ export async function safeFetch(url, init = {}, options = {}) {
         if (!location || hop >= maxRedirects) {
             return response;
         }
-        const nextUrl = assertFetchableUrl(new URL(location, currentUrl).toString(), options).toString();
+        const next = assertFetchableUrl(new URL(location, currentUrl).toString(), options);
+        await assertResolvedHostAllowed(next.hostname, options);
+        const nextUrl = next.toString();
         await response.body?.cancel();
         let nextInit = redirectInit(response.status, currentInit);
         if (new URL(nextUrl).origin !== new URL(currentUrl).origin) {

package/dist/wirings/actor-flow/run-conversation.js

@@ -70,12 +70,7 @@ function actorInstructions(persona, task) {
             : '',
         `Your goal in this conversation: ${task}.`,
         `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
-        // Every call the actor makes wants a schema'd object back, and a gateway
-        // that cannot take a JSON *schema* degrades to OpenAI's `json_object`
-        // mode — which refuses the request outright unless the word "json" appears
-        // somewhere in the prompt. Saying it once here covers all three call sites
-        // (turn, approvals, verdict), since each builds on these instructions, and
-        // it costs nothing on providers that never needed telling.
+        // knowledge: decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md
         `Reply with json matching the schema you are given, and nothing else.`,
     ]
         .filter(Boolean)

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

@@ -0,0 +1,15 @@
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { SessionService } from '../../services/user-session-service.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { PikkuRPC } from '../rpc/rpc-types.js';
+export type AgentRPCOptions = {
+    sessionService?: SessionService<CoreUserSession>;
+};
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export declare const createAgentRPC: (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC["agent"];

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

@@ -0,0 +1,53 @@
+import { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
+import { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+import { wrapChannelWithAGUI } from './ai-agent-agui.js';
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export const createAgentRPC = (wire, options) => {
+    const params = () => ({
+        sessionService: options.sessionService,
+        getCredential: wire.getCredential?.bind(wire),
+    });
+    const streamingChannel = () => {
+        const channel = wire.channel;
+        if (!channel)
+            throw new Error('No channel available for streaming');
+        return channel;
+    };
+    /** `run` and `approve` return the same shape; only the call differs. */
+    const asRunResult = (result) => ({
+        runId: result.runId,
+        result: result.object ?? result.text,
+        usage: result.usage,
+        ...(result.status === 'suspended' && {
+            status: 'suspended',
+            pendingApprovals: result.pendingApprovals,
+        }),
+    });
+    return {
+        run: async (agentName, input) => asRunResult(await runAIAgent(agentName, input, params())),
+        stream: async (agentName, input, streamOptions) => {
+            let currentRunId;
+            await streamAIAgent(agentName, input, wrapChannelWithAGUI(streamingChannel(), {
+                threadId: input.threadId,
+                getRunId: () => currentRunId,
+            }), params(), undefined, {
+                ...streamOptions,
+                onRunCreated: (runId) => {
+                    currentRunId = runId;
+                    streamOptions?.onRunCreated?.(runId);
+                },
+            });
+        },
+        resume: async (runId, input, streamOptions) => {
+            await resumeAIAgent({ runId, ...input }, wrapChannelWithAGUI(streamingChannel(), { runId }), params(), streamOptions);
+        },
+        interrupt: async (runId, reason) => interruptAIAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: options.sessionService }),
+        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAIAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
+    };
+};

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

@@ -296,11 +296,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     });
                     break;
                 }
-                // AG-UI has no event for speech, so it travels as CUSTOM like the other
-                // pikku-specific ones. Dropping it instead — which is what this did —
-                // means a voice agent reached over HTTP is inaudible: `voiceOutput`
-                // synthesizes every sentence, the provider bills for it, and nothing
-                // gets past the mapper.
+                // knowledge: decisions/internals/agent-speech-travels-as-a-custom-agui-event.md
                 case 'audio-delta': {
                     send({
                         type: 'CUSTOM',

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

@@ -2,7 +2,9 @@ import { randomUUID } from 'crypto';
 export function resolveMemoryServices(agent, singletonServices) {
     const memoryConfig = agent.memory;
     const storage = memoryConfig?.storage
-        ? singletonServices[memoryConfig.storage]
+        ? // The service is named by string in agent config, so the lookup cannot be
+            // checked — only the shape it is required to have.
+            singletonServices[memoryConfig.storage]
         : singletonServices.aiStorage;
     return { storage };
 }

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

@@ -1,5 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions, runPermissions } 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';
@@ -648,10 +648,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     }
     let messages = [];
     if (storage) {
-        // A tool whose run was interrupted may still be writing its result to this
-        // thread. In voice the next turn lands within a second or two, so without
-        // this the model would load context that is missing the very thing it is
-        // about to be asked about.
+        // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
         await awaitPendingInterruptNote(threadId);
         messages = await storage.getMessages(threadId, {
             lastN: memoryConfig?.lastMessages ?? 20,
@@ -660,10 +657,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
     const userContent = input.attachments?.length
         ? [
-            // Omitted when there is nothing to say. An attachment on its own is a
-            // real turn — a spoken one carries audio and no text at all — and an
-            // empty text part alongside it is a part providers are entitled to
-            // reject, for a caller who never wrote one.
+            // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
             ...(input.message
                 ? [{ type: 'text', text: input.message }]
                 : []),