@dugleelabs/copair 1.9.0 → 1.10.0

package/dist/api.d.ts

@@ -74,8 +74,8 @@ declare const ProviderConfigSchema: z.ZodObject<{
         supports_tool_calling: z.ZodOptional<z.ZodBoolean>;
         supports_streaming: z.ZodOptional<z.ZodBoolean>;
         tool_call_format: z.ZodOptional<z.ZodEnum<{
-            dsml: "dsml";
             "qwen-xml": "qwen-xml";
+            dsml: "dsml";
             "fenced-block": "fenced-block";
         }>>;
     }, z.core.$strip>>;
@@ -107,8 +107,8 @@ declare const CopairConfigSchema: z.ZodObject<{
             supports_tool_calling: z.ZodOptional<z.ZodBoolean>;
             supports_streaming: z.ZodOptional<z.ZodBoolean>;
             tool_call_format: z.ZodOptional<z.ZodEnum<{
-                dsml: "dsml";
                 "qwen-xml": "qwen-xml";
+                dsml: "dsml";
                 "fenced-block": "fenced-block";
             }>>;
         }, z.core.$strip>>;
@@ -186,6 +186,42 @@ declare const CopairConfigSchema: z.ZodObject<{
         }>>>;
         max_tool_calls: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    model_overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        tier: z.ZodOptional<z.ZodEnum<{
+            small: "small";
+            large: "large";
+        }>>;
+        context_window: z.ZodOptional<z.ZodNumber>;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        native_tool_calling: z.ZodOptional<z.ZodEnum<{
+            reliable: "reliable";
+            unreliable: "unreliable";
+            none: "none";
+        }>>;
+        preferred_format: z.ZodOptional<z.ZodEnum<{
+            "qwen-xml": "qwen-xml";
+            dsml: "dsml";
+            "fenced-block": "fenced-block";
+            native: "native";
+        }>>;
+        recommended_harness: z.ZodOptional<z.ZodObject<{
+            enable_small_model_harness: z.ZodOptional<z.ZodBoolean>;
+            max_turns: z.ZodOptional<z.ZodNumber>;
+            max_tool_calls: z.ZodOptional<z.ZodNumber>;
+            inject_format_reminder_every_turn: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        read: z.ZodOptional<z.ZodObject<{
+            overflow_lines: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        bash: z.ZodOptional<z.ZodObject<{
+            overflow_tokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        grep: z.ZodOptional<z.ZodObject<{
+            default_max_results: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 type CopairConfig = z.infer<typeof CopairConfigSchema>;
 type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
@@ -206,9 +242,29 @@ interface ToolDefinition {
     description: string;
     inputSchema: Record<string, unknown>;
 }
+/**
+ * spec 029 (F-15b): declarative side-effects a tool surfaces to the agent loop,
+ * which dispatches each to the matching `Renderer.show*` method. Keeps tools
+ * renderer-free; additive (tools emitting no events are unaffected).
+ */
+type ToolEvent = {
+    kind: 'bash_truncated';
+    label: 'stdout' | 'stderr';
+    originalTokens: number;
+} | {
+    kind: 'read_overflow';
+    filePath: string;
+    lineCount: number;
+} | {
+    kind: 'grep_overflow';
+    pattern: string;
+    maxResults: number;
+};
 interface ToolResult {
     content: string;
     isError?: boolean;
+    /** spec 029 (F-15b): overflow/truncation events for the agent to dispatch. */
+    events?: ToolEvent[];
 }
 interface Tool {
     definition: ToolDefinition;
@@ -375,6 +431,38 @@ interface AgentBridgeEvents {
     'unclear-signal': (data: {
         message: string;
     }) => void;
+    /** Spec 029 F-13: loop guard nudged the model after 2 identical tool repeats. */
+    'loop-nudge': (data: {
+        message: string;
+    }) => void;
+    /** Spec 029 F-13: loop guard halted the agent turn after 3 identical tool repeats. */
+    'loop-halt': (data: {
+        reason: string;
+    }) => void;
+    /** Spec 029 F-14: format-repair retry fired after a parseStrict failure. */
+    'format-repair': (data: {
+        specific_issue: string;
+    }) => void;
+    /** Spec 029 F-14: format-repair retries exhausted; agent turn breaks. */
+    'format-repair-exhausted': (data: {
+        specific_issue: string;
+        message: string;
+    }) => void;
+    /** Spec 029 F-15b: bash stdout/stderr was head+tail truncated by the overflow helper. */
+    'bash-truncated': (data: {
+        label: 'stdout' | 'stderr';
+        originalTokens: number;
+    }) => void;
+    /** Spec 029 F-15b: `read` refused to surface a large file without an explicit `limit`. */
+    'read-overflow': (data: {
+        filePath: string;
+        lineCount: number;
+    }) => void;
+    /** Spec 029 F-15b: `grep` capped at `max_results` with at least one more match available. */
+    'grep-overflow': (data: {
+        pattern: string;
+        maxResults: number;
+    }) => void;
 }
 type EventName = keyof AgentBridgeEvents;
 /**
@@ -555,6 +643,8 @@ interface ExecutionResult {
     denied?: boolean;
     /** Actual tool execution time in ms (excludes approval prompt wait). */
     _durationMs?: number;
+    /** Spec 029 F-15b: declarative side-effects (overflow/truncation) the agent dispatches. */
+    events?: ToolEvent[];
 }
 /**
  * Executes tools on behalf of the agent loop.
@@ -740,7 +830,37 @@ interface ParsedToolCall {
     id: string;
     name: string;
     arguments: string;
+    /** Provider-specific metadata (e.g. native tool-call IDs). Passed through opaquely. */
+    metadata?: Record<string, unknown>;
 }
+/**
+ * spec 029 (F-14): structured parse error returned by `parseStrict`. The
+ * `specific_issue` enum drives the repair-message template and the renderer's
+ * format-repair event.
+ */
+interface ParseError {
+    kind: 'parse';
+    /** Human-readable error message — surfaced to the model in the repair prompt. */
+    message: string;
+    /** A canonical example of valid markup for this formatter (≈formatter.exampleCall()). */
+    expected_format_example: string;
+    /** The part of the model's output that failed to parse, ≤200 chars. */
+    offending_substring: string;
+    specific_issue: 'unknown_tool' | 'bad_arg_type' | 'unclosed_tag' | 'invalid_json' | 'other';
+}
+/**
+ * spec 029 (F-14): non-throwing parse result. Success carries the same shape as
+ * legacy `parse(text)` so call sites can swap in `parseStrict` without
+ * remapping fields.
+ */
+type ParseResult = {
+    ok: true;
+    toolCalls: ParsedToolCall[];
+    remainingText: string;
+} | {
+    ok: false;
+    error: ParseError;
+};
 interface ToolCallFormatter {
     readonly name: string;
     readonly markupPattern: RegExp;
@@ -759,13 +879,20 @@ interface ToolCallFormatter {
     buildSystemPrompt(tools: ToolDefinition$1[]): string;
     /** Return a minimal example tool call in this formatter's markup language. */
     exampleCall(): string;
+    /**
+     * spec 029 (F-14): non-throwing variant returning a structured error on parse
+     * failure. Optional — third-party formatters without it degrade through
+     * `parseWithStrictFallback`; the built-in formatters implement it natively.
+     */
+    parseStrict?(text: string): ParseResult;
 }
 
 type FormatName = 'dsml' | 'qwen-xml' | 'fenced-block';
 
 declare class SmallModelHarness {
     readonly isSmallModel: boolean;
-    private config;
+    private readonly modelId;
+    private readonly config;
     constructor(modelId: string, config?: SmallModelsConfig, forceOverride?: boolean);
     get maxToolCalls(): number;
     getSystemPromptAddition(): string | null;
@@ -797,6 +924,7 @@ declare class Agent {
     private textFilter;
     private pluginManager?;
     private harness?;
+    private loopGuard;
     constructor(provider: Provider, model: string, toolRegistry: ToolRegistry, executor: ToolExecutor, options?: AgentOptions);
     get model(): string;
     getConversation(): ConversationManager;
@@ -813,6 +941,13 @@ declare class Agent {
         /** Input tokens from the last API call — reflects actual context window usage. */
         lastInputTokens: number;
     }>;
+    /**
+     * spec 029 (F-14): wrap a single provider streaming call so it's callable
+     * from both the outer iteration loop and the inner format-repair retry loop.
+     * Resets the streaming markup filter so `suppressAfterMatch` formatters scope
+     * to one response.
+     */
+    private streamOnce;
     /** Prompt the user for input and return their answer (used by ask_user intercept). */
     private collectUserAnswer;
     /**