@runtypelabs/sdk 1.0.2 → 1.2.0

package/dist/endpoints.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentsEndpoint = exports.ClientTokensEndpoint = exports.EvalEndpoint = exports.ToolsEndpoint = exports.ContextTemplatesEndpoint = exports.FlowStepsEndpoint = exports.AnalyticsEndpoint = exports.UsersEndpoint = exports.ChatEndpoint = exports.DispatchEndpoint = exports.ModelConfigsEndpoint = exports.ApiKeysEndpoint = exports.RecordsEndpoint = exports.PromptsEndpoint = exports.FlowsEndpoint = void 0;
+const generated_tool_gate_1 = require("./generated-tool-gate");
 /**
  * Flows endpoint handlers
  */
@@ -419,6 +420,34 @@ class DispatchEndpoint {
         }
         return this.client.post('/dispatch/resume', data);
     }
+    /**
+     * Evaluate a model-proposed runtime tool against a configurable allowlist policy.
+     * Useful for local `propose_runtime_tool` handlers before redispatch.
+     */
+    gateGeneratedRuntimeToolProposal(proposal, options) {
+        return (0, generated_tool_gate_1.evaluateGeneratedRuntimeToolProposal)(proposal, options);
+    }
+    /**
+     * Build standardized local-tool output for a generated tool proposal.
+     * Returns `{ approved, reason, violations, tool? }`.
+     */
+    buildGeneratedRuntimeToolGateOutput(proposal, options) {
+        return (0, generated_tool_gate_1.buildGeneratedRuntimeToolGateOutput)(proposal, options);
+    }
+    /**
+     * Attach approved runtime tools to a prompt step in a redispatch request.
+     * Returns a new request object and does not mutate the original.
+     */
+    attachApprovedRuntimeTools(request, runtimeTools, options) {
+        return (0, generated_tool_gate_1.attachRuntimeToolsToDispatchRequest)(request, runtimeTools, options);
+    }
+    /**
+     * Validate a generated runtime tool proposal and attach it to the redispatch
+     * request if approved, in one call.
+     */
+    applyGeneratedRuntimeToolProposal(request, proposal, options) {
+        return (0, generated_tool_gate_1.applyGeneratedRuntimeToolProposalToDispatchRequest)(request, proposal, options);
+    }
 }
 exports.DispatchEndpoint = DispatchEndpoint;
 /**
@@ -885,6 +914,9 @@ function dispatchAgentEvent(event, callbacks) {
         case 'agent_error':
             callbacks.onError?.(typedData);
             break;
+        case 'agent_paused':
+            callbacks.onAgentPaused?.(typedData);
+            break;
         case 'agent_ping':
             callbacks.onPing?.(typedData);
             break;
@@ -927,6 +959,57 @@ async function processAgentStream(body, callbacks) {
         reader.releaseLock();
     }
 }
+const GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
+    type: 'object',
+    properties: {
+        name: {
+            type: 'string',
+            description: 'Tool name. Use letters/numbers/underscore only.',
+        },
+        description: {
+            type: 'string',
+            description: 'Clear description of what the generated tool does.',
+        },
+        toolType: {
+            type: 'string',
+            enum: ['custom'],
+            description: 'Must be "custom" for generated code execution tools.',
+        },
+        parametersSchema: {
+            type: 'object',
+            description: 'JSON schema for tool call arguments.',
+        },
+        config: {
+            type: 'object',
+            description: 'Runtime tool config including code, sandboxProvider, language, and timeout.',
+        },
+        reason: {
+            type: 'string',
+            description: 'Why this tool is needed.',
+        },
+    },
+    required: ['name', 'description', 'toolType', 'parametersSchema', 'config'],
+};
+function appendRuntimeToolsToAgentRequest(request, runtimeTools) {
+    const existing = request.tools?.runtimeTools || [];
+    const existingNames = new Set(existing.map((tool) => tool.name));
+    const converted = runtimeTools
+        .filter((tool) => !existingNames.has(tool.name))
+        .map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        toolType: tool.toolType,
+        parametersSchema: tool.parametersSchema,
+        ...(tool.config ? { config: tool.config } : {}),
+    }));
+    return {
+        ...request,
+        tools: {
+            ...request.tools,
+            runtimeTools: [...existing, ...converted],
+        },
+    };
+}
 /**
  * Agents endpoint handlers
  */
@@ -964,6 +1047,54 @@ class AgentsEndpoint {
     async delete(id) {
         return this.client.delete(`/agents/${id}`);
     }
+    /**
+     * Evaluate a model-proposed runtime tool against a configurable allowlist policy.
+     * Useful for local `propose_runtime_tool` handlers before follow-up execution.
+     */
+    gateGeneratedRuntimeToolProposal(proposal, options) {
+        return (0, generated_tool_gate_1.evaluateGeneratedRuntimeToolProposal)(proposal, options);
+    }
+    /**
+     * Build standardized local-tool output for a generated tool proposal.
+     * Returns `{ approved, reason, violations, tool? }`.
+     */
+    buildGeneratedRuntimeToolGateOutput(proposal, options) {
+        return (0, generated_tool_gate_1.buildGeneratedRuntimeToolGateOutput)(proposal, options);
+    }
+    /**
+     * Create a local tool definition that validates model-proposed runtime tools.
+     * Plug this into `executeWithLocalTools()` under a name like `propose_runtime_tool`.
+     */
+    createGeneratedRuntimeToolGateLocalTool(options) {
+        const { description, ...gateOptions } = options || {};
+        return {
+            description: description ||
+                'Validate a generated runtime custom tool and return { approved, reason, violations, tool? }',
+            parametersSchema: GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA,
+            execute: async (args) => (0, generated_tool_gate_1.buildGeneratedRuntimeToolGateOutput)(args, gateOptions),
+        };
+    }
+    /**
+     * Attach approved runtime tools to an agent execute request.
+     * Returns a new request object and does not mutate the original.
+     */
+    attachApprovedRuntimeTools(request, runtimeTools) {
+        return appendRuntimeToolsToAgentRequest(request, runtimeTools);
+    }
+    /**
+     * Validate a generated runtime tool proposal and append it to an agent execute
+     * request if approved, in one call.
+     */
+    applyGeneratedRuntimeToolProposal(request, proposal, options) {
+        const decision = (0, generated_tool_gate_1.evaluateGeneratedRuntimeToolProposal)(proposal, options);
+        if (!decision.approved || !decision.tool) {
+            return { decision, request };
+        }
+        return {
+            decision,
+            request: appendRuntimeToolsToAgentRequest(request, [decision.tool]),
+        };
+    }
     /**
      * Execute an agent (non-streaming)
      */
@@ -1048,6 +1179,386 @@ class AgentsEndpoint {
         });
         return completeEvent;
     }
+    /**
+     * Execute an agent with local tool support (pause/resume loop)
+     *
+     * When the agent hits a tool with `toolType: 'local'`, the server emits
+     * `agent_paused`. This method automatically executes the local tool and
+     * resumes execution, repeating until the agent completes.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.agents.executeWithLocalTools('agt_123', {
+     *   messages: [{ role: 'user', content: 'Create a file called hello.txt' }],
+     * }, {
+     *   write_file: async ({ path, content }) => {
+     *     fs.writeFileSync(path, content)
+     *     return 'ok'
+     *   },
+     * })
+     * ```
+     */
+    async executeWithLocalTools(id, data, localTools, callbacks) {
+        // Build runtime tool definitions from local tool schemas and inject into request
+        const runtimeTools = Object.entries(localTools).map(([name, def]) => ({
+            name,
+            description: def.description,
+            toolType: 'local',
+            parametersSchema: def.parametersSchema,
+        }));
+        const requestData = {
+            ...data,
+            tools: {
+                ...data.tools,
+                runtimeTools: [
+                    ...(data.tools?.runtimeTools || []),
+                    ...runtimeTools,
+                ],
+            },
+        };
+        const response = await this.executeStream(id, requestData);
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        let currentBody = response.body;
+        while (true) {
+            let pausedEvent = null;
+            let completeEvent = null;
+            await processAgentStream(currentBody, {
+                ...callbacks,
+                onAgentPaused: (event) => {
+                    pausedEvent = event;
+                    callbacks?.onAgentPaused?.(event);
+                },
+                onAgentComplete: (event) => {
+                    completeEvent = event;
+                    callbacks?.onAgentComplete?.(event);
+                },
+            });
+            if (completeEvent)
+                return completeEvent;
+            if (pausedEvent) {
+                const { toolName, parameters, executionId } = pausedEvent;
+                const toolDef = localTools[toolName];
+                if (!toolDef) {
+                    throw new Error(`Local tool "${toolName}" required but not provided`);
+                }
+                // Recursively unwrap stringified parameters — the server pipeline may
+                // double-serialize: object → JSON string → JSON string
+                let parsedParams = {};
+                let current = parameters;
+                for (let i = 0; i < 3; i++) {
+                    if (typeof current === 'string') {
+                        try {
+                            current = JSON.parse(current);
+                        }
+                        catch {
+                            console.warn(`[local-tools] Failed to parse parameters (attempt ${i + 1}):`, typeof current, String(current).slice(0, 200));
+                            break;
+                        }
+                    }
+                    else {
+                        break;
+                    }
+                }
+                if (current && typeof current === 'object' && !Array.isArray(current)) {
+                    parsedParams = current;
+                }
+                else {
+                    console.warn('[local-tools] Parameters could not be resolved to an object:', typeof current, String(current).slice(0, 200));
+                }
+                let toolResult;
+                try {
+                    toolResult = await toolDef.execute(parsedParams);
+                }
+                catch (err) {
+                    // Return the error as a tool result so the agent can recover
+                    toolResult = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                }
+                // Resume via agent resume endpoint
+                const resumeResponse = await this.client.requestStream(`/agents/${id}/resume`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        executionId,
+                        toolOutputs: { [toolName]: toolResult },
+                        streamResponse: true,
+                        debugMode: data.debugMode,
+                    }),
+                });
+                if (!resumeResponse.ok) {
+                    const error = await resumeResponse.json().catch(() => ({ error: 'Unknown error' }));
+                    throw new Error(error.error || `HTTP ${resumeResponse.status}`);
+                }
+                currentBody = resumeResponse.body;
+                continue;
+            }
+            // Stream ended without complete or paused
+            return null;
+        }
+    }
+    // ─── Long-Task Agent Execution ───────────────────────────────────────
+    /**
+     * Run a long-task agent across multiple sessions with automatic state management.
+     *
+     * Each session is a single agent execution. The SDK drives the loop client-side,
+     * calling the agent's execute endpoint repeatedly and accumulating context.
+     * Progress is optionally synced to a Runtype record for dashboard visibility.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.agents.runTask('agt_123', {
+     *   message: 'Build a REST API with CRUD endpoints',
+     *   maxSessions: 20,
+     *   maxCost: 5.00,
+     *   trackProgress: true,
+     *   onSession: (state) => {
+     *     console.log(`Session ${state.sessionCount}: ${state.lastStopReason} ($${state.totalCost.toFixed(4)})`)
+     *   },
+     * })
+     *
+     * console.log(`Finished: ${result.status} after ${result.sessionCount} sessions`)
+     * ```
+     */
+    async runTask(id, options) {
+        const maxSessions = options.maxSessions ?? 50;
+        const maxCost = options.maxCost;
+        const useStream = options.stream ?? true;
+        // Resolve agent metadata
+        const agent = await this.get(id);
+        const taskName = typeof options.trackProgress === 'string'
+            ? options.trackProgress
+            : options.trackProgress
+                ? `${agent.name} task`
+                : '';
+        // Initialize state
+        const state = {
+            agentId: id,
+            agentName: agent.name,
+            taskName: taskName || `${agent.name} task`,
+            status: 'running',
+            sessionCount: 0,
+            totalCost: 0,
+            lastOutput: '',
+            lastStopReason: 'complete',
+            sessions: [],
+            startedAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        // Track the record ID if we're syncing
+        let recordId;
+        // Extract local tool names for prompt injection
+        const localToolNames = options.localTools ? Object.keys(options.localTools) : undefined;
+        // Session loop
+        for (let session = 0; session < maxSessions; session++) {
+            // Build messages for this session
+            const messages = this.buildSessionMessages(options.message, state, session, maxSessions, localToolNames);
+            // Execute one session
+            let sessionResult;
+            const sessionData = { messages, debugMode: options.debugMode, model: options.model };
+            if (useStream && options.localTools) {
+                // Local tools require the pause/resume streaming loop
+                const completeEvent = await this.executeWithLocalTools(id, sessionData, options.localTools, options.streamCallbacks);
+                if (!completeEvent) {
+                    throw new Error('Agent stream ended without a complete event');
+                }
+                sessionResult = {
+                    success: completeEvent.success,
+                    result: completeEvent.finalOutput || '',
+                    iterations: completeEvent.iterations,
+                    totalCost: completeEvent.totalCost || 0,
+                    stopReason: completeEvent.stopReason,
+                    error: completeEvent.error,
+                };
+            }
+            else if (useStream && options.streamCallbacks) {
+                const completeEvent = await this.executeWithCallbacks(id, sessionData, options.streamCallbacks);
+                if (!completeEvent) {
+                    throw new Error('Agent stream ended without a complete event');
+                }
+                sessionResult = {
+                    success: completeEvent.success,
+                    result: completeEvent.finalOutput || '',
+                    iterations: completeEvent.iterations,
+                    totalCost: completeEvent.totalCost || 0,
+                    stopReason: completeEvent.stopReason,
+                    error: completeEvent.error,
+                };
+            }
+            else {
+                sessionResult = await this.execute(id, sessionData);
+            }
+            // Update state
+            const sessionCost = sessionResult.totalCost;
+            state.sessionCount = session + 1;
+            state.totalCost += sessionCost;
+            state.lastOutput = sessionResult.result;
+            state.lastStopReason = sessionResult.stopReason;
+            state.updatedAt = new Date().toISOString();
+            state.sessions.push({
+                index: session + 1,
+                cost: sessionCost,
+                iterations: sessionResult.iterations,
+                stopReason: sessionResult.stopReason,
+                outputPreview: sessionResult.result.slice(0, 300),
+                completedAt: new Date().toISOString(),
+            });
+            // Keep session log trimmed to last 50 entries
+            if (state.sessions.length > 50) {
+                state.sessions = state.sessions.slice(-50);
+            }
+            // Check terminal conditions
+            if (sessionResult.stopReason === 'complete') {
+                state.status = 'complete';
+            }
+            else if (sessionResult.stopReason === 'error') {
+                state.status = 'complete';
+            }
+            else if (sessionResult.stopReason === 'max_cost') {
+                state.status = 'budget_exceeded';
+            }
+            else if (this.detectTaskCompletion(sessionResult.result)) {
+                // Client-side stop-phrase detection for non-loop agents returning 'end_turn'
+                state.status = 'complete';
+            }
+            else if (maxCost && state.totalCost >= maxCost) {
+                state.status = 'budget_exceeded';
+            }
+            else if (session + 1 >= maxSessions) {
+                state.status = 'max_sessions';
+            }
+            // Sync to record if enabled
+            if (options.trackProgress) {
+                recordId = await this.syncProgressRecord(state, recordId);
+            }
+            // Notify caller
+            if (options.onSession) {
+                const shouldStop = await options.onSession(state);
+                if (shouldStop === false) {
+                    state.status = 'paused';
+                }
+            }
+            // Stop if terminal
+            if (state.status !== 'running') {
+                break;
+            }
+        }
+        return {
+            status: state.status,
+            sessionCount: state.sessionCount,
+            totalCost: state.totalCost,
+            lastOutput: state.lastOutput,
+            sessions: state.sessions,
+            recordId,
+        };
+    }
+    /**
+     * Client-side fallback for detecting task completion in agent output.
+     * Mirrors the API's detectAutoComplete() for non-loop agents that return 'end_turn'.
+     */
+    detectTaskCompletion(output) {
+        const upper = output.toUpperCase();
+        return AgentsEndpoint.STOP_PHRASES.some((phrase) => upper.includes(phrase.toUpperCase()));
+    }
+    /**
+     * Build messages for a session, injecting progress context for continuation sessions.
+     */
+    buildSessionMessages(originalMessage, state, sessionIndex, maxSessions, localToolNames) {
+        // Build local tools guidance block when tools are available
+        const toolsBlock = localToolNames?.length
+            ? [
+                '',
+                '--- Local Tools ---',
+                `You have access to local filesystem tools (${localToolNames.join(', ')}) that execute directly on the user's machine.`,
+                'Use these tools to create working, runnable files — not just code in your response.',
+                'Prefer creating self-contained HTML files that the user can open in a web browser.',
+                'For example, write a single .html file with inline CSS and JavaScript that demonstrates the result.',
+                'Always use write_file to save your output so the user can run it immediately.',
+            ].join('\n')
+            : '';
+        // First session: user message + completion signal instruction
+        if (sessionIndex === 0) {
+            const content = [
+                originalMessage,
+                toolsBlock,
+                '',
+                `This is a multi-session task (session 1/${maxSessions}). When you have fully completed the task, end your response with TASK_COMPLETE on its own line.`,
+            ].join('\n');
+            return [{ role: 'user', content }];
+        }
+        // Continuation sessions: inject progress context
+        const recentSessions = state.sessions.slice(-5);
+        const progressSummary = recentSessions
+            .map((s) => `  Session ${s.index}: ${s.stopReason} ($${s.cost.toFixed(4)}) — ${s.outputPreview.slice(0, 100)}`)
+            .join('\n');
+        const content = [
+            originalMessage,
+            toolsBlock,
+            '',
+            `--- Progress (session ${sessionIndex + 1}/${maxSessions}, $${state.totalCost.toFixed(4)} spent) ---`,
+            `Previous sessions:`,
+            progressSummary,
+            '',
+            `Last output (do NOT repeat this — build on it):`,
+            state.lastOutput.slice(0, 1000),
+            '',
+            'Continue where you left off. Do not redo previous work. If the task is already complete, respond with TASK_COMPLETE.',
+        ].join('\n');
+        return [{ role: 'user', content }];
+    }
+    /**
+     * Upsert a record to sync long-task progress to the dashboard.
+     * Creates the record on first call, updates it on subsequent calls.
+     */
+    async syncProgressRecord(state, existingRecordId) {
+        const metadata = {
+            agentId: state.agentId,
+            agentName: state.agentName,
+            status: state.status,
+            sessionCount: state.sessionCount,
+            totalCost: state.totalCost,
+            lastStopReason: state.lastStopReason,
+            lastOutputPreview: state.lastOutput.slice(0, 500),
+            sessions: state.sessions.slice(-10), // Keep last 10 in the record
+            startedAt: state.startedAt,
+            updatedAt: state.updatedAt,
+        };
+        try {
+            if (existingRecordId) {
+                // Update existing record
+                const record = await this.client.put(`/records/${existingRecordId}`, { metadata });
+                return record.id;
+            }
+            else {
+                // Try to find existing record by type + name first
+                const existing = await this.client.get('/records', { type: 'agent-task', name: state.taskName, limit: 1 });
+                if (existing.data.length > 0) {
+                    const record = await this.client.put(`/records/${existing.data[0].id}`, { metadata });
+                    return record.id;
+                }
+                // Create new record
+                const record = await this.client.post('/records', {
+                    type: 'agent-task',
+                    name: state.taskName,
+                    metadata,
+                });
+                return record.id;
+            }
+        }
+        catch {
+            // Record sync is best-effort — don't fail the task
+            return existingRecordId || '';
+        }
+    }
 }
 exports.AgentsEndpoint = AgentsEndpoint;
+/** Stop phrases that indicate the agent considers its task complete. */
+AgentsEndpoint.STOP_PHRASES = [
+    'DONE:',
+    'TASK_COMPLETE',
+    'FINISHED',
+    '[COMPLETE]',
+    'STATUS: RESOLVED',
+    'STATUS: COMPLETE',
+];
 //# sourceMappingURL=endpoints.js.map