@puku-ai/sdk 4.0.3 → 4.0.4

package/dist/vendor/lib/parser.cjs

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeParseMessage = maybeParseMessage;
+exports.parseMessage = parseMessage;
+const error_1 = require("../core/error");
+function getOutputFormat(params) {
+    return params?.output_config?.format;
+}
+function maybeParseMessage(message, params, opts) {
+    const outputFormat = getOutputFormat(params);
+    if (!params || !('parse' in (outputFormat ?? {}))) {
+        return {
+            ...message,
+            content: message.content.map((block) => {
+                if (block.type === 'text') {
+                    const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+                        value: null,
+                        enumerable: false,
+                    });
+                    return parsedBlock;
+                }
+                return block;
+            }),
+            parsed_output: null,
+        };
+    }
+    return parseMessage(message, params, opts);
+}
+function parseMessage(message, params, opts) {
+    let firstParsedOutput = null;
+    const content = message.content.map((block) => {
+        if (block.type === 'text') {
+            const parsedOutput = parseOutputFormat(params, block.text);
+            if (firstParsedOutput === null) {
+                firstParsedOutput = parsedOutput;
+            }
+            const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+                value: parsedOutput,
+                enumerable: false,
+            });
+            return parsedBlock;
+        }
+        return block;
+    });
+    return {
+        ...message,
+        content,
+        parsed_output: firstParsedOutput,
+    };
+}
+function parseOutputFormat(params, content) {
+    const outputFormat = getOutputFormat(params);
+    if (outputFormat?.type !== 'json_schema') {
+        return null;
+    }
+    try {
+        if ('parse' in outputFormat) {
+            return outputFormat.parse(content);
+        }
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new error_1.PukuError(`Failed to parse structured output: ${error}`);
+    }
+}

package/dist/vendor/lib/sessions/accumulate.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accumulateManagedAgentsEvent = accumulateManagedAgentsEvent;
+const error_1 = require("../../core/error");
+function accumulateManagedAgentsEvent(accumulated, event) {
+    switch (event.type) {
+        case 'event_start': {
+            if (event.event.type === 'agent.message') {
+                return { id: event.event.id, type: 'agent.message', content: [], processed_at: '' };
+            }
+            return accumulated;
+        }
+        case 'agent.message': {
+            return { ...event, content: event.content.map((block) => ({ ...block })) };
+        }
+        case 'event_delta': {
+            if (accumulated === undefined) {
+                throw new error_1.PukuError(`event_delta for ${event.event_id} received before its event_start`);
+            }
+            const idx = event.delta.index ?? 0;
+            const fragment = event.delta.content;
+            // Indices arrive in order — the first delta at a new index opens the slot.
+            // A gap means deltas arrived out of order or were mis-routed.
+            if (idx > accumulated.content.length) {
+                throw new error_1.PukuError(`event_delta index ${idx} is beyond the end of content (length ${accumulated.content.length})`);
+            }
+            const existing = accumulated.content[idx];
+            if (existing === undefined) {
+                // New index: pass the fragment through as a fresh block.
+                return { ...accumulated, content: [...accumulated.content, { ...fragment }] };
+            }
+            let updated = existing;
+            if (fragment.type === 'text' && existing.type === 'text') {
+                updated = { ...existing, text: existing.text + fragment.text };
+            }
+            const content = accumulated.content.slice();
+            content[idx] = updated;
+            return { ...accumulated, content };
+        }
+        default:
+            // Any other event, including types newer than this SDK, leaves the snapshot unchanged.
+            return accumulated;
+    }
+}

package/dist/vendor/lib/standard-schema.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standardSchemaToJSONSchema = standardSchemaToJSONSchema;
+exports.parseWithStandardSchema = parseWithStandardSchema;
+const error_1 = require("../core/error");
+/**
+ * Returns `jsonSchema` if given, otherwise the schema's Standard JSON Schema `input`
+ * representation (the model produces the value that the validator consumes).
+ */
+function standardSchemaToJSONSchema(schema, jsonSchema) {
+    if (jsonSchema) {
+        return jsonSchema;
+    }
+    const std = schema['~standard'];
+    if (std.jsonSchema) {
+        return std.jsonSchema.input({ target: 'draft-2020-12' });
+    }
+    throw new error_1.PukuError(`Could not derive a JSON Schema from this ${std.vendor} schema as it does not implement Standard JSON Schema (\`~standard.jsonSchema\`). Pass the \`jsonSchema\` option, or use a library version that implements it (e.g. zod >= 4.2, or valibot via \`toStandardJsonSchema()\`).`);
+}
+/**
+ * Validates `value` with `~standard.validate` and returns the typed output, throwing an
+ * `PukuError` on issues. Validation must be synchronous because `parse` hooks are.
+ */
+function parseWithStandardSchema(schema, value) {
+    const result = schema['~standard'].validate(value);
+    if (result instanceof Promise) {
+        // avoid an unhandled rejection from the discarded result
+        result.catch(() => { });
+        throw new error_1.PukuError(`Async validation is not supported: the ${schema['~standard'].vendor} schema's \`~standard.validate()\` returned a Promise.`);
+    }
+    if (result.issues) {
+        const formattedIssues = result.issues.slice(0, 5).map(formatIssue).join('\n');
+        const issueCount = result.issues.length;
+        const suffix = issueCount > 5 ? `\n  ... and ${issueCount - 5} more issue(s)` : '';
+        throw new error_1.PukuError(`Schema validation failed with ${issueCount} issue(s):\n${formattedIssues}${suffix}`);
+    }
+    return result.value;
+}
+function formatIssue(issue) {
+    const path = (issue.path ?? [])
+        .map((segment) => String(typeof segment === 'object' ? segment.key : segment))
+        .join('.');
+    return path ? `  - ${path}: ${issue.message}` : `  - ${issue.message}`;
+}

package/dist/vendor/lib/tools/BetaRunnableTool.cjs

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolName = toolName;
+exports.toolErrorContent = toolErrorContent;
+exports.runRunnableTool = runRunnableTool;
+const ToolError_1 = require("./ToolError");
+/**
+ * The name the model calls a tool by: `mcp_server_name` for MCP toolsets, `type` for nameless server
+ * toolsets (browser/computer), `name` for everything else.
+ */
+function toolName(tool) {
+    return ('name' in tool ? tool.name
+        : 'mcp_server_name' in tool ? tool.mcp_server_name
+            : tool.type);
+}
+/** Tool-result content for a thrown value: a {@link ToolError}'s own content, otherwise `Error: <message>`. */
+function toolErrorContent(e) {
+    return e instanceof ToolError_1.ToolError ? e.content : `Error: ${e instanceof Error ? e.message : String(e)}`;
+}
+/** Parse the input, run the tool, and turn anything thrown into an error result. */
+async function runRunnableTool(tool, rawInput, context) {
+    try {
+        const input = tool.parse ? tool.parse(rawInput) : rawInput;
+        const content = await tool.run(input, context);
+        return { content, isError: false };
+    }
+    catch (e) {
+        return { content: toolErrorContent(e), isError: true };
+    }
+}

package/dist/vendor/lib/tools/BetaToolRunner.cjs

@@ -0,0 +1,500 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BetaToolRunner = void 0;
+const ToolError_1 = require("./ToolError");
+const error_1 = require("../../core/error");
+const headers_1 = require("../../internal/headers");
+const promise_1 = require("../../internal/utils/promise");
+const values_1 = require("../../internal/utils/values");
+const CompactionControl_1 = require("./CompactionControl");
+const stainless_helper_header_1 = require("../../internal/stainless-helper-header");
+/**
+ * A ToolRunner handles the automatic conversation loop between the assistant and tools.
+ *
+ * A ToolRunner is an async iterable that yields either BetaMessage or BetaMessageStream objects
+ * depending on the streaming configuration.
+ */
+class BetaToolRunner {
+    client;
+    /** Whether the async iterator has been consumed */
+    #consumed = false;
+    /** Whether parameters have been mutated since the last API call */
+    #mutated = false;
+    /** Current state containing the request parameters */
+    #state;
+    #options;
+    /** Promise for the last message received from the assistant */
+    #message;
+    /** Cached tool response to avoid redundant executions */
+    #toolResponse;
+    /** Promise resolvers for waiting on completion */
+    #completion;
+    /** Number of iterations (API requests) made so far */
+    #iterationCount = 0;
+    constructor(client, params, options) {
+        this.client = client;
+        this.#state = {
+            params: {
+                // You can't clone the entire params since there are functions as handlers.
+                // You also don't really need to clone params.messages, but it probably will prevent a foot gun
+                // somewhere.
+                ...params,
+                messages: structuredClone(params.messages),
+            },
+        };
+        // structuredClone drops symbol-keyed properties, so collect helper marks
+        // from the original params here — the create()-side collector won't see
+        // them on the cloned messages.
+        const collected = (0, stainless_helper_header_1.collectStainlessHelpers)(params.tools, params.messages);
+        this.#options = {
+            ...options,
+            headers: (0, headers_1.buildHeaders)([
+                (0, stainless_helper_header_1.helperHeader)('BetaToolRunner'),
+                collected.length ? { [stainless_helper_header_1.STAINLESS_HELPER_HEADER]: collected.join(', ') } : undefined,
+                options?.headers,
+            ]),
+        };
+        this.#completion = (0, promise_1.promiseWithResolvers)();
+        if (params.compactionControl?.enabled) {
+            console.warn('Puku: The `compactionControl` parameter is deprecated and will be removed in a future version. ' +
+                'Use server-side compaction instead by passing `edits: [{ type: "compact_20260112" }]` in the params passed to `toolRunner()`. ' +
+                'See https://puku.sh/docs/');
+        }
+    }
+    async #checkAndCompact() {
+        const compactionControl = this.#state.params.compactionControl;
+        if (!compactionControl || !compactionControl.enabled) {
+            return false;
+        }
+        let tokensUsed = 0;
+        if (this.#message !== undefined) {
+            try {
+                const message = await this.#message;
+                const totalInputTokens = message.usage.input_tokens +
+                    (message.usage.cache_creation_input_tokens ?? 0) +
+                    (message.usage.cache_read_input_tokens ?? 0);
+                tokensUsed = totalInputTokens + message.usage.output_tokens;
+            }
+            catch {
+                // If we can't get the message, skip compaction
+                return false;
+            }
+        }
+        const threshold = compactionControl.contextTokenThreshold ?? CompactionControl_1.DEFAULT_TOKEN_THRESHOLD;
+        if (tokensUsed < threshold) {
+            return false;
+        }
+        const model = compactionControl.model ?? this.#state.params.model;
+        const summaryPrompt = compactionControl.summaryPrompt ?? CompactionControl_1.DEFAULT_SUMMARY_PROMPT;
+        const messages = this.#state.params.messages;
+        if (messages[messages.length - 1].role === 'assistant') {
+            // Remove tool_use blocks from the last message to avoid 400 error
+            // (tool_use requires tool_result, which we don't have yet)
+            const lastMessage = messages[messages.length - 1];
+            if (Array.isArray(lastMessage.content)) {
+                const nonToolBlocks = lastMessage.content.filter((block) => block.type !== 'tool_use');
+                if (nonToolBlocks.length === 0) {
+                    // If all blocks were tool_use, just remove the message entirely
+                    messages.pop();
+                }
+                else {
+                    lastMessage.content = nonToolBlocks;
+                }
+            }
+        }
+        const response = await this.client.beta.messages.create({
+            model,
+            messages: [
+                ...messages,
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'text',
+                            text: summaryPrompt,
+                        },
+                    ],
+                },
+            ],
+            max_tokens: this.#state.params.max_tokens,
+        }, {
+            signal: this.#options.signal,
+            headers: (0, headers_1.buildHeaders)([this.#options.headers, (0, stainless_helper_header_1.helperHeader)('compaction')]),
+        });
+        if (response.content[0]?.type !== 'text') {
+            throw new error_1.PukuError('Expected text response for compaction');
+        }
+        this.#state.params.messages = [
+            {
+                role: 'user',
+                content: response.content,
+            },
+        ];
+        return true;
+    }
+    async *[Symbol.asyncIterator]() {
+        if (this.#consumed) {
+            throw new error_1.PukuError('Cannot iterate over a consumed stream');
+        }
+        this.#consumed = true;
+        this.#mutated = true;
+        this.#toolResponse = undefined;
+        try {
+            while (true) {
+                let stream;
+                try {
+                    if (this.#state.params.max_iterations &&
+                        this.#iterationCount >= this.#state.params.max_iterations) {
+                        break;
+                    }
+                    this.#mutated = false;
+                    this.#toolResponse = undefined;
+                    this.#iterationCount++;
+                    this.#message = undefined;
+                    const { max_iterations, compactionControl, ...params } = this.#state.params;
+                    if (params.stream) {
+                        stream = this.client.beta.messages.stream({ ...params }, this.#options);
+                        this.#message = stream.finalMessage();
+                        // Make sure that this promise doesn't throw before we get the option to do something about it.
+                        // Error will be caught when we call await this.#message ultimately
+                        this.#message.catch(() => { });
+                        yield stream;
+                    }
+                    else {
+                        this.#message = this.client.beta.messages.create({ ...params, stream: false }, this.#options);
+                        yield this.#message;
+                    }
+                    const isCompacted = await this.#checkAndCompact();
+                    if (!isCompacted) {
+                        if (!this.#mutated) {
+                            const message = await this.#message;
+                            const nextStep = determineNextStepFromStopReason(message.stop_reason);
+                            this.#state.params.messages.push({ role: message.role, content: message.content });
+                            // Container-bound server tools reject a follow-up request that omits the container the
+                            // previous turn ran in, so carry its id forward unless the caller pinned one themselves.
+                            const { container } = this.#state.params;
+                            if (message.container) {
+                                if (container == null) {
+                                    this.#state.params.container = message.container.id;
+                                }
+                                else if (typeof container === 'object' && container.id == null) {
+                                    this.#state.params.container = { ...container, id: message.container.id };
+                                }
+                            }
+                            if (nextStep === 'stop') {
+                                break;
+                            }
+                            if (nextStep === 'resume') {
+                                continue;
+                            }
+                        }
+                        const toolMessage = await this.#generateToolResponse(this.#state.params.messages.at(-1));
+                        if (toolMessage) {
+                            this.#state.params.messages.push(toolMessage);
+                        }
+                        else if (!this.#mutated) {
+                            break;
+                        }
+                    }
+                }
+                finally {
+                    if (stream) {
+                        stream.abort();
+                    }
+                }
+            }
+            if (!this.#message) {
+                throw new error_1.PukuError('ToolRunner concluded without a message from the server');
+            }
+            this.#completion.resolve(await this.#message);
+        }
+        catch (error) {
+            this.#consumed = false;
+            // Silence unhandled promise errors
+            this.#completion.promise.catch(() => { });
+            this.#completion.reject(error);
+            this.#completion = (0, promise_1.promiseWithResolvers)();
+            throw error;
+        }
+    }
+    setMessagesParams(paramsOrMutator) {
+        if (typeof paramsOrMutator === 'function') {
+            this.#state.params = paramsOrMutator(this.#state.params);
+        }
+        else {
+            this.#state.params = paramsOrMutator;
+        }
+        this.#mutated = true;
+        // Invalidate cached tool response since parameters changed
+        this.#toolResponse = undefined;
+    }
+    setRequestOptions(optionsOrMutator) {
+        if (typeof optionsOrMutator === 'function') {
+            this.#options = optionsOrMutator(this.#options);
+        }
+        else {
+            this.#options = { ...this.#options, ...optionsOrMutator };
+        }
+    }
+    /**
+     * Get the tool response for the last message from the assistant.
+     * Avoids redundant tool executions by caching results.
+     *
+     * @returns A promise that resolves to a BetaMessageParam containing tool results, or null if no tools need to be executed
+     *
+     * @example
+     * const toolResponse = await runner.generateToolResponse();
+     * if (toolResponse) {
+     *   console.log('Tool results:', toolResponse.content);
+     * }
+     */
+    async generateToolResponse(signal = this.#options.signal) {
+        const message = (await this.#message) ?? this.params.messages.at(-1);
+        if (!message) {
+            return null;
+        }
+        return this.#generateToolResponse(message, signal);
+    }
+    async #generateToolResponse(lastMessage, signal = this.#options.signal) {
+        if (this.#toolResponse !== undefined) {
+            return this.#toolResponse;
+        }
+        this.#toolResponse = generateToolResponse(this.#state.params, lastMessage, {
+            ...this.#options,
+            signal,
+        });
+        return this.#toolResponse;
+    }
+    /**
+     * Wait for the async iterator to complete. This works even if the async iterator hasn't yet started, and
+     * will wait for an instance to start and go to completion.
+     *
+     * @returns A promise that resolves to the final BetaMessage when the iterator completes
+     *
+     * @example
+     * // Start consuming the iterator
+     * for await (const message of runner) {
+     *   console.log('Message:', message.content);
+     * }
+     *
+     * // Meanwhile, wait for completion from another part of the code
+     * const finalMessage = await runner.done();
+     * console.log('Final response:', finalMessage.content);
+     */
+    done() {
+        return this.#completion.promise;
+    }
+    /**
+     * Returns a promise indicating that the stream is done. Unlike .done(), this will eagerly read the stream:
+     * * If the iterator has not been consumed, consume the entire iterator and return the final message from the
+     * assistant.
+     * * If the iterator has been consumed, waits for it to complete and returns the final message.
+     *
+     * @returns A promise that resolves to the final BetaMessage from the conversation
+     * @throws {PukuError} If no messages were processed during the conversation
+     *
+     * @example
+     * const finalMessage = await runner.runUntilDone();
+     * console.log('Final response:', finalMessage.content);
+     */
+    async runUntilDone() {
+        // If not yet consumed, start consuming and wait for completion
+        if (!this.#consumed) {
+            for await (const _ of this) {
+                // Iterator naturally populates this.#message
+            }
+        }
+        // If consumed but not completed, wait for completion
+        return this.done();
+    }
+    /**
+     * Get the current parameters being used by the ToolRunner.
+     *
+     * @returns A readonly view of the current ToolRunnerParams
+     *
+     * @example
+     * const currentParams = runner.params;
+     * console.log('Current model:', currentParams.model);
+     * console.log('Message count:', currentParams.messages.length);
+     */
+    get params() {
+        return this.#state.params;
+    }
+    /**
+     * Add one or more messages to the conversation history.
+     *
+     * @param messages - One or more BetaMessageParam objects to add to the conversation
+     *
+     * @example
+     * runner.pushMessages(
+     *   { role: 'user', content: 'Also, what about the weather in NYC?' }
+     * );
+     *
+     * @example
+     * // Adding multiple messages
+     * runner.pushMessages(
+     *   { role: 'user', content: 'What about NYC?' },
+     *   { role: 'user', content: 'And Boston?' }
+     * );
+     */
+    pushMessages(...messages) {
+        this.setMessagesParams((params) => ({
+            ...params,
+            messages: [...params.messages, ...messages],
+        }));
+    }
+    /**
+     * Makes the ToolRunner directly awaitable, equivalent to calling .runUntilDone()
+     * This allows using `await runner` instead of `await runner.runUntilDone()`
+     */
+    then(onfulfilled, onrejected) {
+        return this.runUntilDone().then(onfulfilled, onrejected);
+    }
+}
+exports.BetaToolRunner = BetaToolRunner;
+async function generateToolResponse(params, lastMessage = params.messages.at(-1), requestOptions) {
+    // Only process if the last message is from the assistant and has tool use blocks
+    if (!lastMessage ||
+        lastMessage.role !== 'assistant' ||
+        !lastMessage.content ||
+        typeof lastMessage.content === 'string') {
+        return null;
+    }
+    const toolUseBlocks = lastMessage.content.filter((content) => content.type === 'tool_use');
+    if (toolUseBlocks.length === 0) {
+        return null;
+    }
+    const available = availableToolNames(params);
+    const toolResults = await Promise.all(toolUseBlocks.map(async (toolUse) => {
+        const tool = params.tools.find((t) => ('name' in t ? t.name
+            : 'mcp_server_name' in t ? t.mcp_server_name
+                : t.type) === toolUse.name);
+        // A `tool_removal` is only a hint to the model, which may still emit a tool_use for a
+        // withdrawn tool — treat those exactly like a tool that was never defined.
+        if (!tool || !('run' in tool) || !available.has(toolUse.name)) {
+            return toolNotFoundResult(toolUse);
+        }
+        try {
+            let input = toolUse.input;
+            if ('parse' in tool && tool.parse) {
+                input = tool.parse(input);
+            }
+            const result = await tool.run(input, {
+                toolUse: toolUse,
+                toolUseBlock: toolUse,
+                signal: requestOptions?.signal,
+            });
+            return {
+                type: 'tool_result',
+                tool_use_id: toolUse.id,
+                content: result,
+            };
+        }
+        catch (error) {
+            return {
+                type: 'tool_result',
+                tool_use_id: toolUse.id,
+                content: error instanceof ToolError_1.ToolError ?
+                    error.content
+                    : `Error: ${error instanceof Error ? error.message : String(error)}`,
+                is_error: true,
+            };
+        }
+    }));
+    return {
+        role: 'user',
+        content: toolResults,
+    };
+}
+function toolNotFoundResult(toolUse) {
+    return {
+        type: 'tool_result',
+        tool_use_id: toolUse.id,
+        content: `Error: Tool '${toolUse.name}' not found`,
+        is_error: true,
+    };
+}
+/**
+ * Computes the names of locally runnable tools that are still available for the assistant
+ * turn being answered, by folding `tool_removal` / `tool_addition` blocks from the
+ * `role: "system"` messages over the runnable tools. The assistant turn being answered is
+ * terminal-or-absent and only `system` messages are inspected, so folding the whole current
+ * history is exactly folding the messages preceding that turn — call this before appending
+ * anything after it. MCP references are ignored — those tools are executed server-side and
+ * never dispatched by this runner.
+ */
+function availableToolNames(params) {
+    const available = new Set();
+    for (const tool of params.tools) {
+        if ('run' in tool) {
+            available.add(tool.name);
+        }
+    }
+    for (const message of params.messages) {
+        if (message.role !== 'system' || typeof message.content === 'string') {
+            continue;
+        }
+        for (const block of message.content) {
+            applyToolChange(block, available);
+        }
+    }
+    return available;
+}
+function applyToolChange(block, available) {
+    switch (block.type) {
+        case 'tool_removal':
+        case 'tool_addition':
+            applyToolReference(block, available);
+            break;
+    }
+}
+function applyToolReference(block, available) {
+    const name = referencedToolName(block.tool);
+    if (name === undefined)
+        return;
+    if (block.type === 'tool_removal') {
+        available.delete(name);
+    }
+    else {
+        available.add(name);
+    }
+}
+function referencedToolName(ref) {
+    switch (ref.type) {
+        case 'tool_reference':
+            return ref.name;
+        default:
+            // mcp_tool_reference / mcp_toolset_reference run server-side; unknown reference
+            // types are ignored rather than rejected.
+            return undefined;
+    }
+}
+/**
+ * Sorts every stop reason into one of three buckets: `run_tools` turns run their client tool
+ * calls and continue the loop; `resume` turns are sent back unchanged so the server continues
+ * them; `stop` turns end the loop without running any tool calls.
+ */
+function determineNextStepFromStopReason(stopReason) {
+    if (stopReason === null)
+        return 'stop';
+    switch (stopReason) {
+        case 'tool_use':
+            return 'run_tools';
+        case 'pause_turn':
+        // pause_after_compaction hands the turn back before the model answers; sending it back
+        // unchanged continues it.
+        case 'compaction':
+            return 'resume';
+        case 'end_turn':
+        case 'stop_sequence':
+        case 'max_tokens':
+        case 'model_context_window_exceeded':
+        case 'refusal':
+            return 'stop';
+        default:
+            // The union is forward-compatible, so a stop reason this SDK doesn't know yet ends the
+            // loop rather than throwing; the `never` check makes tsc reject an unclassified member.
+            (0, values_1.checkNever)(stopReason);
+            return 'stop';
+    }
+}