Sovereign 8s.is mirror of 8b-is/ios-AGsession
  • Swift 69.7%
  • Shell 17.5%
  • Python 9%
  • TypeScript 1.6%
  • Ruby 1.2%
  • Other 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Peter Lodri be6e4f2fd1
Some checks failed
CI / Build + Test (Networking) (push) Has been cancelled
CI / Build app (no signing) (push) Has been cancelled
feat(web): React + Vite SPA chat client talking to Hermes (#43)
Adds a single-page browser client for AGsession alongside the iOS app.
Same backend, different surface — Tailscale-only, no auth UI.

Scope:
- web/ — React 18 + Vite 5 + TypeScript, plain CSS, no UI framework
- Vite dev proxy:
  /hermes -> http://100.67.51.123:8642 (strips Origin/Referer; gateway
  has an Origin allowlist that rejects http://localhost:5173)
  /chat   -> http://100.67.51.123:11800 (rag-stack SSE, for future modes)
- SSE parser handles both OpenAI streaming (hermes mode) and rag-stack
  unnamed data:{json} events (delta/tool/tool_log/tool_done/done/error)
- Settings overlay: gear icon, backend URL editable, persisted to
  localStorage. VITE_HERMES_KEY in web/.env.local (gitignored).
- Components: ChatView, MessageBubble (markdown via raw HTML for agent),
  ComposeBar (Enter sends, mode dropdown), ToolCallChip (status, log,
  copy-when-done), StreamingText (blinking cursor)
- scripts/dev-web.sh — wrapper for `task`/manual runs: PID lock
  (.claude/web.pid), log capture (.claude/logs/web.log), --force kills
  existing instance
- .claude/launch.json — preview server registry for AGsession

Not in scope (yet):
- Tool call streaming in hermes mode — Hermes OpenAI endpoint doesn't
  emit structured tool events; non-hermes modes via /chat will surface
  them via the existing dispatchPayload path
- Build/deploy to Hetzner — dev-server only for now

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-10-12 18:56:49 +09:00
.claude feat(web): React + Vite SPA chat client talking to Hermes (#43) 2026-10-12 18:56:49 +09:00
.github/workflows Add HermesAudioClient for /v1/audio/speech TTS playback (#40) 2026-05-16 10:26:33 +02:00
AGsession feat(designsystem): Hanken Grotesk variable font + registration 2026-05-16 10:44:21 +02:00
AGsession.xcodeproj chore(xcode): set DEVELOPMENT_TEAM + enable STRING_CATALOG_GENERATE_SYMBOLS (#44) 2026-10-12 18:56:11 +09:00
AGsessionLiveActivity feat(live-activities): add AGsessionLiveActivity Widget Extension target 2026-05-13 17:59:28 +02:00
deploy fix(infra): tailnet check via API + rustfs override file 2026-05-16 21:29:44 +02:00
docs feat(ai-backend): docling live + Context Hub integration plan + loader 2026-05-16 19:31:17 +02:00
Packages feat(chat): terminal log text selection + copy button (#42) 2026-05-16 13:12:22 +02:00
scripts feat(web): React + Vite SPA chat client talking to Hermes (#43) 2026-10-12 18:56:49 +09:00
tools feat(cron-agent): colourful PDF + 15-min cadence + data-engineer reporter 2026-05-16 21:17:08 +02:00
web feat(web): React + Vite SPA chat client talking to Hermes (#43) 2026-10-12 18:56:49 +09:00
.gitignore feat(web): React + Vite SPA chat client talking to Hermes (#43) 2026-10-12 18:56:49 +09:00
AGENTS.md docs(project): update CLAUDE.md and AGENTS.md for current sprint state 2026-05-15 13:25:18 +02:00
Brewfile chore: dev environment + Taskfile + expanded CLAUDE.md 2026-05-11 17:11:14 +02:00
CLAUDE.md feat(tools): docling-agent — URLs in, markdown out 2026-05-16 19:55:50 +02:00
DESIGN.md docs: rewrite DESIGN.md to the Breezy & Weightless theme 2026-05-11 17:39:48 +02:00
docker-compose.yml feat(build): add local dev/prod build automation + release + signing 2026-05-14 13:51:43 +02:00
LOGO_PROMPT.md Add README and logo design prompt 2026-05-16 07:36:06 +00:00
Makefile feat(build): add local dev/prod build automation + release + signing 2026-05-14 13:51:43 +02:00
opencode.json feat(gpu): Hyperstack L40 provisioner + Devstral dual-slot setup 2026-05-14 07:21:23 +02:00
README.md Add README and logo design prompt 2026-05-16 07:36:06 +00:00
Taskfile.orchestrator.yml chore: add Taskfile.orchestrator.yml (from claude-marketplace@v0.18.0) 2026-05-11 23:14:48 +02:00
Taskfile.yml feat(setup,orch): bake opencode into setup + default coder to deepseek-v4-flash 2026-05-16 15:49:46 +02:00

AGsession

A native iOS client for intelligent multi-agent interaction, powered by Tailscale and streaming agent backends.

Overview

AGsession (Agent Session) is a premium iOS application that provides a rich, native interface to interact with multiple AI agents running on a private Tailscale tailnet. It replaces day-to-day reliance on chat bots with a modern, real-time streaming experience optimized for iPhone 17 Pro and contemporary iOS.

Core Features

  • Multi-Chat Architecture — Independent threads, each with its own mode (chat, agent, research, direct) and full local history
  • Multi-Agent Switching — Native support for four rag-stack backends with streamed responses and per-agent status indicators
  • Live Terminal & Log Streaming — SSH-style views for task app:status, oxmgr status, and live service logs
  • Push Notifications — Native APNs integration for real-time event delivery (in development)
  • Live Activities — Monitor long-running agent tasks directly from the lock screen and Dynamic Island
  • Token-by-Token Streaming — Feels responsive and alive; no artificial chunking or buffering delays
  • Offline-First Persistence — Full local history via SwiftData; authoritative local store with optional CloudKit sync

Architecture

Tech Stack

  • Language: Swift 6 (strict concurrency mode)
  • UI Framework: SwiftUI with Liquid Glass materials (iOS 26+)
  • Networking: URLSession-based SSE client with Tailscale private reachability
  • State Management: Swift Concurrency actors, @Observable patterns
  • Persistence: SwiftData for thread/message store
  • Packages: 12 local SwiftPM modules for feature isolation

Modular Design

The app is structured as a multi-module SwiftPM workspace for fast iteration, independent compilation, and offline-capable previews:

Module Purpose
Chat Chat threads, messages, views, and message streaming
A2A JSON-RPC 2.0 + SSE client for A2A-compliant agent endpoints
Approvals Tool-call approval request/decision flow and user notification
Auth Device identity via Secure Enclave (real device) or software keychain (simulator)
DesignSystem Reusable SwiftUI components on system Liquid Glass materials
FineTuningCollector Opt-in capture of model interactions to rotating samples.jsonl for fine-tuning
HermesPanel SwiftUI overlay for the Hermes monitoring dashboard
LiveActivities Live Activity lifecycle for streaming agent tasks to Dynamic Island and lock screen
LocalAgent Local agent task execution, state, and tool running
Networking URLSession SSE client, Tailscale reachability, bearer-token abstraction
Persistence SwiftData store, compression, and integrity helpers
SessionsOverview Sessions list UI, view models, and state management

Network Architecture

Tailscale Private Reachability

The app communicates exclusively over a private Tailscale tailnet. The system Tailscale iOS app (installed separately from the App Store) provides the VPN tunnel; AGsession connects transparently via resolvable Tailscale hostnames.

  • No packet-tunnel extension — The system Tailscale VPN owns the tunnel
  • Authentication via tailnet — User identity is validated at the network layer
  • Simulator support — The iOS Simulator inherits the Mac's Tailscale tunnel if active

Backend Endpoints

The app talks to services running on a Hetzner host (rag-stack):

  • agent_api (:11800/chat) — Chat and tool surface, streamed via SSE
  • generic_agent (:12100/run) — Long-running task execution with stream results
  • Deep Research API — In-house MCP endpoint fanning out to Perplexity and Tavily
  • APNs Bridge — Server-side subscription to rag:notify:{chat_id} events

See docs/superpowers/specs/2026-05-13-tailscale-setup.md for admin setup and network topology.

Development

Prerequisites

  • Xcode 16+ (with iOS 26 SDK)
  • Homebrew (for Taskfile, Git, etc.)
  • Tailscale (optional for development; required for production testing)

Quick Start

# Full development environment setup
./scripts/setup-macos.sh

# Or, if already set up:
task build:dev           # Build, test, and generate IPA
task build:quick         # Build without tests
task build:prod          # Production IPA (with optimizations)

Build Commands

All commands are available via task (a make-like tool driven by Taskfile.yml):

task                 # List all available tasks
task menu            # Interactive task selector
task doctor          # Verify environment and dependencies
task build:dev       # Clean, test, archive (dev build)
task build:quick     # Build without tests
task build:prod      # Production build with LTO and dead-strip
task release:draft -- 1.0.0   # Create draft GitHub release
task release:publish -- 1.0.0 # Publish release

Raw xcodebuild is available but not recommended; the scripts handle derived-data cleanup and proper test configurations.

Running Tests

task build:dev       # Runs tests automatically as part of build

# Or manually:
xcodebuild test -scheme AGsession \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro'

Code Style

The project uses Swift Format (built into recent Xcode toolchains):

swift format -i -r Sources/ Tests/

No SwiftLint rules are currently enforced. All modules are configured to use -strict-concurrency=complete in Swift 6.

Project Status

Current Release: Beta (TestFlight)
Target Device: iPhone 17 Pro (iOS 26+)
Build System: Xcode 16 + Taskfile + SwiftPM
Visibility: Private (no public TestFlight link or GitHub mirror)

Known Limitations (Beta)

  • Apple Developer Program enrollment pending (affects TestFlight, Push, App Groups, entitlements)
  • APNs bridge is in development
  • CloudKit sync is deferred pending user demand
  • Terminal transport design still in evaluation (WebSocket vs. SSE vs. polling)

Design Philosophy

UX Principles

  • Token-level streaming — Responses feel alive, not chunked
  • Instant thread switching — No loading spinners between conversations
  • Smooth scrolling — Terminal view handles high-volume logs without stuttering
  • One-handed reachability — Bottom navigation and full-screen chat focus

DX Principles

  • Previews work offline — Every screen has a preview; no full-app build required
  • Modules compile independently — Feature teams can work in parallel
  • Mocked SSE/backend — Tests and previews don't require network
  • No force unwraps — Typed errors surface cleanly via Result enums
  • Swift Concurrency end-to-end — No Combine, no callbacks, no Dispatch

Technical Decisions

  • SwiftUI only — Liquid Glass materials are first-class; no approximate blurs
  • Local store is authoritative — SwiftData is the source of truth for threads and messages
  • No third-party UI frameworks — System materials, NavigationStack, SF Symbols
  • Tailscale-only auth (beta) — Device identity via Secure Enclave (production-ready layer); network layer is the gate
  • Live Activities for streaming — Agents can show progress on the lock screen and Dynamic Island while running

Future Direction

Planned Features

  • User-addable channels — Generic mechanism for runtime-configurable agent endpoints (WebSocket, SSE, custom)
  • CloudKit sync — Optional cross-device history sync (deferred)
  • On-device summarization — Leverage Apple Foundation Models for long conversation summaries
  • Siri Shortcuts — Start a chat, tail a log, or trigger an agent via voice

Deferred (Out of Scope)

  • Custom packet-tunnel extension (use system Tailscale VPN)
  • HomeKit, CarPlay, or other capability integrations
  • macOS/iPad versions (iOS-specific for now)

Documentation

Comprehensive internal documentation lives in the docs/ hierarchy:

  • docs/repo-wiki/ — Module deep-dives and architecture
  • docs/superpowers/specs/ — Feature design documents with rationale
  • docs/superpowers/plans/ — Implementation task breakdowns
  • docs/BUILD_AND_RELEASE.md — Release procedures and signing
  • CLAUDE.md — Full developer handbook (conventions, skills, workflows)
  • DESIGN.md — High-level product and architectural vision

Contributing

This is a private repository. Contributions from core team members follow the standard pull request workflow:

  1. Create a feature branch from main
  2. Work in isolation; preview changes locally
  3. Open a PR with clear description of changes
  4. Address code review feedback
  5. Merge to main when approved

Each feature ideally lands in a single module and compiles independently for fast CI.

License

Private. Not for public distribution without explicit permission.


Built with Swift 6, SwiftUI, and a passion for streaming AI interactions.