SPB Git

spb/zyquo-agent Public MIT

The autonomous agent that actually operates your Mac — plans, runs real commands, verifies its own work.

macosswiftaiagent
Swift 94.7% Shell 4.1% Python 0.7% Makefile 0.5%
13.3 KB
View source Raw Blame History

# Zyquo Agent — Build Plan & Phase Checkpoints

# Phase 0 — Research + Zyquo Cloud Study

  • 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)

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.

  • 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)

# Phase 1 — Project Setup (SPM, no Xcode IDE)

  • Package.swift, executable target ZyquoAgent (swift-markdown dep, test target)
  • 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)
  • @main via synchronous Main enum (CLI modes: --run/--verify/--load-vault stubs), SwiftUI app shell + AppDelegate activation

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.

# Phase 2 — Architecture skeleton (folders per CLAUDE.md)

  • 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)
  • DesignSystem/ ZyquoTheme (violet #7A5AF0 flagship), Components, AppearanceStore (violet/graphite/sky/emerald/amber)
  • 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)

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.

# Phase 3 — Agent Engine (loop, memory, tools+safety) → CLI POC gate

  • 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 PASS
  • 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 prompt
  • 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)
  • 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.

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.

# Phase 4 — Design system & UI spec (ZyquoTheme violet)

  • 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)
  • Components (hover/press/badges/status dots/provider glyphs) + AppearanceStore (violet default; graphite/sky/emerald/amber alternates)
  • Post-Phase-3 coherence sweep: headers 100%, no naming drift, no Cloud identifier leftovers

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.

# Phase 5 — Icon (SVG → icns)

  • 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.
  • assets/icon/: zyquo-agent.svg (source of truth) + both candidates + -small (16/32) + -template (menu bar) variants
  • scripts/generate-icon.sh → Resources/AppIcon.icns (iconutil-valid) + MenuBarIcon.png/@2x; make icon + make dev green; icns verified in the bundle

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.

# Phase 6 — Features / full UI

  • 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/19
  • 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 set
  • 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 smoke
  • Post-Phase-6 coherence sweep: headers 100%, no naming drift, tokens-only (SyntaxHighlighter's palette is itself a dynamic token table)

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.

# Phase 7 — Verification with real keys (provider tool-calling table + scenario suite + safety tests)

  • 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 green
  • 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.py
  • 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 artifact
  • --load-vault implemented (env → AES-256-GCM vault, per-provider stored/skipped, never prints keys)

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.

# Phase 8 — Signing & notarization (reuse zyquo-term identity) — ✅ COMPLETE

  • 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").
  • 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.
  • 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.
  • 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.
  • The shipped bundle's own binary passes --verify-policy 38/38 and --run-mock, and the app launches and renders the command center.

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.

# Definition of Done — status

  • ✅ make release → Developer ID-signed, notarized, stapled app (spctl-verified), no Xcode IDE
  • ✅ 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)
  • ✅ bash + AppleScript + workspace file tools with live streaming; every action through the policy gate; destructive/elevated always require approval; complete audit log
  • ✅ Memory compaction keeps long tasks in-window (proven live: 4 compactions, task still correct); workspaces isolate and track task files
  • ✅ Violet SVG icon → icns + menu-bar template, sibling of Cloud/Local
  • ✅ Violet light theme per spec + derived dark theme, quality gate passed
  • ✅ Naming coherent (Zyquo Agent / com.zyquo.agent / ZyquoAgent), keys in the reused AES-256-GCM vault (no Keychain)
  • ✅ Mandatory header on every code file (repo-wide sweep)
  • ✅ docs/: PLAN, AGENT-RESEARCH, PROVIDER-REUSE, VERIFICATION, EVALUATION

# Known gaps (documented, not hidden)

  • 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.
  • 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.
  • 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.

Facts gathered from ~/Desktop/other/OTHER/zyquo-term (2026-07-30):

  • Identity: Developer ID Application: Simon-Pierre Boucher (3YM54G49SN) (Team ID 3YM54G49SN)
  • notarytool keychain profile: MacLustr-Notarize (xcrun notarytool submit … --keychain-profile "MacLustr-Notarize" --wait)
  • Pipeline: codesign nested executables first, then bundle, --options runtime --timestamp --entitlements, verify --deep --strict, DMG signed too, staple after notarize
  • 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.
  • Toolchain: Swift 6.4 (arm64, macOS 27)