DOCSEARCHbyAlgolia
Submit Docs

WUPHF Documentation

repository·main·Indexed 22 days ago

https://github.com/nex-crm/wuphf

A collaborative 'office' for AI agents featuring a shared environment (the 'brain') where multiple AI employees communicate and maintain a shared knowledge base via a wiki. The ecosystem includes the wuphf-agent service for workflow execution and persistence, a desktop shell built with Wails v2, an avatar design system for consistent agent representation, and wuphfbench for measuring SLO probes like cold-start and IPC latency.

Tokens
167.4K
Snippets
200
Records
811
Agent score
79%

What's inside WUPHF

  1. Understand the WUPHF Operator MLP Build Plan

    main

    The Operator MLP (Minimum Loveable Product) plan defines the transition of WUPHF from a multi-agent/notebook-based system to a streamlined 'Operator' platform focused on inbound routing and scoring.

    Core Concept: The Operator Loop

    The goal is to enable users (like RevOps managers) to automate manual triage tasks through a specific loop:

    1. Capture: A user narrates a process via screen-share/voice.
    2. Build: An Internal Tool is generated, consisting of a UI tab (for interacting with data) and a Workflow tab (the logic engine).
    3. Run & Digest: The tool processes requests and provides a daily summary (e.g., via Slack/Email).
    4. Improve: The user iterates on the tool via chat or through proactive detection of their manual activities.

    Key Components

    • Internal Tool: A composite object containing a workflow specification, an app-builder UI, and (eventually) a Data store.
    • gbrain: The central Knowledge/context backend, served as an MCP server. It replaces legacy embedding and indexing systems.
    • Workflow Engine: The core logic that executes the trigger → enrich → score → guard → route sequence.
    • App Builder: A UI component used to construct the interface for the Internal Tool.

  2. Understand @wuphf/protocol overview and architecture

    main
    @wuphf/protocol is a pure-data TypeScript protocol library designed for in-process contracts at broker boundaries. It provides branded types, validators, codecs, and deterministic byte projections. It does not perform any I/O (filesystem, network, SQLite, or keychain). It serves as the TypeScript implementation of the contract mirrored by a Go reference verifier for audit chains, receipts, approval tokens, and IPC envelopes.

  3. Navigate the wuphf Operator surfaces

    main

    The product consists of five primary navigation surfaces:

    1. Chats: The entry point for talking to Nex. Used to tune existing tools or start a new one via the "Describe a new tool" or "Build a tool" flows. Includes the "Teach your workflow to Nex" voice-based CTA.
    2. Internal tools: A management view for tools. Tools are categorized as a live "hero" tool, Drafts, or "Suggested by your AI". Each tool has three tabs:
      • UI: The mini-app interface for running the tool (e.g., a table of scored requests).
      • Workflow: The deterministic pipeline of steps, run history, and version history.
      • Data: Typed tables produced by the tool.
    3. Knowledge: A Wikipedia-style reader for company information, featuring articles with infoboxes, citations, and references.
    4. Integrations: A view to manage connected apps like HubSpot, Slack, Gmail, Salesforce, Zendesk, and Stripe.
    5. Settings: Workspace configuration and voice settings (allowing users to bring their own OpenAI Realtime key).

  4. Understand the WUPHF architecture and core components

    main

    WUPHF is designed as a push-driven system where agents are spawned on demand rather than being continuously polled. The architecture consists of a central Broker (pub/sub + queue) that receives messages from interfaces like the Web UI or TUI and pushes them to Per-agent headless runners (such as Claude Code or Codex). Each agent operates within an isolated git worktree to prevent cross-agent corruption.

    Core Components Reference

    ComponentRole
    cmd/wuphf/CLI entrypoint, slash commands, TUI, and launcher
    internal/team/broker.goThe message bus; agents are spawned on message push
    internal/team/launcher.goDetermines which agents wake based on mode (focus/collab) or tags
    internal/team/headless_claude.goSpawns claude as a one-shot per turn (no --resume)
    internal/team/headless_codex.goSpawns Codex as a one-shot per turn
    internal/team/worktree.goManages isolated git worktrees per agent
    internal/team/resume.goReplays unfinished tasks and unanswered messages on restart
    internal/teammcp/Provides per-agent scoped MCP tool surfaces
    internal/agent/packs.goDefines team compositions (e.g., starter, coding-team)
    web/index.htmlThe Office UI for channels, composer, and live streams
    mcp/Built-in MCP servers for Nex context and human-in-the-loop approvals

  5. Understand the Slice 0.5 prompt eval harness

    main

    The Slice 0.5 prompt eval harness is a minimal golden-case harness used to evaluate the three core wiki intelligence prompts. It is designed to calibrate prompt drift, catch regressions before Slice 1 is shipped, and feed the Week 0 benchmark corpus. It focuses on three specific prompt types:

    • extract: Uses extract_entities_lite.tmpl cases.
    • synthesis: Uses synthesis_v2.tmpl cases.
    • query: Uses answer_query.tmpl cases.

    The harness is lightweight, running in under a minute locally by performing single LLM shell-outs (approximately 2-3s per case).

  6. Use WebAuthn Cosign Components for approvals

    main

    The web/src/components/cosign module provides renderer-only WebAuthn approval surfaces. It is designed to handle the assertion ceremony directly in the browser via navigator.credentials rather than proxying through Electron IPC. The resulting JSON response is sent to the broker via a loopback HTTP client.

    Key components include:

    • CosignPrompt: Renders the ApprovalClaim and ApprovalScope, initiates the assertion ceremony, and displays the accepted token or threshold progress.
    • CredentialRegistrationPanel: A standalone settings surface used to bind a browser WebAuthn credential to an approval role.

  7. Understand the WUPHF Wiki Design System scope

    main

    The WUPHF Wiki design system applies exclusively to the /wiki surface within the WUPHF web app (running on port 7891 for production or 7900 for development).

    It does NOT apply to:

    • The pixel-office marketing site.
    • The rest of the WUPHF app chrome (which uses web/src/styles/global.css).

    Core Concept: The wiki is a git-native markdown knowledge base designed with a 'Wikipedia-fidelity' aesthetic. It uses a three-column layout and an editorial-first posture to create a sense of a 'living reference work' where users can see AI agents writing in real-time.

  8. What is a transport and how to choose a scope

    main

    A transport bridges an external messaging service (like Slack, Discord, or WhatsApp) with the WUPHF office broker. When implementing a new integration, you must choose one of three scopes based on how the external service maps to the WUPHF office:

    • Channel-bound (Transport): One external chat/session maps to exactly one office channel (e.g., Telegram). Use this when an external chat corresponds to a specific #channel in the office.
    • Member-bound (MemberBoundTransport): Each bridged session becomes an individual office member (e.g., OpenClaw). Use this when every external user/session is treated as a distinct agent or human member.
    • Office-bound (OfficeBoundTransport): The external entity joins the entire office (e.g., Human-share). Use this when an external human is admitted to the whole office rather than a specific channel or member slot.

  9. How the WUPHF desktop shell works

    main

    The desktop shell avoids the complexity of a sidecar architecture (where a separate process manages the lifecycle of the broker) by running the broker in-process.

    Lifecycle Flow:

    1. Thread Locking: init() calls runtime.LockOSThread() to ensure the Cocoa run loop stays on the main thread.
    2. Broker Boot: main() selects a free loopback port and boots the broker in a goroutine using the sequence: NewLauncher("") → SetNoOpen(true) → PreflightWeb() → LaunchWeb(port).
    3. Window Loading: The Wails window loads an embedded bootstrap page. This page uses a middleware from bootstrap.go to template the live port into the page. Once the broker is ready, the page uses location.replace to redirect to the actual http://127.0.0.1:<port>/ origin.

    Note: Redirecting to a real HTTP origin is required because the wails:// custom scheme does not support WebSockets, which are necessary for the SPA's SSE and WebSocket communication.

  10. Routine Data Model

    main

    A routine is defined by the following schema:

    • id: Unique identifier.
    • name: Human-readable name.
    • prompt: The text instruction to be executed.
    • schedule: The timing configuration (managed via cron).
    • enabled: Boolean toggle to pause/resume the schedule.
    • version: The current version number of the prompt.
    • lastRun: Timestamp of the most recent execution.

  11. Understand the Operator Harness Architecture

    main

    The Operator Harness is a three-layer system designed to allow non-technical users to build deterministic internal tools via AI conversation.

    1. Operator FE (React): The user interface for chats, internal tools, knowledge, and settings. It communicates with the harness via a thin HTTP + SSE API.
    2. Harness API (Python/FastAPI): The backend that manages the build and execution processes. Key endpoints include:
      • POST /build/stream: Streams the agent's process of assembling a workflow via SSE.
      • POST /run: Executes a compiled workflow on test or real data.
      • GET/POST /knowledge: Interfaces with gbrain for search, querying, and page management.
      • /integrations, /settings, /providers: Manages provider detection and BYOK (Bring Your Own Key) configurations.
    3. Core Engines:
      • BUILD (Agentic): Uses a deepagents agent to plan, drive discovery (via gbrain, browsersniff, browser-capture, or Composio), and emit a WorkflowSpec.
      • EXECUTE (Deterministic): Runs the compiled WorkflowSpec through a workflow engine (API-first replay → UI replay → bounded CUA-heal). It does not use tool-call chains at runtime.

    Note: The system relies on an MCP (Model Context Protocol) seam to allow the harness to reach tools.

  12. WUPHF Design Anti-Patterns

    main

    To maintain the brand identity, avoid the following:

    • Smooth Animations: No ease-in-out or cubic-bezier in the pixel scene.
    • Rounded Corners: No border-radius on any element in the pixel scene.
    • Light Mode: No light-mode color values or versions.
    • Incorrect Accents: No purple, violet, or blue as primary accents.
    • Gradients: No gradient backgrounds or gradient buttons.
    • Non-Pixel Imagery: No photos or smooth vector graphics.
    • Standard Fonts: No Inter, Roboto, Helvetica, or system fonts for visible text.
    • Traditional Hero Layouts: No standard hero copy with a CTA above the fold.