@pikku/core 0.12.63 → 0.12.66

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

@@ -0,0 +1,305 @@
+import { randomUUID } from './ai-agent-utils.js';
+function resultToString(result) {
+    if (typeof result === 'string')
+        return result;
+    try {
+        return JSON.stringify(result, (_key, val) => typeof val === 'bigint' ? val.toString() : val);
+    }
+    catch {
+        return String(result);
+    }
+}
+export function wrapChannelWithAGUI(inner, options) {
+    const threadId = options?.threadId ?? randomUUID();
+    let runId = options?.runId ?? null;
+    function resolveRunId() {
+        if (!runId) {
+            runId = options?.getRunId?.() ?? randomUUID();
+        }
+        return runId;
+    }
+    let textMessageId = null;
+    let thinkingMessageId = null;
+    let openStepName = null;
+    let stepSeq = 0;
+    let runStartedSent = false;
+    let terminal = false;
+    let sawUsage = false;
+    let usageModel;
+    const usageTotals = { input: 0, output: 0 };
+    // The AG-UI client rejects any event arriving before RUN_STARTED, so the
+    // run is opened lazily with the first translated event.
+    function send(event) {
+        if (!runStartedSent) {
+            runStartedSent = true;
+            inner.send({
+                type: 'RUN_STARTED',
+                threadId,
+                runId: resolveRunId(),
+            });
+        }
+        inner.send(event);
+    }
+    function endTextMessage() {
+        if (textMessageId) {
+            send({ type: 'TEXT_MESSAGE_END', messageId: textMessageId });
+            textMessageId = null;
+        }
+    }
+    function endThinkingMessage() {
+        if (thinkingMessageId) {
+            send({ type: 'THINKING_TEXT_MESSAGE_END', messageId: thinkingMessageId });
+            send({ type: 'THINKING_END' });
+            thinkingMessageId = null;
+        }
+    }
+    function endStep() {
+        if (openStepName) {
+            send({ type: 'STEP_FINISHED', stepName: openStepName });
+            openStepName = null;
+        }
+    }
+    function ensureTextMessage() {
+        if (!textMessageId) {
+            textMessageId = randomUUID();
+            send({ type: 'TEXT_MESSAGE_START', messageId: textMessageId });
+        }
+        return textMessageId;
+    }
+    function ensureThinkingMessage() {
+        if (!thinkingMessageId) {
+            thinkingMessageId = randomUUID();
+            send({ type: 'THINKING_START' });
+            send({
+                type: 'THINKING_TEXT_MESSAGE_START',
+                messageId: thinkingMessageId,
+            });
+        }
+        return thinkingMessageId;
+    }
+    // The AG-UI client treats RUN_FINISHED as terminal and rejects everything
+    // after it, so it is emitted exactly once — on 'done' — with the usage
+    // accumulated across all steps (per-step 'usage' events must NOT finish
+    // the run: on multi-step tool runs later steps would arrive after
+    // RUN_FINISHED and the client would drop the whole stream).
+    function finishRun() {
+        endTextMessage();
+        endThinkingMessage();
+        endStep();
+        send({
+            type: 'RUN_FINISHED',
+            threadId,
+            runId: resolveRunId(),
+            ...(usageModel ? { model: usageModel } : {}),
+            ...(sawUsage
+                ? {
+                    usage: {
+                        promptTokens: usageTotals.input,
+                        completionTokens: usageTotals.output,
+                        totalTokens: usageTotals.input + usageTotals.output,
+                    },
+                }
+                : {}),
+        });
+        terminal = true;
+    }
+    return {
+        channelId: inner.channelId,
+        openingData: inner.openingData,
+        get state() {
+            return inner.state;
+        },
+        setState: (s) => inner.setState(s),
+        getState: () => inner.getState(),
+        clearState: () => inner.clearState(),
+        sendBinary: (data) => inner.sendBinary(data),
+        close: () => inner.close(),
+        send: (event) => {
+            if (terminal)
+                return;
+            switch (event.type) {
+                case 'text-delta': {
+                    endThinkingMessage();
+                    const id = ensureTextMessage();
+                    send({
+                        type: 'TEXT_MESSAGE_CONTENT',
+                        messageId: id,
+                        delta: event.text,
+                    });
+                    break;
+                }
+                case 'reasoning-delta': {
+                    endTextMessage();
+                    const id = ensureThinkingMessage();
+                    send({
+                        type: 'THINKING_TEXT_MESSAGE_CONTENT',
+                        messageId: id,
+                        delta: event.text,
+                    });
+                    break;
+                }
+                case 'tool-call': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'TOOL_CALL_START',
+                        toolCallId: event.toolCallId,
+                        toolCallName: event.toolName,
+                    });
+                    send({
+                        type: 'TOOL_CALL_ARGS',
+                        toolCallId: event.toolCallId,
+                        delta: resultToString(event.args) || '{}',
+                    });
+                    send({
+                        type: 'TOOL_CALL_END',
+                        toolCallId: event.toolCallId,
+                        toolCallName: event.toolName,
+                    });
+                    break;
+                }
+                case 'tool-result': {
+                    send({
+                        type: 'TOOL_CALL_RESULT',
+                        messageId: randomUUID(),
+                        toolCallId: event.toolCallId,
+                        role: 'tool',
+                        content: resultToString(event.result),
+                    });
+                    break;
+                }
+                case 'usage': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    sawUsage = true;
+                    usageTotals.input += event.tokens.input;
+                    usageTotals.output += event.tokens.output;
+                    if (event.model)
+                        usageModel = event.model;
+                    break;
+                }
+                case 'error': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    send({ type: 'RUN_ERROR', message: event.message });
+                    terminal = true;
+                    break;
+                }
+                case 'done': {
+                    finishRun();
+                    break;
+                }
+                // Step names must be unique among active steps on the client and
+                // sub-agents reuse step numbers on the shared channel, so each
+                // step-start closes the previous step and gets a sequential name.
+                case 'step-start': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    stepSeq += 1;
+                    openStepName = `${event.agent ?? 'step'}#${stepSeq}`;
+                    send({ type: 'STEP_STARTED', stepName: openStepName });
+                    break;
+                }
+                case 'approval-request': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:approval-request',
+                        value: {
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            reason: event.reason,
+                            runId: event.runId,
+                            agent: event.agent,
+                            session: event.session,
+                        },
+                    });
+                    break;
+                }
+                case 'credential-request': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:credential-request',
+                        value: {
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            credentialName: event.credentialName,
+                            credentialType: event.credentialType,
+                            connectUrl: event.connectUrl,
+                            runId: event.runId,
+                            agent: event.agent,
+                            session: event.session,
+                        },
+                    });
+                    break;
+                }
+                case 'generative-ui': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:generative-ui',
+                        value: { spec: event.spec },
+                    });
+                    break;
+                }
+                case 'data': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:data',
+                        value: { name: event.name, data: event.data },
+                    });
+                    break;
+                }
+                case 'workflow-created': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:workflow-created',
+                        value: { workflowName: event.workflowName, graph: event.graph },
+                    });
+                    break;
+                }
+                case 'agent-call': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:agent-call',
+                        value: {
+                            agentName: event.agentName,
+                            session: event.session,
+                            input: event.input,
+                        },
+                    });
+                    break;
+                }
+                case 'agent-result': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:agent-result',
+                        value: {
+                            agentName: event.agentName,
+                            session: event.session,
+                            result: event.result,
+                        },
+                    });
+                    break;
+                }
+                case 'suspended': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:suspended',
+                        value: { reason: event.reason, missingRpcs: event.missingRpcs },
+                    });
+                    break;
+                }
+                case 'audio-delta':
+                case 'audio-done':
+                    break;
+            }
+        },
+    };
+}

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

@@ -1,5 +1,5 @@
 import type { CoreUserSession } from '../../types/core.types.js';
-import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel, PikkuAIMiddlewareHooks } from './ai-agent.types.js';
+import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel, PikkuAIMiddlewareHooks, SessionScope } from './ai-agent.types.js';
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { SessionService } from '../../services/user-session-service.js';
@@ -8,9 +8,91 @@ export type RunAIAgentParams = {
     /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
     getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>;
 };
+/**
+ * The ownership key for a thread/run: the trusted principal (the authenticated
+ * `session.userId` for `'user'` scope, or `session.orgId` for `'org'` scope)
+ * composed with the client-supplied `resourceId` as a sub-partition —
+ * `principal:resourceId`. Because the principal is always the prefix, a client
+ * `resourceId` can sub-divide within the caller's own boundary but can never
+ * widen access to another user's or org's threads.
+ *
+ * Idempotent: a value that is already within the caller's namespace (top-level
+ * re-entry, sub-agent recursion, or resume, which all pass an already-composite
+ * `resourceId`) is returned unchanged rather than double-composed.
+ *
+ * `'org'` scope with no session org throws {@link ForbiddenError} — falling back
+ * to a bare/shared key would leak across organizations. Sessionless `'user'`
+ * wirings have no trusted principal and fall back to the requested `resourceId`
+ * as a best-effort partition key.
+ */
+export declare function resolveOwnerResourceId(params: RunAIAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
+/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export declare function agentSessionScope(agentName: string): SessionScope;
+/**
+ * Enforce that a stored thread/run belongs to the caller's owner resource,
+ * throwing {@link ForbiddenError} (without echoing the id, to avoid an
+ * 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;
+    /**
+     * Invoked as soon as the run's AIRunStateService id exists, so transport
+     * wrappers (e.g. the AG-UI bridge) can stamp the real runId on RUN_STARTED.
+     */
+    onRunCreated?: (runId: string) => void;
 };
+/**
+ * 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
+ * sub-agent's LLM-shaped `result.object` — plain JSON — cannot carry a Symbol,
+ * so `checkForApprovals` trusts the brand rather than the `__approvalRequired`
+ * string key to decide an approval must be surfaced.
+ */
+export declare const APPROVAL_REQUIRED: unique symbol;
 export declare class ToolApprovalRequired extends PikkuError {
     readonly toolCallId: string;
     readonly toolName: string;
@@ -54,12 +136,34 @@ 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<{
         toolCallId: string;
         toolName: string;
         args: unknown;
+        reason?: string;
         runId: string;
     }>;
 };