# Zyquo Agent — Provider Reuse (Phase 0.B, contract for the provider layer)

Compiled 2026-07-30 from an in-depth study of the sibling Zyquo Cloud repository at /Users/simon-pierreboucher/Desktop/zyquo-cloud (source files under Sources/ZyquoCloud/, plus docs/PROVIDERS.md — Cloud's own live-probed provider research — and docs/VERIFICATION.md).

Rule of this document: Zyquo Agent calls every model exactly the way Zyquo Cloud does. The files listed in §1 are ported (near-)verbatim; the only addition is a normalized tool-calling interface layered onto the same ProviderClient protocol (§5–§6). The model picker offers the same catalog as Cloud (§2) with the agent-capable subset marked and defaulted (§3). The key vault is byte-format-compatible in design (§4).

# 1. How each provider's API is called (Cloud's provider layer, file by file)

# 1.1 Architecture overview

Cloud's entire provider layer is four files plus shared networking and models:

Key finding: there is NO GeminiClient in Zyquo Cloud. Gemini is served through Google's OpenAI-compatibility endpoint (https://generativelanguage.googleapis.com/v1beta/openai, Bearer auth) via OpenAICompatibleClient. Cloud's research (docs/PROVIDERS.md §Gemini, verified live) confirms the compat endpoint supports chat + streaming + function calling (tools) + structured outputs + vision + reasoning_effort. Zyquo Agent's CLAUDE.md sketch lists a GeminiClient.swift; per this study the correct, Cloud-identical approach is to keep Gemini on the compat endpoint (Gemini tool calls then arrive as standard OpenAI tool_calls, one uniform streaming path). A native GeminiClient (functionCall/functionResponse parts) is only needed if Phase 7 finds compat-endpoint tool streaming inadequate — see §5.4.

# 1.2 Core protocol types (ProviderProtocol.swift)

struct ChatRequest {                    // provider-agnostic; clients translate to wire format
    var model: AIModel
    var systemPrompt: String?
    var messages: [Message]
    var parameters: ChatParameters
    var stream: Bool = true
}

enum ChatEvent {                        // streamed back to the UI
    case reasoningDelta(String)
    case textDelta(String)
    case citations([Citation])
    case usage(TokenUsage)
    case finished(reason: String?)
}

protocol ProviderClient {
    var providerID: ProviderID { get }
    func streamChat(_ request: ChatRequest, apiKey: String) -> AsyncThrowingStream<ChatEvent, Error>
    func complete(_ request: ChatRequest, apiKey: String) async throws -> Message
    func listModelIDs(apiKey: String) async throws -> [String]
}
// + extension ProviderClient.testKey(_:fallbackModel:) -> TimeInterval
//   (uses /models when supported, else a 16-token "Reply with exactly: OK" completion;
//    fallbackModel needed only for Perplexity, which has no /models endpoint)

ProviderError cases: invalidAPIKey, rateLimited(retryAfter:), serverError(status:message:), badRequest, networkError, invalidResponse, missingAPIKey, noModelAvailable, cancelled — each with a polished errorDescription. ProviderError.from(status:body:provider:) maps 401/403→invalidAPIKey, 429→rateLimited, 400/404/422→badRequest, else serverError, and extractMessage(from:) tolerates all observed error shapes: {"error":{"message":…}}, {"error":"…"}, {"message":…}, {"detail":…}, and Gemini's array-wrapped errors.

# 1.3 Provider table (from ProviderID.swift, all verified live by Cloud on 2026-07-30)

wireFormat: .anthropicMessages for .anthropic, .openAIChatCompletions for everything else. Env-var names used by the verify harness (reuse for Agent's Phase 7): OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GEMINI_API_KEY, DASHSCOPE_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY, PERPLEXITY_API_KEY, TOGETHER_API_KEY, DEEPINFRA_API_KEY, CEREBRAS_API_KEY.

# 1.4 OpenAICompatibleClient — request/response design

• Endpoint: POST {base}/chat/completions (path appended with appendingPathComponent, preserving base paths like /compatible-mode/v1 and /v1beta/openai); GET {base}/models.
• Request wire types (private Encodable structs): WireRequest (model, messages, stream, stream_options, temperature, top_p, max_tokens, max_completion_tokens, frequency_penalty, presence_penalty, reasoning_effort, enable_thinking), WireMessage (role + content), WireContent (plain string OR parts array), WirePart ({"type":"text"} / {"type":"image_url","image_url":{"url":"data:…;base64,…"}}).
• Parameter gating: every optional field is included only if the model's ParameterSupport allows it (providers 400 on unknown/unsupported params). Notable: usesMaxCompletionTokens → send max_completion_tokens instead of max_tokens (OpenAI reasoning models, Kimi K-series, Cerebras); Mistral maps reasoning_effort medium→"high", low→"none" (only accepts high/none); Qwen enable_thinking is only legal when stream:true.
• stream_options: {"include_usage": true} is sent for openai/xai/gemini/deepseek/kimi/ together/cerebras/custom; omitted for mistral (rejects unknown params), qwen, deepinfra, perplexity (usage included automatically).
• Response wire types (private Decodable): WireChunk (choices, usage, plus Perplexity citations + search_results), WireChoice (delta for streaming, message for non-streaming, bare text for Together's completions-style streams, finish_reason), WireDelta (content, reasoning_content, reasoning; custom init(from:) also decodes Mistral's content-array ThinkChunk/TextChunk shape), WireUsage (prompt_tokens/completion_tokens/completion_tokens_details.reasoning_tokens).
• Streaming: consumes StreamingService.sseEvents, stops on data: [DONE], silently tolerates undecodable keep-alive chunks, yields .reasoningDelta (from reasoning_content or reasoning), .textDelta (from delta.content or choice.text), .citations (once, Perplexity), .usage, then .finished(reason: finish_reason).
• complete: if parameterSupport.requiresStreaming (Qwen qwq/qvq, several Together/ DeepInfra-hosted models reject stream:false), it aggregates the stream instead (completeViaStream); otherwise plain POST via StreamingService.postJSON (3 attempts, exponential backoff on 429/5xx honoring Retry-After).
• listModelIDs: decodes {"data":[{"id"}]} OR Together's bare [{"id"}]; strips Gemini's models/ prefix.
• Attachments: text files are injected inline as fenced blocks; images become base64 data-URI image_url parts (user messages on vision models only).

# 1.5 AnthropicClient — native Messages API

• Endpoint: POST /v1/messages; headers x-api-key: <key>, anthropic-version: 2023-06-01, Content-Type: application/json. GET /v1/models?limit=100 for listing.
• Request: WireRequest — model, mandatory max_tokens (default 8192 when unset), messages (block-structured: WireMessage{role, content:[WireBlock]} with .text / .image(base64 source) blocks; empty text becomes " "), top-level system string, stream, temperature/top_p (gated — Claude 4.7+/5 reject them, encoded per-model in ParameterSupport), and thinking: {"type":"enabled","budget_tokens":8000} / {"type":"disabled"} when thinkingToggle is supported. (Cloud's PROVIDERS.md documents the full per-model thinking matrix, incl. {"type":"adaptive"} for 4.6+ and "omit entirely" for claude-fable-5 where thinking is always on.)
• Streaming (named SSE events, no [DONE]): the client switches on sse.event ?? decoded.type:
  • message_start → capture message.usage.input_tokens
  • content_block_delta → delta.text → .textDelta; delta.thinking → .reasoningDelta
  • message_delta → usage.output_tokens + delta.stop_reason
  • error → mid-stream error surfaced as ProviderError.serverError
  • message_stop / ping / content_block_start / content_block_stop → currently ignored (Agent's port MUST handle content_block_start/stop + input_json_delta — §5.1)
• Non-streaming: decodes content: [Block{type,text,thinking}], joins text blocks into the message body and thinking blocks into reasoning; reads stop_reason and usage.

# 1.6 StreamingService — shared SSE plumbing (port unchanged)

• Shared URLSession: timeoutIntervalForRequest = 120, timeoutIntervalForResource = 900, User-Agent: ZyquoCloud/1.0 (macOS) (rename to ZyquoAgent/1.0 (macOS)).
• SSEParser: incremental line parser handling event:/data: fields, multi-line data: joins, : comment/keep-alive lines (DeepSeek sends : keep-alive), CRLF, and a trailing flush for streams ending without a final blank line. Critical detail preserved: URLSession.AsyncBytes.lines skips empty lines (the SSE event separators) — the byte stream is split manually on \n.
• sseEvents(for:provider:): on non-2xx, reads the full error body and throws the typed ProviderError; wraps CancellationError → .cancelled; onTermination cancels the task (this is what makes the Stop button actually abort the HTTP stream — same mechanism will make Agent runs cancellable).
• Unit tests exist in Tests/ZyquoCloudTests/SSEParserTests.swift — port them.

# 2. The full model catalog (from Services/ModelCatalogData.swift, generated 2026-07-30)

170 built-in models across 12 providers. Zyquo Agent ships this exact catalog. Legend — caps: V vision, T tools/function-calling, R reasoning output, J JSON mode, C citations; price = USD per 1M tokens in/out (— = not published); ⭐ = isRecommended, 🕰 = isLegacy; 🤖 = agent-capable (the subset per §3); bold 🤖 entries are the suggested per-provider agent defaults. Param notes: mct = uses max_completion_tokens, re = reasoning_effort, tt = thinking toggle, rs = requiresStreaming, no-t/p = temperature & top_p rejected.

# OpenAI (27)

# Anthropic (11)

# xAI / Grok (5)

# Mistral (10)

# Google Gemini (14) — served via the OpenAI-compat endpoint

All Gemini chat models take reasoning_effort on the compat endpoint.

# Alibaba Qwen / DashScope (32)

# DeepSeek (2)

Both support up to 128 functions per request; finish_reason may be the DeepSeek-specific insufficient_system_resource ("servers overloaded").

# Kimi / Moonshot (12)

# Perplexity (4) — entire provider excluded from the agent-capable subset

Cloud's research is explicit: "no vision/image input; no tool/function calling on the Sonar chat API". These are web-search answer engines. Keep them in the picker (same list as Cloud) but never selectable as the agent driver — or gray them out with an explanation.

# Together AI (16)

Together quirks preserved in the client: bare-array /models, completions-style choices[].text streaming for some models, extra finish_reason: "eos".

# DeepInfra (34)

(Note: google/gemma-4-31B-it was removed from DeepInfra on 2026-07-30 — endpoint hangs. DeepInfra-proxied Claude/Gemini speak the plain OpenAI schema, no native thinking config.)

# Cerebras (3)

# 3. The agent-capable subset (what Zyquo Agent marks and defaults to)

Criteria (from the catalog's capability flags + Cloud's per-provider research):

1. capabilities.tools == true — native function calling, live-verified by Cloud;
2. strong multi-step reasoning (flagship/frontier tier, or agentic-coding tuned);
3. context window ≥ ~128K (agent transcripts with tool results grow fast);
4. reliable streaming of tool-call arguments;
5. not legacy, not a niche tuning (chat-alias, vision-only, search-only).

Counts: ~70 of the 170 catalog models are marked 🤖 agent-capable (per-model marks in the §2 tables). Everything else remains in the picker (same list as Cloud) but is visually de-emphasized and produces a "not recommended for agent tasks" hint if selected.

Overall default agent model: claude-sonnet-5 (Anthropic) — 1M context, adaptive thinking, best-in-class tool use, and the Messages API's tool_use blocks are the most explicit tool-calling contract of the twelve providers. Per-provider defaults are bolded in §2.

Recommended top tier (surface first in the model chip): claude-sonnet-5, claude-opus-5, gpt-5.6-terra, gpt-5.6-sol, gemini-3.6-flash, grok-4.5, grok-code-fast-1, deepseek-v4-pro, kimi-k3, kimi-k2.7-code, qwen3.7-max, mistral-medium-latest, Cerebras gpt-oss-120b (speed king for tight loops).

Excluded from agent use, with reasons:

All exclusions are soft (UI de-emphasis + default filter), except Perplexity + tools:false models which are hard exclusions — the agent loop refuses to start with a model whose capabilities.tools == false.

Phase 7 contract: every 🤖 model above gets the scripted (a) schema-receipt, (b) valid tool call for "list the files in the workspace using the shell tool", (c) tool_result consumption, (d) streaming test — following the VerifyHarness pattern (Sources/ZyquoCloud/Verify/VerifyHarness.swift): env keys, per-model results table, written to docs/VERIFICATION.md.

# 4. SecureKeyStore — the AES-256-GCM vault (NO Keychain), reused verbatim

Source: zyquo-cloud/Sources/ZyquoCloud/Services/SecureKeyStore.swift (+ tests in Tests/ZyquoCloudTests/SecureKeyStoreTests.swift). Port both.

• File: ~/Library/Application Support/ZyquoCloud/vault.zq → Agent uses ~/Library/Application Support/ZyquoAgent/vault.zq (via PersistenceService.shared.rootDirectory, which is the app-support folder named after the app).
• Blob layout: [salt 32 B][AES-GCM combined: nonce 12 B ‖ ciphertext ‖ tag 16 B]. Written atomically with .completeFileProtection. Load validates count > 32 + 12 + 16 and throws VaultError.corrupted on any decrypt failure.
• Plaintext: JSON [String: String] — provider rawValue → API key ({"openai":"sk-…","anthropic":"sk-ant-…", …}).
• Key derivation: HKDF<SHA256>.deriveKey(ikm: machineEntropy ‖ pepper, salt: vault salt, info: "ZyquoCloud.vault.v1", outputByteCount: 32) → AES.GCM SymmetricKey.
  • machineEntropy = IOPlatformUUID (IOKit IOPlatformExpertDevice / kIOPlatformUUIDKey) ‖ NSHomeDirectory() — binds the vault to machine + account. Injectable closure for tests.
  • pepper = 30 compiled-in bytes XOR 0x5A, assembled at runtime (never a literal in the binary).
  • Re-saves reuse the existing salt (existingSalt()) so derivation stays stable.
• API: loadKeys(), saveKeys(_:), key(for: ProviderID), setKey(_:for:), deleteKey(for:), static redacted(_:) → "••••abcd" (last 4 chars only, everywhere in UI).
• Agent decisions: keep the same design and blob format; change only the HKDF info string to "ZyquoAgent.vault.v1" and (recommended) a distinct pepper — the two apps keep separate vaults with an identical user experience; keys are entered per-app (a Cloud vault cannot be decrypted by Agent by design — machine-bound, app-info-bound). Keep the rules: decrypt on demand only, never log, never plaintext on disk, no Keychain.
• The SwiftUI wrapper ViewModels/KeyVaultStore.swift (per-provider key status, test-key latency chip) is also reusable for the Settings → Providers & Keys tab.

# 5. Provider-specific tool-calling quirks (what the normalized interface must absorb)

Zyquo Cloud declares capabilities.tools per model but never sends tools — Zyquo Agent adds that. Cloud's docs/PROVIDERS.md already documents each provider's tool wire format (request schema sections + finish_reason inventories). Consolidated contract:

# 5.1 Anthropic (native Messages API) — the odd one out

• Declare: top-level tools: [{name, description, input_schema: <JSON Schema>}]; tool_choice: {"type":"auto"|"any"|"tool","name":…} (+ disable_parallel_tool_use).
• Model calls a tool: assistant content contains a {"type":"tool_use","id":"toolu_…","name":…,"input":{…}} block; stop_reason == "tool_use".
• Streaming: content_block_start announces the tool_use block (with id + name, empty input); arguments then stream as content_block_delta with {"type":"input_json_delta","partial_json":"…"} fragments — accumulate per block index and JSON-parse at content_block_stop. (Cloud's client currently ignores content_block_start/stop and input_json_delta — the port must add these three cases.)
• Return the result: append a user message whose content is [{"type":"tool_result","tool_use_id":"toolu_…","content":"…", "is_error":bool}] — NOT a special role. Multiple tool_results go in one user turn for parallel calls. Assistant thinking blocks must be passed back unchanged on the same model.
• Done signal: stop_reason: "end_turn" (also max_tokens, stop_sequence, pause_turn, refusal — Fable 5/Opus 5 can refuse with HTTP 200 — model_context_window_exceeded). No [DONE] sentinel; stream ends at message_stop.
• Other quirks (already in Cloud's code/notes): max_tokens mandatory; per-model thinking-config matrix (adaptive vs enabled+budget vs omit-for-Fable-5); temperature/top_p rejected on 4.7+/5; HTTP 529 overloaded_error retry; mid-stream error events.

# 5.2 OpenAI-compatible family (OpenAI, xAI, Mistral, Gemini-compat, Qwen, DeepSeek, Kimi, Together, DeepInfra, Cerebras, custom)

• Declare: tools: [{"type":"function","function":{name, description, parameters: <JSON Schema>}}]; tool_choice: "none"|"auto"|"required"|{"type":"function","function":{"name":…}} (Mistral additionally accepts "any"; default parallel_tool_calls: true on Mistral/Cerebras; Cerebras supports strict: true schemas).
• Model calls tools: assistant message carries tool_calls: [{id, type:"function", function:{name, arguments: "<JSON string>"}}]; finish_reason == "tool_calls".
• Streaming deltas: choices[].delta.tool_calls is an array of index-keyed fragments: first fragment for an index carries id + function.name, subsequent ones carry function.arguments string chunks. Accumulate per index, then JSON-parse each arguments string when the stream finishes (finish_reason:"tool_calls" or [DONE]).
• Return the result: append the assistant message with its tool_calls array intact, then one message per call: {"role":"tool","tool_call_id":…, "content":"<result string>"} (Kimi/DeepSeek/Mistral all follow this; name optionally included).
• Done signal: finish_reason: "stop" (length, content_filter; Together adds eos; DeepSeek adds insufficient_system_resource); stream terminates with data: [DONE].
• Per-provider notes already encoded or documented by Cloud:
  • OpenAI: reasoning models need max_completion_tokens and reject sampling params; ignore unknown obfuscation field in chunks.
  • Gemini (compat): tools/function-calling officially supported on the compat endpoint; ignore extra_content/thought_signature extras in deltas; /models IDs prefixed models/; Google Search grounding available via tools on Gemini 3+ (don't mix with function tools unless verified).
  • Mistral: content can be an array of ThinkChunk/TextChunk objects (handled in WireDelta.init(from:)); tool_choice: "any"; reasoning_effort only high/none.
  • Qwen/DashScope: enable_thinking only with stream:true; reasoning_content deltas; qwq/qvq reject non-streaming.
  • DeepSeek: reasoning_content deltas stream before content; thinking on by default on v4-flash; ≤128 tools; : keep-alive SSE comments.
  • Kimi: reasoning_content before content on K-series; built-in $web_search tool uses type:"builtin_function" (do NOT use for Agent — our tools are local); temperature unsupported on K-series (no-t/p + mct).
  • Together: some models stream completions-style choices[].text; bare-array /models; finish_reason:"eos".
  • Cerebras: max_completion_tokens required-style; strict:true tool schemas; gpt-oss-120b may emit malformed/hallucinated tool calls — validate arguments against the schema and re-prompt on failure (this validation belongs in the normalized layer for ALL providers).
  • Perplexity: no tools — hard-excluded (§3); citations/search_results fields must keep being tolerated by the decoder.
• Reasoning surfaces to keep uniform: delta.reasoning_content (DeepSeek/Qwen/Kimi/some DeepInfra), delta.reasoning (Together/Cerebras gpt-oss), Mistral ThinkChunk arrays, Anthropic thinking_delta, Perplexity inline <think> — all already normalized to ChatEvent.reasoningDelta by Cloud's clients; unchanged.

# 5.3 The normalized interface Zyquo Agent adds

Extend the ported types (one uniform surface; per-provider translation stays inside clients):

struct ToolSpec: Codable {              // handed to the client from ToolRegistry
    var name: String
    var description: String
    var parametersJSONSchema: String     // canonical JSON Schema (object) as a string
}

struct ToolCall: Codable, Identifiable, Hashable {
    var id: String                       // provider call id (toolu_… / call_…); synthesize for providers that omit it
    var name: String
    var argumentsJSON: String            // raw accumulated JSON string; parsed+validated by the loop
}

struct ToolResult: Codable {             // threaded back on the next request
    var toolCallID: String
    var content: String                  // stringified output (stdout/stderr summary, file text…)
    var isError: Bool
}

// ChatRequest additions
var tools: [ToolSpec] = []
var toolChoice: ToolChoice = .auto       // .auto / .none / .required / .named(String)

// Message additions (so history round-trips correctly per provider)
var toolCalls: [ToolCall]? = nil         // on assistant turns
var toolResults: [ToolResult]? = nil     // rendered as role:"tool" messages (OpenAI) or
                                         // tool_result user blocks (Anthropic) by the client

// ChatEvent additions
case toolCallStarted(index: Int, id: String, name: String)   // live chip in the UI
case toolCallArgumentsDelta(index: Int, delta: String)       // streamed args
case toolCalls([ToolCall])                                   // finalized, parsed set

.finished(reason:) is normalized by the client to a small enum surfaced alongside the raw string: endTurn (stop/end_turn/eos), toolUse (tool_calls/tool_use), maxTokens (length/max_tokens), refusal, other(String) — the AgentLoop branches only on this.

# 5.4 Gemini native (only if Phase 7 demands it)

If the compat endpoint's tool streaming proves insufficient, a native GeminiClient would use POST /v1beta/models/{model}:streamGenerateContent?alt=sse with x-goog-api-key, declare tools: [{functionDeclarations:[{name,description,parameters}]}] + toolConfig: {functionCallingConfig: {mode: AUTO|ANY|NONE, allowedFunctionNames}}, receive candidates[].content.parts[].functionCall {name,args} (complete JSON, not deltas), and reply with a user part functionResponse {name, response}; completion signaled by finishReason: "STOP". Not planned for the initial port — Cloud ships without it and all Gemini catalog models advertise tools on the compat endpoint.

# 6. Porting plan

Port verbatim (rename module header Zyquo Cloud → Zyquo Agent, ZyquoCloud strings → ZyquoAgent where they are app-facing: User-Agent, app-support folder, HKDF info, pepper):

Add new (Agent-only): ToolSpec/ToolCall/ToolResult types (§5.3); per-client tool encoding/decoding; argument-JSON validation against the declared schema with a re-prompt path (needed for gpt-oss-class models); the Agent/, Tools/, Execution/, Workspace/ layers per Phase 2 — none of which touch provider wire code.

Renames for the ZyquoAgent module: file headers to Zyquo Agent; ZyquoCloud → ZyquoAgent only in User-Agent, PersistenceService folder, HKDF info, pepper, and test module names. Wire formats, base URLs, headers, catalog IDs, error mapping, SSE parsing: unchanged — that is the whole point.

Invariants inherited from Cloud (do not regress):

• Decoders tolerate unknown fields and malformed keep-alive chunks; never crash a stream.
• Every optional request param is gated by ParameterSupport; never send unsupported params.
• Cancellation flows through AsyncThrowingStream.onTermination → Task.cancel() → HTTP abort.
• 429/5xx backoff on non-streaming calls; typed ProviderError with human-readable text.
• cheapestModel(for:) (non-reasoning preferred) for utility calls like auto-titles.
• Catalog (ModelCatalogData.swift) and this doc stay in sync with any Phase-7 findings.