@tomsun28/pizza 0.1.0 → 0.1.1

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

@@ -0,0 +1,202 @@
+/**
+ * Agent Types — pizza's own message / tool / state model.
+ *
+ * Built on top of pi-ai's primitives (`UserMessage`, `AssistantMessage`,
+ * `ToolResultMessage`, `Tool`, `Model`) without carrying the old standalone
+ * agent-core package boundary.
+ *
+ * This module is the new canonical home for agent shape definitions.
+ * Callers should import from here.
+ */
+import type { AssistantMessage, AssistantMessageEvent, Context, ImageContent, Message, Model, SimpleStreamOptions, streamSimple, TextContent, ThinkingLevel as AiThinkingLevel, Tool, ToolResultMessage, UserMessage } from "@earendil-works/pi-ai/compat";
+import type { Static, TSchema } from "@sinclair/typebox";
+export type { AssistantMessage, AssistantMessageEvent, ImageContent, Message, Model, TextContent, Tool, ToolResultMessage, UserMessage, };
+/** Controls whether a tool runs sequentially or in parallel with other tool calls. */
+export type ToolExecutionMode = "sequential" | "parallel";
+export type ThinkingLevel = "off" | AiThinkingLevel;
+/** A bash execution message (recorded by the runtime, not produced by the LLM). */
+export interface BashExecutionMessage {
+    role: "bashExecution";
+    command: string;
+    /** Combined stdout+stderr output. */
+    output: string;
+    exitCode: number | undefined;
+    /** Whether the command was cancelled/aborted. */
+    cancelled: boolean;
+    /** Whether the output was truncated. */
+    truncated: boolean;
+    timestamp: number;
+    /** Path to full output file when truncated. */
+    fullOutputPath?: string;
+    /** Whether to exclude from LLM context. */
+    excludeFromContext?: boolean;
+    /** Separated stdout (when available). */
+    stdout?: string;
+    /** Separated stderr (when available). */
+    stderr?: string;
+}
+/** A summary inserted by compaction. */
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    tokensBefore: number;
+    timestamp: number;
+}
+/** A branch summary inserted when switching branches. */
+export interface BranchSummaryMessage {
+    role: "branchSummary";
+    summary: string;
+    /** Source branch/entry id. */
+    fromId?: string;
+    timestamp: number;
+}
+/** A custom extension-provided message. Generic over the structured payload type. */
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    /** Discriminator for the extension to identify its own custom messages. */
+    customType: string;
+    /** Content visible to the LLM when this message is included in context. */
+    content: string | (TextContent | ImageContent)[];
+    /** Optional UI-only display text or boolean flag. */
+    display?: string | boolean;
+    /** Arbitrary structured payload for tooling / persistence. */
+    details?: T;
+    timestamp: number;
+}
+export type AgentMessage = Message | BashExecutionMessage | CompactionSummaryMessage | BranchSummaryMessage | CustomMessage;
+/** Tool execution result returned to the LLM. */
+export interface AgentToolResult<T = unknown> {
+    /** Text or image content returned to the model. */
+    content: (TextContent | ImageContent)[];
+    /** Optional structured payload for logs/UI. */
+    details?: T;
+}
+/** Optional streaming-update callback. */
+export type AgentToolUpdateCallback<T = unknown> = (partial: AgentToolResult<T>) => void;
+/** Pizza's tool definition. */
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unknown> extends Tool<TParameters> {
+    /** Controls whether a tool runs sequentially or in parallel with other tool calls. */
+    executionMode?: ToolExecutionMode;
+    /** Optional shim for raw tool-call arguments before schema validation. */
+    prepareArguments?: (args: unknown) => Static<TParameters>;
+    /** Execute the tool call. Throw on failure. */
+    execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+}
+export interface AgentState {
+    /** System prompt sent with each model request. */
+    systemPrompt: string;
+    /** Active model used for future turns. */
+    model: Model<any> | undefined;
+    /** Requested reasoning level for future turns. */
+    thinkingLevel: ThinkingLevel;
+    /** Available tools. */
+    tools: AgentTool<any>[];
+    /** Conversation transcript. */
+    messages: AgentMessage[];
+    /** True while the agent is processing a prompt. */
+    isStreaming: boolean;
+    /** Tool call ids currently executing. */
+    pendingToolCalls: ReadonlySet<string>;
+    /** Error message from the most recent failed turn. */
+    errorMessage?: string;
+}
+/** Type guard: is this a pi-ai LLM message (user / assistant / toolResult)? */
+export declare function isLlmMessage(msg: AgentMessage): msg is Message;
+/** Filter pizza-specific messages, keep only those the LLM can consume. */
+export declare function toLlmMessages(messages: AgentMessage[]): Message[];
+/** Events emitted during agent execution. */
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+    partialResult: any;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError: boolean;
+};
+/**
+ * Stream function used by the agent loop.
+ *
+ * Mirrors pi-ai's `streamSimple` shape so that pi-ai can be plugged in directly.
+ */
+export type StreamFn = (...args: Parameters<typeof streamSimple>) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;
+/** A single tool-call content block emitted by an assistant message. */
+export type AgentToolCall = Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>;
+/** Result returned from `beforeToolCall`. */
+export interface BeforeToolCallResult {
+    block?: boolean;
+    reason?: string;
+}
+/** Partial override returned from `afterToolCall`. */
+export interface AfterToolCallResult {
+    content?: (TextContent | ImageContent)[];
+    details?: unknown;
+    isError?: boolean;
+}
+/** Context passed to `beforeToolCall`. */
+export interface BeforeToolCallContext {
+    assistantMessage: AssistantMessage;
+    toolCall: AgentToolCall;
+    args: unknown;
+    context: AgentContext;
+}
+/** Context passed to `afterToolCall`. */
+export interface AfterToolCallContext {
+    assistantMessage: AssistantMessage;
+    toolCall: AgentToolCall;
+    args: unknown;
+    result: AgentToolResult<any>;
+    isError: boolean;
+    context: AgentContext;
+}
+/** Context snapshot passed into the low-level agent loop. */
+export interface AgentContext {
+    systemPrompt: string;
+    messages: AgentMessage[];
+    tools?: AgentTool<any>[];
+}
+/** Configuration for one agent loop run. */
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    model: Model<any>;
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    toolExecution?: ToolExecutionMode;
+    beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+}
+export type { Context };

package/dist/core/agent/types.js

@@ -0,0 +1,51 @@
+/**
+ * Agent Types — pizza's own message / tool / state model.
+ *
+ * Built on top of pi-ai's primitives (`UserMessage`, `AssistantMessage`,
+ * `ToolResultMessage`, `Tool`, `Model`) without carrying the old standalone
+ * agent-core package boundary.
+ *
+ * This module is the new canonical home for agent shape definitions.
+ * Callers should import from here.
+ */
+// ============================================================================
+// Helpers
+// ============================================================================
+/** Type guard: is this a pi-ai LLM message (user / assistant / toolResult)? */
+export function isLlmMessage(msg) {
+    return msg.role === "user" || msg.role === "assistant" || msg.role === "toolResult";
+}
+/** Filter pizza-specific messages, keep only those the LLM can consume. */
+export function toLlmMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (isLlmMessage(m)) {
+            out.push(m);
+        }
+        else if (m.role === "compactionSummary" || m.role === "branchSummary") {
+            // Inject summaries as a user message so the LLM sees them.
+            out.push({
+                role: "user",
+                content: `[Previous context summary]\n${m.summary}`,
+                timestamp: m.timestamp,
+            });
+        }
+        else if (m.role === "bashExecution") {
+            out.push({
+                role: "user",
+                content: `[Bash command executed]\n$ ${m.command}\n` +
+                    (m.output ? `output:\n${m.output}\n` : "") +
+                    `exit code: ${m.exitCode}`,
+                timestamp: m.timestamp,
+            });
+        }
+        else if (m.role === "custom") {
+            out.push({
+                role: "user",
+                content: m.content,
+                timestamp: m.timestamp,
+            });
+        }
+    }
+    return out;
+}

package/dist/core/auth-storage.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Credential storage for API keys and OAuth tokens.
+ * Handles loading, saving, and refreshing credentials from auth.json.
+ *
+ * Uses file locking to prevent race conditions when multiple Pizza instances
+ * try to refresh tokens simultaneously.
+ */
+import { type OAuthCredentials, type OAuthLoginCallbacks, type OAuthProviderId } from "@earendil-works/pi-ai/compat";
+export type ApiKeyCredential = {
+    type: "api_key";
+    key: string;
+};
+export type OAuthCredential = {
+    type: "oauth";
+} & OAuthCredentials;
+export type AuthCredential = ApiKeyCredential | OAuthCredential;
+export type AuthStorageData = Record<string, AuthCredential>;
+type LockResult<T> = {
+    result: T;
+    next?: string;
+};
+export interface AuthStorageBackend {
+    withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
+    withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T>;
+}
+export declare class FileAuthStorageBackend implements AuthStorageBackend {
+    private authPath;
+    constructor(authPath?: string);
+    private ensureParentDir;
+    private ensureFileExists;
+    private acquireLockSyncWithRetry;
+    withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
+    withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T>;
+}
+export declare class InMemoryAuthStorageBackend implements AuthStorageBackend {
+    private value;
+    withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
+    withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T>;
+}
+/**
+ * Credential storage backed by a JSON file.
+ */
+export declare class AuthStorage {
+    private storage;
+    private data;
+    private runtimeOverrides;
+    private fallbackResolver?;
+    private loadError;
+    private errors;
+    private constructor();
+    static create(authPath?: string): AuthStorage;
+    static fromStorage(storage: AuthStorageBackend): AuthStorage;
+    static inMemory(data?: AuthStorageData): AuthStorage;
+    /**
+     * Set a runtime API key override (not persisted to disk).
+     * Used for CLI --api-key flag.
+     */
+    setRuntimeApiKey(provider: string, apiKey: string): void;
+    /**
+     * Remove a runtime API key override.
+     */
+    removeRuntimeApiKey(provider: string): void;
+    /**
+     * Set a fallback resolver for API keys not found in auth.json or env vars.
+     * Used for custom provider keys from models.json.
+     */
+    setFallbackResolver(resolver: (provider: string) => string | undefined): void;
+    private recordError;
+    private parseStorageData;
+    /**
+     * Reload credentials from storage.
+     */
+    reload(): void;
+    private persistProviderChange;
+    /**
+     * Get credential for a provider.
+     */
+    get(provider: string): AuthCredential | undefined;
+    /**
+     * Set credential for a provider.
+     */
+    set(provider: string, credential: AuthCredential): void;
+    /**
+     * Remove credential for a provider.
+     */
+    remove(provider: string): void;
+    /**
+     * List all providers with credentials.
+     */
+    list(): string[];
+    /**
+     * Check if credentials exist for a provider in auth.json.
+     */
+    has(provider: string): boolean;
+    /**
+     * Check if any form of auth is configured for a provider.
+     * Unlike getApiKey(), this doesn't refresh OAuth tokens.
+     */
+    hasAuth(provider: string): boolean;
+    /**
+     * Get all credentials (for passing to getOAuthApiKey).
+     */
+    getAll(): AuthStorageData;
+    drainErrors(): Error[];
+    /**
+     * Login to an OAuth provider.
+     */
+    login(providerId: OAuthProviderId, callbacks: OAuthLoginCallbacks): Promise<void>;
+    /**
+     * Logout from a provider.
+     */
+    logout(provider: string): void;
+    /**
+     * Refresh OAuth token with backend locking to prevent race conditions.
+     * Multiple Pizza instances may try to refresh simultaneously when tokens expire.
+     */
+    private refreshOAuthTokenWithLock;
+    /**
+     * Get API key for a provider.
+     * Priority:
+     * 1. Runtime override (CLI --api-key)
+     * 2. API key from auth.json
+     * 3. OAuth token from auth.json (auto-refreshed with locking)
+     * 4. Environment variable
+     * 5. Fallback resolver (models.json custom providers)
+     */
+    getApiKey(providerId: string, options?: {
+        includeFallback?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * Get all registered OAuth providers
+     */
+    getOAuthProviders(): import("@earendil-works/pi-ai/compat").OAuthProviderInterface[];
+}
+export {};