tarsk 0.3.43 → 0.4.4

package/README.md

@@ -1,3 +1,3 @@
 # Tarsk
 
-Run `npx tarsk` to start the Tarsk App.
+Run `npx tarsk` to start the Tarsk App.

package/dist/agent/agent.error-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error handling utilities for Pi Agent
+ * Provides functions for extracting and formatting error information
+ */
+import type { AgentEvent } from "@tarsk/shared";
+/**
+ * Extracts error code from an unknown error object
+ */
+export declare function getErrorCode(error: unknown): string | undefined;
+/**
+ * Formats an error into an AgentEvent
+ */
+export declare function formatErrorEvent(error: unknown): AgentEvent;
+//# sourceMappingURL=agent.error-utils.d.ts.map

package/dist/agent/agent.error-utils.js

@@ -0,0 +1,52 @@
+/**
+ * Error handling utilities for Pi Agent
+ * Provides functions for extracting and formatting error information
+ */
+/**
+ * Extracts error code from an unknown error object
+ */
+export function getErrorCode(error) {
+    if (error && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return undefined;
+}
+/**
+ * Formats an error into an AgentEvent
+ */
+export function formatErrorEvent(error) {
+    let errCode;
+    let errMessage;
+    let errStack;
+    let errDetails;
+    if (error instanceof Error) {
+        errMessage = error.message || "Unknown error";
+        errStack = error.stack;
+        errCode = getErrorCode(error);
+    }
+    else if (typeof error === "object" && error !== null) {
+        errMessage = error.message
+            ? String(error.message)
+            : JSON.stringify(error);
+        errCode = getErrorCode(error);
+        errDetails = error;
+    }
+    else if (typeof error === "string") {
+        errMessage = error;
+    }
+    else {
+        errMessage = String(error);
+    }
+    return {
+        type: "error",
+        content: errMessage,
+        error: {
+            code: errCode ?? "EXECUTION_ERROR",
+            message: errMessage ?? "An error occurred during execution",
+            details: { stack: errStack, originalError: errDetails },
+        },
+    };
+}
+//# sourceMappingURL=agent.error-utils.js.map

package/dist/agent/agent.event-transformer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Event transformer for Pi Agent
+ * Handles transformation of Pi Agent events to AgentEvent format
+ */
+import type { AgentEvent as PiAgentEvent } from "@mariozechner/pi-agent-core";
+import type { AssistantMessage } from "@mariozechner/pi-ai";
+import type { AgentEvent } from "@tarsk/shared";
+/**
+ * Extracts text content from an assistant message
+ */
+export declare function extractTextFromAssistantMessage(msg: AssistantMessage): string;
+/**
+ * Event queue manager for handling Pi Agent events
+ */
+export declare class EventQueue {
+    private queue;
+    private resolver;
+    finalContent: string;
+    errorOccurred: boolean;
+    toolCallCount: number;
+    /**
+     * Processes Pi Agent events and transforms them into AgentEvent format
+     */
+    handlePiEvent(event: PiAgentEvent): void;
+    /**
+     * Adds an event to the queue
+     */
+    push(event: AgentEvent): void;
+    /**
+     * Removes and returns the next event from the queue
+     */
+    shift(): AgentEvent | undefined;
+    /**
+     * Returns the number of events in the queue
+     */
+    get length(): number;
+    /**
+     * Sets a resolver to be called when new events are added
+     */
+    setResolver(resolver: () => void): void;
+    /**
+     * Clears the current resolver
+     */
+    clearResolver(): void;
+    /**
+     * Notifies the resolver if one is set
+     */
+    private notifyResolver;
+    /**
+     * Wakes up any waiting consumer (e.g. when the agent finishes).
+     * Call this instead of setResolver(() => {}) so the pending Promise resolves.
+     */
+    notify(): void;
+}
+//# sourceMappingURL=agent.event-transformer.d.ts.map

package/dist/agent/agent.event-transformer.js

@@ -0,0 +1,175 @@
+/**
+ * Event transformer for Pi Agent
+ * Handles transformation of Pi Agent events to AgentEvent format
+ */
+/**
+ * Extracts text content from an assistant message
+ */
+export function extractTextFromAssistantMessage(msg) {
+    return msg.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+}
+/**
+ * Event queue manager for handling Pi Agent events
+ */
+export class EventQueue {
+    queue = [];
+    resolver = null;
+    finalContent = "";
+    errorOccurred = false;
+    toolCallCount = 0;
+    /**
+     * Processes Pi Agent events and transforms them into AgentEvent format
+     */
+    handlePiEvent(event) {
+        if (event.type === "message_update" && event.assistantMessageEvent.type === "thinking_delta") {
+            // Stream thinking/reasoning content in real-time as the model thinks
+            const delta = event.assistantMessageEvent.delta;
+            this.push({
+                type: "message",
+                role: "assistant",
+                content: delta,
+                isThinking: true,
+            });
+        }
+        else if (event.type === "message_update" &&
+            event.assistantMessageEvent.type === "text_delta") {
+            const delta = event.assistantMessageEvent.delta;
+            this.finalContent += delta;
+            this.push({
+                type: "message",
+                role: "assistant",
+                content: delta,
+            });
+        }
+        else if (event.type === "message_update" &&
+            event.assistantMessageEvent.type === "toolcall_delta") {
+            // Handle tool call delta events for progress indication
+            const deltaEvent = event.assistantMessageEvent;
+            this.push({
+                type: "toolcall_delta",
+                contentIndex: deltaEvent.contentIndex,
+                delta: deltaEvent.delta,
+                partial: deltaEvent.partial,
+            });
+        }
+        else if (event.type === "message_start") {
+            // Handle message_start events - these contain usage information
+            this.push({
+                type: "message",
+                role: "assistant",
+                content: "",
+                message: event.message, // Store the full message object for usage extraction
+            });
+        }
+        else if (event.type === "tool_execution_start") {
+            this.toolCallCount++;
+            this.push({
+                type: "message",
+                role: "tool",
+                content: JSON.stringify([
+                    {
+                        type: "tool_use",
+                        name: event.toolName,
+                        id: event.toolCallId,
+                        input: event.args,
+                    },
+                ]),
+            });
+        }
+        else if (event.type === "tool_execution_end") {
+            const resultContent = event.result?.content
+                ?.filter((b) => b.type === "text")
+                .map((b) => b.text ?? "")
+                .join("") ?? JSON.stringify(event.result);
+            this.push({
+                type: "message",
+                role: "tool",
+                content: JSON.stringify([
+                    {
+                        type: "tool-result",
+                        toolCallId: event.toolCallId,
+                        toolName: event.toolName,
+                        content: resultContent,
+                        isError: event.isError,
+                    },
+                ]),
+            });
+        }
+        else if (event.type === "agent_end") {
+            const messages = event.messages;
+            const lastAssistant = [...messages]
+                .reverse()
+                .find((m) => "role" in m && m.role === "assistant");
+            if (lastAssistant) {
+                const extracted = extractTextFromAssistantMessage(lastAssistant);
+                if (extracted && extracted !== this.finalContent) {
+                    this.finalContent = extracted;
+                }
+            }
+            const toolCallCount = messages.filter((m) => "role" in m &&
+                m.role === "assistant" &&
+                "content" in m &&
+                Array.isArray(m.content) &&
+                m.content.some((b) => b.type === "tool_use")).length;
+            console.log(`[ai] agent_end: ${messages.length} messages, ` +
+                `finalContent length=${this.finalContent.length}, ` +
+                `toolCallRounds=${toolCallCount}` +
+                (this.finalContent.length === 0 ? " ⚠️  no text content produced" : ""));
+        }
+        this.notifyResolver();
+    }
+    /**
+     * Adds an event to the queue
+     */
+    push(event) {
+        this.queue.push(event);
+    }
+    /**
+     * Removes and returns the next event from the queue
+     */
+    shift() {
+        return this.queue.shift();
+    }
+    /**
+     * Returns the number of events in the queue
+     */
+    get length() {
+        return this.queue.length;
+    }
+    /**
+     * Sets a resolver to be called when new events are added
+     */
+    setResolver(resolver) {
+        this.resolver = resolver;
+    }
+    /**
+     * Clears the current resolver
+     */
+    clearResolver() {
+        this.resolver = null;
+    }
+    /**
+     * Notifies the resolver if one is set
+     */
+    notifyResolver() {
+        if (this.resolver) {
+            this.resolver();
+            this.resolver = null;
+        }
+    }
+    /**
+     * Wakes up any waiting consumer (e.g. when the agent finishes).
+     * Call this instead of setResolver(() => {}) so the pending Promise resolves.
+     */
+    notify() {
+        if (this.resolver) {
+            const resolver = this.resolver;
+            this.resolver = null;
+            resolver();
+        }
+    }
+}
+//# sourceMappingURL=agent.event-transformer.js.map

package/dist/agent/agent.executor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PiExecutor handles execution of agent commands via @mariozechner/pi-agent-core
+ *
+ * This manager is responsible for:
+ * - Executing streaming agent sessions using the Pi Agent
+ * - Streaming result messages back to the caller
+ * - Handling execution errors
+ */
+import type { ExecutionContext, AgentEvent } from "@tarsk/shared";
+import { MetadataManager } from "../features/metadata/metadata.manager.js";
+/**
+ * AgentExecutor interface defines the contract for agent command execution
+ */
+export interface AgentExecutor {
+    execute(prompt: string, context: ExecutionContext, signal?: AbortSignal): AsyncGenerator<AgentEvent>;
+}
+/**
+ * PiExecutorImpl provides the implementation for agent command execution
+ * using the @mariozechner/pi-agent-core Agent with streaming events.
+ */
+export declare class PiExecutorImpl implements AgentExecutor {
+    private metadataManager;
+    constructor(metadataManager: MetadataManager);
+    execute(userPrompt: string, context: ExecutionContext, signal?: AbortSignal): AsyncGenerator<AgentEvent>;
+}
+//# sourceMappingURL=agent.executor.d.ts.map

package/dist/agent/agent.executor.js

@@ -0,0 +1,286 @@
+/**
+ * PiExecutor handles execution of agent commands via @mariozechner/pi-agent-core
+ *
+ * This manager is responsible for:
+ * - Executing streaming agent sessions using the Pi Agent
+ * - Streaming result messages back to the caller
+ * - Handling execution errors
+ */
+import { Agent } from "@mariozechner/pi-agent-core";
+import { resolve, isAbsolute } from "path";
+import { createCodingTools } from "../tools/index.js";
+import { createAgentTool } from "../tools/agent-tool.js";
+import { resolveProviderConfig } from "../features/providers/provider-resolver.js";
+import { getDataDir } from "../core/paths.js";
+import { resolveModel } from "./agent.model-resolver.js";
+import { EventQueue } from "./agent.event-transformer.js";
+import { loadAgentSystemPrompt } from "./agent.prompt-loader.js";
+import { getErrorCode, formatErrorEvent } from "./agent.error-utils.js";
+/**
+ * PiExecutorImpl provides the implementation for agent command execution
+ * using the @mariozechner/pi-agent-core Agent with streaming events.
+ */
+export class PiExecutorImpl {
+    metadataManager;
+    constructor(metadataManager) {
+        this.metadataManager = metadataManager;
+    }
+    async *execute(userPrompt, context, signal) {
+        try {
+            const providerName = context.provider;
+            if (!providerName) {
+                throw new Error("No provider specified in execution context");
+            }
+            let model = context.model?.trim();
+            if (!model) {
+                throw new Error("No model specified in execution context");
+            }
+            model = model.replace(`${providerName.toLowerCase()}/`, "");
+            // Ensure threadPath is absolute - if relative, resolve against dataDir
+            const cwd = isAbsolute(context.threadPath)
+                ? context.threadPath
+                : resolve(getDataDir(), context.threadPath);
+            console.log("[ai] Execution context:", {
+                model,
+                cwd,
+                providerName,
+                promptLength: userPrompt.length,
+            });
+            // Resolve provider config: merges hardcoded PROVIDERS with catalog data (api, keyName, url)
+            const providerConfig = await resolveProviderConfig(providerName);
+            if (!providerConfig) {
+                throw new Error(`Unknown provider: ${providerName}`);
+            }
+            let apiKey = providerConfig.env && providerConfig.env.length > 0
+                ? process.env[providerConfig.env[0]]
+                : undefined;
+            let apiKeySource = "environment";
+            if (!apiKey) {
+                try {
+                    const providerKeys = await this.metadataManager.getProviderKeys();
+                    apiKey = providerKeys[providerConfig.name];
+                    apiKeySource = "configuration";
+                }
+                catch (error) {
+                    console.error(`[ai] Failed to retrieve provider keys from configuration:`, error);
+                    throw new Error(`Failed to retrieve API key for provider ${providerName}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (!apiKey) {
+                throw new Error(`No API key found for provider: ${providerName}. ` +
+                    `Set ${providerConfig.env && providerConfig.env.length > 0 ? providerConfig.env[0] : "an API key"} in environment variables or configuration.`);
+            }
+            // Verify the API key is not still encrypted (should have been decrypted by metadata manager)
+            if (apiKey.includes(":") && apiKey.length > 100) {
+                console.warn(`[ai] ⚠️  API key appears to still be encrypted. This may indicate a decryption failure.`);
+            }
+            console.log(`[ai] API key source for ${providerName}: ${apiKeySource}`);
+            const resolvedModel = resolveModel(providerName, model, providerConfig);
+            console.log("[ai] Resolved model:", {
+                id: resolvedModel.id,
+                api: resolvedModel.api,
+                provider: resolvedModel.provider,
+            });
+            const tools = await createCodingTools(cwd, {
+                skills: context.skills,
+                threadId: context.threadId,
+            });
+            const systemPrompt = await loadAgentSystemPrompt(cwd, context.skills, context.planMode, context.agents);
+            console.log("[ai] System prompt loaded from thread path", context.skills && context.skills.length > 0 ? `with ${context.skills.length} skill(s)` : "");
+            console.log(`[ai] System prompt: ${systemPrompt}`);
+            const eventQueue = new EventQueue();
+            // Add agent tool if agents are defined (enables subagent spawning)
+            const invocableAgents = (context.agents ?? []).filter((a) => !a.disableModelInvocation);
+            if (invocableAgents.length > 0) {
+                const agentToolInstance = createAgentTool({
+                    agents: invocableAgents,
+                    baseTools: tools,
+                    metadataManager: this.metadataManager,
+                    parentModel: `${providerName.toLowerCase()}/${model}`,
+                    parentProvider: providerName,
+                    defaultSystemPrompt: systemPrompt,
+                    onEvent: (event) => eventQueue.push(event),
+                    signal,
+                });
+                tools.push(agentToolInstance);
+            }
+            const agent = new Agent({
+                initialState: {
+                    systemPrompt,
+                    model: resolvedModel,
+                    tools,
+                },
+                getApiKey: async () => apiKey,
+            });
+            let done = false;
+            let aborted = false;
+            // Handle abort signal from client disconnect
+            const onAbort = () => {
+                if (aborted)
+                    return;
+                aborted = true;
+                console.log("[ai] Client disconnected, aborting agent execution");
+                // Immediately abort the agent to stop ongoing LLM API calls.
+                // Must happen here — not in the finally block — otherwise the agent
+                // keeps consuming tokens until the current API call completes.
+                agent.abort();
+                done = true;
+                eventQueue.notify();
+            };
+            if (signal) {
+                if (signal.aborted) {
+                    console.log("[ai] Agent execution aborted before start");
+                    return;
+                }
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            console.log(`[ai] Agent prompt request:`, {
+                promptLength: userPrompt.length,
+                promptPreview: userPrompt.substring(0, 200) + (userPrompt.length > 200 ? "..." : ""),
+            });
+            let count = 0;
+            let lastLogTime = 0;
+            const unsubscribe = agent.subscribe((event) => {
+                // Throttle logging to prevent spam - only log every 2 seconds or every 100 events
+                const now = Date.now();
+                const shouldLog = count === 0 || count % 100 === 0 || now - lastLogTime > 2000;
+                if (shouldLog) {
+                    console.log(`[ai] Agent event.${count++}:`, event.type, event.type === "message_update" &&
+                        event.assistantMessageEvent?.type === "toolcall_delta"
+                        ? `toolcall_delta (delta="${event.assistantMessageEvent.delta}")`
+                        : JSON.stringify(event).substring(0, 255));
+                    lastLogTime = now;
+                }
+                else {
+                    count++;
+                }
+                eventQueue.handlePiEvent(event);
+            });
+            const images = (context.attachments ?? [])
+                .filter((a) => a.mimeType.startsWith("image/"))
+                .map((a) => ({ type: "image", data: a.content, mimeType: a.mimeType }));
+            const textAttachments = (context.attachments ?? []).filter((a) => !a.mimeType.startsWith("image/"));
+            let finalPrompt = userPrompt;
+            if (textAttachments.length > 0) {
+                const attachmentBlocks = textAttachments
+                    .map((a) => {
+                    const decoded = Buffer.from(a.content, "base64").toString("utf-8");
+                    return `<file name="${a.name}">\n${decoded}\n</file>`;
+                })
+                    .join("\n\n");
+                finalPrompt = `${attachmentBlocks}\n\n${userPrompt}`;
+            }
+            console.log(`[ai] Attachments: ${context.attachments?.length ?? 0} total, ${images.length} image(s), ${textAttachments.length} text file(s)`, (context.attachments ?? []).map((a) => ({
+                name: a.name,
+                mimeType: a.mimeType,
+                contentLength: a.content?.length ?? 0,
+            })), "images →", images.map((img) => ({ mimeType: img.mimeType, dataLength: img.data?.length ?? 0 })));
+            const promptDone = agent
+                .prompt(finalPrompt, images.length > 0 ? images : undefined)
+                .then(() => {
+                console.log(`[ai] Agent prompt completed successfully`);
+                done = true;
+                // Wake up the waiting loop so it can check the done condition and exit.
+                // Using notify() instead of setResolver(() => {}) is critical: setResolver
+                // would orphan any pending Promise resolver, causing an infinite hang.
+                eventQueue.notify();
+            })
+                .catch((err) => {
+                const errMessage = err instanceof Error ? err.message : String(err);
+                console.error(`[ai] Agent prompt failed:`, {
+                    error: errMessage,
+                    errorType: err instanceof Error ? err.constructor.name : typeof err,
+                });
+                if (!eventQueue.errorOccurred) {
+                    eventQueue.errorOccurred = true;
+                    eventQueue.push({
+                        type: "error",
+                        content: errMessage,
+                        error: {
+                            code: getErrorCode(err) ?? "EXECUTION_ERROR",
+                            message: errMessage,
+                            details: {
+                                stack: err instanceof Error ? err.stack : undefined,
+                            },
+                        },
+                    });
+                }
+                done = true;
+                // Same fix: notify instead of replacing the resolver with a no-op.
+                eventQueue.notify();
+            });
+            try {
+                while (!done || eventQueue.length > 0) {
+                    if (eventQueue.length > 0) {
+                        yield eventQueue.shift();
+                    }
+                    else {
+                        await new Promise((resolve) => {
+                            eventQueue.setResolver(resolve);
+                        });
+                    }
+                }
+                // When aborted, agent.abort() was already called in onAbort — skip waiting
+                // for the LLM response since it has been cancelled.
+                if (!aborted) {
+                    await promptDone;
+                    if (!eventQueue.errorOccurred && eventQueue.finalContent) {
+                        console.log(`[ai] Yielding result, content length=${eventQueue.finalContent.length}`);
+                        yield {
+                            type: "result",
+                            content: eventQueue.finalContent,
+                        };
+                    }
+                    else if (!eventQueue.errorOccurred) {
+                        if (eventQueue.toolCallCount > 0) {
+                            console.log(`[ai] ⚠️  Agent ended with no text content after ${eventQueue.toolCallCount} tool call(s). Emitting error event.`);
+                            yield {
+                                type: "error",
+                                content: "The agent used tools but did not produce a response. The model may have run out of context or terminated unexpectedly. Please try again.",
+                                error: {
+                                    code: "NO_CONTENT_AFTER_TOOLS",
+                                    message: "Agent terminated after tool calls without producing a text response",
+                                    details: { toolCallCount: eventQueue.toolCallCount },
+                                },
+                            };
+                        }
+                        else {
+                            console.log("[ai] ⚠️  Agent ended with no text content and no tool calls.");
+                            yield {
+                                type: "error",
+                                content: `The model ${model} from ${providerName} did not provide a response to your prompt. Check your API key and balance and try again.`,
+                                error: {
+                                    code: "NO_CONTENT_NO_TOOLS",
+                                    message: `The model ${model} from ${providerName} did not provide a response to your prompt.`,
+                                },
+                            };
+                        }
+                    }
+                    else {
+                        console.error("[ai] eventQueue.errorOccurred", eventQueue.errorOccurred);
+                    }
+                }
+                else {
+                    console.log("[ai] Agent aborted by user, skipping result emission");
+                }
+            }
+            finally {
+                // Clean up signal listener
+                if (signal) {
+                    signal.removeEventListener("abort", onAbort);
+                }
+                unsubscribe();
+                if (signal?.aborted) {
+                    console.warn("[ai] Agent aborted by user");
+                }
+                agent.abort();
+                eventQueue.clearResolver();
+            }
+        }
+        catch (error) {
+            console.error("[ai] Error during execution:", error);
+            yield formatErrorEvent(error);
+        }
+    }
+}
+//# sourceMappingURL=agent.executor.js.map

package/dist/agent/agent.model-resolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model resolver for Pi Agent
+ * Handles provider mapping and model resolution for different AI providers
+ */
+import { type Model, type Api, type KnownProvider } from "@mariozechner/pi-ai";
+/**
+ * Maps provider names to Pi AI known provider identifiers
+ */
+export declare const PROVIDER_NAME_TO_PI: Record<string, KnownProvider>;
+/**
+ * Determines the API type based on the provider's API URL
+ */
+export declare function determineApiType(apiUrl: string): "openai-completions" | "anthropic-messages";
+/**
+ * Resolves a model configuration for the Pi Agent
+ * First attempts to use known providers from pi-ai registry,
+ * then falls back to creating a custom model configuration
+ */
+export declare function resolveModel(providerName: string, modelId: string, providerConfig: {
+    api: string | undefined;
+}): Model<Api>;
+//# sourceMappingURL=agent.model-resolver.d.ts.map