spb/zyquo-agent Public MIT

1# Zyquo Agent — Build Plan & Phase Checkpoints23## Phase 0 — Research + Zyquo Cloud Study4- [x] 0.A Intensive web research → `docs/AGENT-RESEARCH.md` (413 lines, 79 citations: stop_reason-keyed loop, 3 provider wire formats, bash/file-edit tool design, auto-compaction @95% + MEMORY.md, workspace isolation, TodoWrite-style planning, deny→ask→allow policy engine, SWE-bench/Terminal-Bench eval)56**Phase 0 checkpoint (2026-07-30):** Both research docs complete. Key decisions locked: port Cloud's two-client provider layer (AnthropicClient + OpenAICompatibleClient, 12 providers, 170 models, ~70 agent-capable, default claude-sonnet-5) and add a normalized tool-calling interface absorbing the 3 wire dialects; agent loop is a stop_reason-keyed while-loop with Planner/MemoryManager/LoopGuard per AGENT-RESEARCH.md; PolicyEngine follows deny→ask→allow with destructive-pattern circuit breakers; SecureKeyStore vault format reused byte-compatible.7- [x] 0.B Study `~/Desktop/zyquo-cloud` → `docs/PROVIDER-REUSE.md` (12 providers / 2 clients: AnthropicClient + OpenAICompatibleClient incl. Gemini compat endpoint; 170-model catalog, ~70 agent-capable, default `claude-sonnet-5`; AES-256-GCM SecureKeyStore vault; 3 tool-calling wire dialects documented)89## Phase 1 — Project Setup (SPM, no Xcode IDE)10- [x] Package.swift, executable target `ZyquoAgent` (swift-markdown dep, test target)11- [x] Makefile (dev bundle, ad-hoc sign; SDKROOT pinned to MacOSX26.sdk — SDK 27 SwiftUI macros need Xcode), scripts/write-info-plist.sh (com.zyquo.agent, NSAppleEventsUsageDescription, developer-tools)12- [x] @main via synchronous Main enum (CLI modes: --run/--verify/--load-vault stubs), SwiftUI app shell + AppDelegate activation1314**Phase 1 checkpoint (2026-07-30):** `swift build -c release` clean (0 warnings), `make dev` assembles + ad-hoc signs `dist/Zyquo Agent.app`, app window shell launches. CLI scaffold (`AgentCLI`) ready to host the Phase 3 POC and Phase 7 harness.1516## Phase 2 — Architecture skeleton (folders per CLAUDE.md)17- [x] Providers/ + Models/ + Services/ ported from Zyquo Cloud (16 files: both clients + ChatEvent normalized tool-calling stream, 170-model catalog byte-identical, 80-model agent-capable set, SecureKeyStore vault at ~/Library/Application Support/ZyquoAgent/vault.zq)18- [x] DesignSystem/ ZyquoTheme (violet #7A5AF0 flagship), Components, AppearanceStore (violet/graphite/sky/emerald/amber)19- [x] Tools/Tool.swift protocol + ToolExecutionContext/Result, Agent/AgentStep.swift, Execution/PolicyEngine.swift skeleton (SafetyMode, ActionRequest, deny→ask→allow types, fail-closed default), Execution/AuditLog.swift (JSONL, actor)2021**Phase 2 checkpoint (2026-07-30):** Build clean, zero warnings. Key names locked: `ProviderClient`, `ChatRequest`/`ChatEvent`, `ToolSpec`/`ToolCall`/`ToolResult`/`ToolChoice`, `StopReason`, `Tool`, `AgentStep`, `PolicyEngine`, `AuditLog`. Message model round-trips tool calls/results for both wire dialects.2223## Phase 3 — Agent Engine (loop, memory, tools+safety) → CLI POC gate24- [x] 3.C ExecutionService (actor, streaming Process, SIGTERM→SIGKILL timeouts, cancellation), full PolicyEngine deny→ask→allow engine (quote-aware subcommand parsing, $()/backtick extraction, wrapper stripping, always-ask circuit breakers, remembered rules that can't override breakers), bash/osascript/5 file tools, ToolRegistry, WorkspaceManager (tracking+checkpoints) — `--verify-policy` 38/38 PASS25- [x] 3.A AgentLoop actor (stop_reason-keyed, retry-once on transient, parallel calls only when all read-only) + Planner (`update_plan` internal tool, .zyquo/plan.json) + LoopGuard (50 steps/500k tok/30min; repetition N=3, stall M=6; pause-not-abort) + Transcript (.zyquo/transcript.json) + sectioned system prompt26- [x] 3.B MemoryManager (85% compaction w/ same-model summarization + mechanical fallback, keep plan+MEMORY.md+last-6-steps verbatim, 10-step thrash guard; >8KB outputs offloaded to .zyquo/outputs/ with stubs)27- [x] GATE: `--run-mock` proves loop end-to-end offline; LIVE POC vs claude-sonnet-5: `--run "create ~/zqtest + hello.txt …"` → policy correctly auto-DENIED outside-workspace write under --yes, model adapted gracefully; with --allow-destructive: executed, verified, completed in 2 steps / 4.4s. Transcript + audit confirmed on disk.2829**Phase 3 checkpoint (2026-07-30):** Engine complete and proven live. Build 0 warnings; policy self-check 38/38; safety contract demonstrated against a real model (deny path AND happy path). ~/zqtest cleaned up after verification.3031## Phase 4 — Design system & UI spec (ZyquoTheme violet)32- [x] ZyquoTheme tokens implemented 1:1 from the CLAUDE.md §4.1 table (violet #7A5AF0 flagship light theme; plum-charcoal dark derived; type/spacing/radii/metrics/motion per family standard; Agent metrics: 1320×860 default, 300pt plan panel, 760×560 settings)33- [x] Components (hover/press/badges/status dots/provider glyphs) + AppearanceStore (violet default; graphite/sky/emerald/amber alternates)34- Post-Phase-3 coherence sweep: headers 100%, no naming drift, no Cloud identifier leftovers3536**Phase 4 checkpoint (2026-07-30):** CLAUDE.md §4.2–4.4 is the binding UI contract for Phase 6 (command-center layout: 260pt sidebar / 760pt conversation column with AgentStep cards + approval cards / collapsible plan panel / terminal drawer with Live-Audit-Files tabs / 52pt header with safety-mode segmented control). Design quality gate runs at the end of Phase 6.3738## Phase 5 — Icon (SVG → icns)39- [x] Both directions designed (Z-command, Z-orbit), rendered 16→1024, iterated on visual inspection ×2 each; **Z-command chosen** (orbit's ring/nodes vanish at 32px; the caret survives). Family squircle+Z DNA ported from zyquo-cloud.svg; palette #8B6CF5→#7A5AF0→#4B3A9E.40- [x] assets/icon/: zyquo-agent.svg (source of truth) + both candidates + -small (16/32) + -template (menu bar) variants41- [x] scripts/generate-icon.sh → Resources/AppIcon.icns (iconutil-valid) + MenuBarIcon.png/@2x; `make icon` + `make dev` green; icns verified in the bundle4243**Phase 5 checkpoint (2026-07-30):** Icon complete; verified visually at 512 and 64px by the orchestrator — reads as a sibling of Cloud's sky icon with a clear "agent that runs commands" story.4445## Phase 6 — Features / full UI46- [x] Wave 1: TaskStore/RunHub/RunController (AgentEvent→UI bridge), UIApprovalPresenter (continuation-based), sidebar w/ grouped tasks + status pills, 760pt conversation column (step cards, streaming, approval/guard-trip/compaction cards), plan panel w/ budget meters, terminal drawer (Live/Audit/Files), empty-state hero, ported Markdown renderer, `--run-ui-smoke` 19/1947- [x] Wave 2: Settings ×7 tabs (vault UI + per-provider Test, models w/ agent badges, safety rule editor + built-in pattern lists, agent budgets → AgentConfiguration, dynamic accent via ZyquoAccentResolver, shortcuts, advanced), Quick Task ⌥Space NSPanel, menu bar extra, 29 templates (6 categories, variables), personas (`personaAddendum` hook), ⌘K palette, auto-titles, Markdown+PDF export, full shortcut set48- [x] Design quality gate: visual review of empty state, Settings (light AND dark), icon in Dock — matches Phase 4 spec; run-state components verified by programmatic UI smoke49- [x] Post-Phase-6 coherence sweep: headers 100%, no naming drift, tokens-only (SyntaxHighlighter's palette is itself a dynamic token table)5051**Phase 6 checkpoint (2026-07-30):** Full command-center app builds 0-warnings, launches, renders to spec in light+dark. All self-checks green (policy 38/38, mock, ui-smoke). Known reported gaps (persisted-but-not-engine-enforced settings: requireApprovalForAppleScript in Autonomous, workspaceEscapePolicy=deny) documented in AgentSettingsStore.5253## Phase 7 — Verification with real keys (provider tool-calling table + scenario suite + safety tests)54- [ ] 7.1 `--verify` harness: every agent-capable model × (schema→tool call→tool_result→final answer→streaming) → table in docs/VERIFICATION.md; fix provider quirks until green55- [x] 7.2 **11/11 scenarios pass** live (docs/EVALUATION.md): nested structure, batch rename, write+run Python, CSV totals, largest files, re-planning after failure, forced compaction (4 CompactionRecords), AppleScript/osascript (TCC worked), multi-tool log analysis, plus 2 cross-provider parity runs on gpt-5.2. Harness: scripts/agent-eval.sh + scripts/eval-inspect.py56- [x] 7.3 **8/8 safety tests pass**: sudo never executes in any mode (model-level AND a new mock-forced gate-level test sf1x proving denial even in Autonomous), out-of-workspace delete auto-denied, SIGINT kills the child + records outcome=cancelled, rm -rf / hard-deny (38/38), zero key material in any artifact57- [x] `--load-vault` implemented (env → AES-256-GCM vault, per-provider stored/skipped, never prints keys)5859**Phase 7 checkpoint (2026-07-30):** 77/80 models green on tool calling (3 external failures documented); 11/11 scenarios and 8/8 safety tests pass. Two real bugs found and fixed by live testing: (1) AgentLoop recorded `completed` instead of `cancelled` when interrupted mid-stream; (2) harness sentinel `sleep 60` collided with an unrelated system daemon, making the cancellation leak-check unfalsifiable. Self-checks after all changes: build 0 warnings, policy 38/38, mock 0, ui-smoke pass.6061## Phase 8 — Signing & notarization (reuse zyquo-term identity) — ✅ COMPLETE62- [x] `Resources/ZyquoAgent.entitlements`: Hardened Runtime ON, App Sandbox deliberately OFF (the app must spawn /bin/bash + /usr/bin/osascript), single entitlement `com.apple.security.automation.apple-events` paired with `NSAppleEventsUsageDescription`. NOTE: the file must stay pure ASCII with no XML comments — codesign's AMFI parser rejects both (hit live: "AMFIUnserializeXML: syntax error").63- [x] `scripts/notarize.sh`: signs nested code inside-out, then the executable, then the bundle (`--options runtime --timestamp --entitlements`), verifies `--deep --strict`, ditto-zips, submits to notarytool `--wait`, staples, and **fails loudly unless spctl reports "Notarized Developer ID"**; optional signed+stapled DMG via a `dmg` argument.64- [x] `make release` green end-to-end: universal binary (x86_64 + arm64 via lipo) → Info.plist → sign → notarize (submission ffe1330f-6832-46e3-9cba-ff6257d4e839, status **Accepted**) → staple → verify.65- [x] Independent verification: `spctl -a -vv` = **accepted, source=Notarized Developer ID**, `stapler validate` OK, CodeDirectory `flags=0x10000(runtime)`, TeamIdentifier 3YM54G49SN, entitlements as intended, `lipo -archs` = x86_64 arm64, AppIcon.icns + menu-bar PNGs in the bundle.66- [x] The shipped bundle's own binary passes `--verify-policy` 38/38 and `--run-mock`, and the app launches and renders the command center.6768**Phase 8 checkpoint (2026-07-30):** Notarized, stapled, Gatekeeper-accepted universal `Zyquo Agent.app` built entirely without the Xcode IDE. Final sweep: every code file carries the mandatory header, no secrets in any commit (`.secrets/` never tracked), dist artifacts gitignored.6970---7172## Definition of Done — status73- ✅ `make release` → Developer ID-signed, notarized, stapled app (spctl-verified), no Xcode IDE74- ✅ Full plan→act→observe→reflect loop on the same providers/models as Zyquo Cloud; 77/80 agent-capable models green on native tool calling (docs/VERIFICATION.md)75- ✅ bash + AppleScript + workspace file tools with live streaming; every action through the policy gate; destructive/elevated always require approval; complete audit log76- ✅ Memory compaction keeps long tasks in-window (proven live: 4 compactions, task still correct); workspaces isolate and track task files77- ✅ Violet SVG icon → icns + menu-bar template, sibling of Cloud/Local78- ✅ Violet light theme per spec + derived dark theme, quality gate passed79- ✅ Naming coherent (`Zyquo Agent` / `com.zyquo.agent` / `ZyquoAgent`), keys in the reused AES-256-GCM vault (no Keychain)80- ✅ Mandatory header on every code file (repo-wide sweep)81- ✅ docs/: PLAN, AGENT-RESEARCH, PROVIDER-REUSE, VERIFICATION, EVALUATION8283### Known gaps (documented, not hidden)84- `requireApprovalForAppleScript` and `workspaceEscapePolicy=deny` are persisted and surfaced in Settings but not yet enforced by dedicated engine hooks (the engine already asks for AppleScript in Manual/Guarded and always asks on workspace escape) — see `AgentSettingsStore` header.85- `swift test` cannot run on a CommandLineTools-only toolchain (no XCTest module); the XCTest files exist for CI/Xcode, and `--verify-policy` / `--run-mock` / `--run-ui-smoke` are the executable equivalents.86- 3 of 80 models fail tool calling for external reasons: DeepInfra's two Gemini re-hosts strip Google's required `thought_signature`, and `kimi-k3` is capacity-throttled upstream.8788**Facts gathered from `~/Desktop/other/OTHER/zyquo-term` (2026-07-30):**89- Identity: `Developer ID Application: Simon-Pierre Boucher (3YM54G49SN)` (Team ID `3YM54G49SN`)90- notarytool keychain profile: `MacLustr-Notarize` (`xcrun notarytool submit … --keychain-profile "MacLustr-Notarize" --wait`)91- Pipeline: codesign nested executables first, then bundle, `--options runtime --timestamp --entitlements`, verify `--deep --strict`, DMG signed too, staple after notarize92- zyquo-term entitlements: hardened runtime, NO App Sandbox (terminal-class app), `com.apple.security.cs.allow-jit=false`. Zyquo Agent: same posture + `NSAppleEventsUsageDescription` in Info.plist and `com.apple.security.automation.apple-events` entitlement for osascript automation.93- Toolchain: Swift 6.4 (arm64, macOS 27)94