From 8cd479f20cd467cab4fb7950e7b211f977e1826f Mon Sep 17 00:00:00 2001 From: -Puter <22245429+puterhimself@users.noreply.github.com> Date: Sun, 19 Jul 2026 17:29:42 +0530 Subject: [PATCH] Track Flue skill and refresh top-level docs - Commit the vendored Flue SKILL.md under .agents/skills/flue and the .claude/skills/flue symlink plus skills-lock.json entry. - Rewrite AGENTS.md down to the repo's actual conventions and expand README.md with daemon/TUI/dev script notes. --- .agents/skills/flue/SKILL.md | 164 ++++++++++++++++++++++++++++++++ .claude/skills/flue | 1 + AGENTS.md | 176 +---------------------------------- README.md | 27 +++++- skills-lock.json | 6 ++ 5 files changed, 198 insertions(+), 176 deletions(-) create mode 100644 .agents/skills/flue/SKILL.md create mode 120000 .claude/skills/flue diff --git a/.agents/skills/flue/SKILL.md b/.agents/skills/flue/SKILL.md new file mode 100644 index 0000000..86b7fdb --- /dev/null +++ b/.agents/skills/flue/SKILL.md @@ -0,0 +1,164 @@ +--- +name: flue +description: Use when building, debugging, reviewing, or documenting Flue agents, workflows, channels, skills, tools, sandboxes, targets, routing, persistence, observability, or CLI usage; routes coding agents to version-matched Flue documentation through the CLI. +--- + +# Flue + +Use `flue docs` to read the documentation bundled with the installed `@flue/cli` version. Choose relevant paths from the catalog below and run `flue docs read `. If no catalog entry matches your task, run `flue docs search `, then read the most relevant result with `flue docs read `. + +For example, `flue docs search "durable execution"` searches with the query `durable execution`. If it returns the path `concepts/durable-execution`, run `flue docs read concepts/durable-execution` to read that page. + +## Documentation Catalog + + + +```text +api/action-api -- Action API + Reference for defining reusable finite Actions with @flue/runtime. +api/agent-api -- Agent API + Reference for defining agents and running agent operations with @flue/runtime. +api/data-persistence-api -- Data Persistence API + Reference for Flue persistence adapters and stores. +api/errors-reference -- Errors Reference + Reference Flue transport errors, runtime failures, and development diagnostics. +api/events-reference -- Events Reference + Reference runtime activity, attached-agent event types, and global observation APIs. +api/provider-api -- Provider API + Register custom model providers and override built-in provider transport. +api/routing-api -- Routing API + Compose Flue routes in an authored application entrypoint. +api/sandbox-api -- Sandbox Adapter API + Adapt a provider sandbox SDK into Flue's public sandbox contract. +api/streaming-protocol -- Streaming Protocol + Reference for reading Flue agent conversations and workflow events over Durable Streams. +api/workflow-api -- Workflow API + Reference for creating and invoking workflows with @flue/runtime. +cli/add -- flue add + Reference for discovering and applying Flue implementation blueprints. +cli/build -- flue build + Reference for creating deployable Flue application artifacts. +cli/dev -- flue dev + Reference for starting a watch-mode local Flue development server. +cli/docs -- flue docs + Reference for listing, reading, and searching the bundled Flue documentation. +cli/init -- flue init + Reference for creating an initial Flue project configuration file. +cli/overview -- CLI + Use the Flue CLI to configure, develop, exercise, inspect, and build an application. +cli/run -- flue run + Reference for executing one agent prompt or workflow invocation from the command line. +cli/update -- flue update + Reference for updating integrations from newer Flue blueprint upgrade guides. +concepts/agents -- What is an agent? + What an AI agent actually is, why a model alone isn't one, and what makes a Flue agent different. +concepts/durable-execution -- Durable Agents + Understand how Flue agents and workflows handle server restarts, interrupted connections, and other disruptions. +ecosystem/channels/discord -- Discord +ecosystem/channels/github -- GitHub +ecosystem/channels/google-chat -- Google Chat +ecosystem/channels/intercom -- Intercom +ecosystem/channels/linear -- Linear +ecosystem/channels/messenger -- Facebook Messenger +ecosystem/channels/notion -- Notion +ecosystem/channels/resend -- Resend +ecosystem/channels/salesforce-marketing-cloud -- Salesforce Marketing Cloud +ecosystem/channels/shopify -- Shopify +ecosystem/channels/slack -- Slack +ecosystem/channels/stripe -- Stripe +ecosystem/channels/teams -- Microsoft Teams +ecosystem/channels/telegram -- Telegram +ecosystem/channels/twilio -- Twilio +ecosystem/channels/whatsapp -- WhatsApp +ecosystem/channels/zendesk -- Zendesk +ecosystem/databases/libsql -- libSQL +ecosystem/databases/mongodb -- MongoDB +ecosystem/databases/mysql -- MySQL +ecosystem/databases/postgres -- Postgres +ecosystem/databases/redis -- Redis +ecosystem/databases/supabase -- Supabase +ecosystem/databases/turso -- Turso +ecosystem/databases/valkey -- Valkey +ecosystem/deploy/aws -- Deploy Agents on AWS +ecosystem/deploy/cloudflare -- Deploy to Cloudflare +ecosystem/deploy/docker -- Deploy Agents with Docker +ecosystem/deploy/fly -- Deploy Agents on Fly.io +ecosystem/deploy/github-actions -- Build Agents for GitHub Actions +ecosystem/deploy/gitlab-ci -- Build Agents for GitLab CI/CD +ecosystem/deploy/node -- Deploy Agents on Node.js +ecosystem/deploy/railway -- Deploy Agents on Railway +ecosystem/deploy/render -- Deploy Agents on Render +ecosystem/deploy/sst -- Deploy Agents on SST +ecosystem/sandboxes/boxd -- boxd +ecosystem/sandboxes/cloudflare -- Cloudflare Sandbox +ecosystem/sandboxes/cloudflare-shell -- Cloudflare Shell +ecosystem/sandboxes/daytona -- Daytona +ecosystem/sandboxes/e2b -- E2B +ecosystem/sandboxes/exedev -- exe.dev +ecosystem/sandboxes/islo -- islo +ecosystem/sandboxes/mirage -- Mirage +ecosystem/sandboxes/modal -- Modal +ecosystem/sandboxes/vercel -- Vercel Sandbox +ecosystem/tooling/braintrust -- Braintrust +ecosystem/tooling/opentelemetry -- OpenTelemetry +ecosystem/tooling/sentry -- Sentry +ecosystem/tooling/vitest-evals -- Vitest Evals +getting-started/quickstart -- Getting Started + Set up a Flue project automatically or create your first agent manually. +guide/actions -- Actions + Define finite agent-backed operations that can be reused by workflows and agents. +guide/building-agents -- Agents + Create an agent, configure its capabilities, and send it messages over time. +guide/channels -- Channels + Receive verified provider events and connect them to Flue applications. +guide/database -- Database + Configure database-backed state for Flue agents and workflow runs. +guide/evals -- Evals + Evaluate Flue agents with repeatable Vitest suites using vitest-evals. +guide/models -- LLM (Models & Providers) + Select models, configure providers, and tune reasoning behavior in Flue agents. +guide/observability -- Observability + Inspect workflow runs, monitor agent activity, and export telemetry from your application. +guide/project-layout -- Project Layout + Understand the source files and generated output in a Flue project. +guide/react -- React + Build React interfaces for live agent conversations and workflow runs. +guide/routing -- Routing + Compose Flue with application routes, middleware, and custom HTTP ingress. +guide/sandboxes -- Sandboxes + Give agents a workspace for files and command-driven work. +guide/schedules -- Schedules + Invoke Flue workflows or dispatch agent input on a schedule with Cloudflare or Node.js. +guide/skills -- Skills + Add Agent Skills to Flue agents and invoke them from sessions. +guide/subagents -- Subagents + Let agents delegate focused work to named specialists. +guide/targets/cloudflare -- Cloudflare + Understand the Cloudflare-specific runtime behavior and APIs for Flue applications. +guide/targets/node -- Node.js + Understand the Node.js-specific runtime behavior and APIs for Flue applications. +guide/tools -- Tools + Give agents application capabilities through custom tools and MCP servers. +guide/workflows -- Workflows + Create, invoke, and expose finite agent-backed operations. +introduction/why-flue -- Why Flue? + Build autonomous AI agents and powerful workflows with a programmable TypeScript harness, and run them anywhere. +reference/configuration -- Configuration + Reference for flue.config.ts options. +sdk/agents -- client.agents + Invoke persistent agent instances and read their conversations. +sdk/client -- createFlueClient(...) + Configure an SDK client for a deployed Flue application. +sdk/errors -- Errors + SDK HTTP and stream error types. +sdk/events -- Events and records + SDK event, workflow-run record, and normalized model-turn types. +sdk/overview -- SDK overview + Reference for consuming deployed Flue agents and workflows with @flue/sdk. +sdk/runs -- client.runs + Inspect and stream HTTP-exposed workflow runs. +sdk/workflows -- client.workflows + Start workflow runs and receive their run ID. +``` + + diff --git a/.claude/skills/flue b/.claude/skills/flue new file mode 120000 index 0000000..9065025 --- /dev/null +++ b/.claude/skills/flue @@ -0,0 +1 @@ +../../.agents/skills/flue \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index c409605..660a07c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,174 +1,2 @@ -# Repository Guidelines - -## Project Overview - -This is a Bun/TypeScript monorepo for operating coding agents across web, native, desktop, terminal, and remote daemon surfaces. Convex is the backend control plane; the compiled Bun daemon subscribes to Convex commands and dispatches them to AgentOS/RivetKit actors that manage isolated agent VMs. - -## Architecture & Data Flow - -- `apps/web`, `apps/native`, `apps/desktop`, and `apps/tui` are user interfaces. Shared UI lives in `packages/ui`; runtime-specific environment validation lives in `packages/env`. -- `packages/backend/convex` owns persistence, Better Auth, daemon registration/presence, the leased command queue, and append-only command events. -- `apps/daemon` is an Effect v4 application. It connects to Convex, subscribes to available commands, atomically claims a lease, invokes an AgentOS actor action, then reports success or failure. -- `packages/primitives` provides shared Effect v4 services, currently the `AgentOs` service and layer over `@rivet-dev/agentos`. -- `packages/agents` contains separate Flue agent definitions; do not conflate these with the AgentOS daemon runtime. - -Primary daemon flow: - -```text -UI mutation -> Convex daemonCommands.enqueue - -> daemon onUpdate subscription - -> claim -> start -> AgentOS action - -> succeed/fail + daemonCommandEvents -``` - -The command queue is lease-based. Preserve ownership checks through `claimedBySessionId`, expiry through `leaseExpiresAt`, terminal statuses, and bounded query results. Keep stable daemon configuration separate from high-churn presence/heartbeat state. - -## Key Directories - -- `apps/web/`: React Router 8 web client; desktop consumes its static build. -- `apps/native/`: Expo/React Native client. -- `apps/desktop/`: Electrobun shell around `apps/web/build/client`. -- `apps/tui/`: OpenTUI/React terminal client. -- `apps/daemon/`: compiled Bun daemon; Effect runtime, Convex adapter, AgentOS adapter. -- `packages/backend/convex/`: schema, queries, mutations, HTTP/auth integration, generated Convex bindings. -- `packages/primitives/`: reusable Effect v4 primitives. -- `packages/ui/`: shared shadcn/Tailwind UI package. -- `packages/env/`: `./web`, `./native`, and `./server` environment schemas. -- `packages/config/`: shared strict TypeScript configuration. -- `repos/`: committed, read-only upstream references; exclude from normal project tooling. - -## Development Commands - -Run commands from the repository root unless noted. - -```sh -bun install # install workspace dependencies -bun run dev:setup # configure/start the Convex development deployment -bun run dev # run workspace dev scripts -bun run build # build all targets; desktop is built separately last -bun run check-types # recursive workspace type checks -bun run check # Ultracite checks -bun run lint # Oxlint through Vite+ -bun run format # Oxfmt through Vite+ -bun run fix # apply Ultracite fixes -``` - -Targeted commands: - -```sh -bun run dev:web -bun run dev:native -bun run dev:desktop -bun run dev:tui -bun run dev:server # Convex dev server -bun run dev:daemon -bun run build:daemon # apps/daemon/dist/code-daemon -bun run build:desktop -``` - -Repository maintenance: - -```sh -bun run docs:update [commit-or-range] --dry-run # preview a documentation-agent prompt -bun run docs:update [commit-or-range] # update first-party docs with codex/opencode/claude -bun run subtree list # list configured vendored subtrees -bun run subtree status [name] # inspect local subtree metadata -bun run subtree preview # show incoming upstream commits -bun run subtree update --yes # pull a configured subtree using --squash -``` - -`docs:update` defaults to `HEAD`, accepts Git ranges such as `main..HEAD`, excludes vendored/generated content, and detects the agent in `codex`, `opencode`, `claude` order. Override it with `--agent` or `DOCS_AGENT`. Subtree configuration is stored in `scripts/subtrees.json`; pinned historical entries require `--force-pinned --yes`. - -Add shared shadcn components with `npx shadcn@latest add -c packages/ui` and import them from `@code/ui/components/`. - -## Code Conventions & Common Patterns - -- Use ESM, TypeScript 6, double quotes, semicolons, and sorted `package.json` fields. Formatting/lint configuration is in `vite.config.ts`, `oxfmt.config.ts`, and `oxlint.config.ts`. -- Use `import type` for type-only imports. Do not use `any`; validate or narrow `unknown` at trust boundaries. -- Reuse workspace packages through `@code/` and their declared subpath exports instead of reaching into unrelated package internals. -- Environment access belongs in `packages/env`; validate new variables with Zod and expose them through the correct runtime entry point. -- Generated files are not hand-edited: notably `packages/backend/convex/_generated/**`, `apps/web/src/routeTree.gen.ts`, and framework build/type directories. -- Convex modules map directly to `api..`. Every function requires argument validators. Prefer indexed, bounded reads and preserve mutation atomicity for claims/state transitions. -- Before changing `packages/backend/convex`, read `packages/backend/AGENTS.md` and `packages/backend/convex/_generated/ai/guidelines.md`; those instructions override remembered Convex APIs. - -Effect v4 patterns used by daemon/primitives: - -- Define dependencies with `Context.Service` and provide them through `Layer`. -- Use `Schema.TaggedErrorClass` for typed failures and `Effect.try`/`Effect.tryPromise` at external boundaries. -- Name effectful functions with `Effect.fn("Module.operation")`. -- Manage resources with scopes, `Effect.acquireRelease`, and finalizers; use structured concurrency (`FiberSet`, scoped fibers) rather than detached promises. -- Bridge callback APIs through Effect streams/queues. Keep promise and callback errors in the typed error channel. -- Run Bun applications through `BunRuntime.runMain`. - -## Important Files - -- `package.json`: workspace catalog and authoritative scripts; package manager is `bun@1.3.14`. -- `vite.config.ts`: Vite+ task, lint, format, staged-file, and generated-file exclusions. -- `packages/config/tsconfig.base.json`: shared strict compiler settings. -- `packages/backend/convex/schema.ts`: daemon and command data model. -- `packages/backend/convex/daemonCommands.ts`: lease-based command state machine. -- `packages/backend/convex/daemonRuntime.ts`: connection, heartbeat, disconnect, and event reporting. -- `apps/daemon/src/index.ts`: Bun/Effect entry point. -- `apps/daemon/src/runtime.ts`: command subscription and execution loop. -- `apps/daemon/src/convex.ts`: `ConvexControlPlane` Effect service. -- `apps/daemon/src/agent-os.ts`: RivetKit registry and AgentOS action dispatch. -- `packages/primitives/src/agent-os.ts`: reusable AgentOS Effect service/layer. -- `packages/env/src/{web,native,server}.ts`: runtime environment contracts. - -## Runtime/Tooling Preferences - -- Use Bun, not npm/pnpm/yarn, for root installation and scripts. The daemon intentionally compiles with `bun build --compile`. -- Vite+ (`vp`) is the workspace task runner; there is no Turbo or Nx workflow. -- Linting is not type-aware. Always run `bun run check-types` for TypeScript verification. -- Effect and `@effect/platform-bun` are pinned to `4.0.0-beta.99`. AgentOS uses `@rivet-dev/agentos`; RivetKit is currently pinned to a feature build. Verify APIs against installed declarations/source before upgrading or generalizing. -- `.env` and `.env*.local` may contain deployment values and are generally ignored. Use `apps/daemon/.env.example` as the daemon template. Placeholder Convex hosts are deliberately rejected by the environment schemas. - -## Testing & QA - -There are currently no first-party automated tests, test scripts, coverage thresholds, or CI workflows. Do not claim a test suite passed. The current baseline verification is: - -```sh -bun run check-types -bun run check -``` - -Also run the changed application path: compile and start the daemon for daemon work, exercise the affected page for UI work, and use a development Convex deployment for backend state transitions. - -When adding tests: - -- Use the Vite+ test configuration rather than adding a standalone Vitest config. -- Convex tests belong under `packages/backend/convex/` and should follow the generated guidance (`convex-test`, Vitest, edge runtime). -- RivetKit actor tests should use its `setupTest` helper. -- Tests must defend observable behavior such as lease ownership, state transitions, cleanup, retries, authentication, or rendered interactions. - -## Vendored Repositories - -External repositories under `repos/` are read-only reference material. - -- Prefer their patterns, examples, tests, and API usage over guesses or web snippets. -- Do not edit files under `repos/` unless explicitly asked. -- Do not import application code from `repos/`; use normal package dependencies. -- Exclude `repos/` from project-wide formatting, linting, typechecking, and tests unless explicitly validating a vendored repository. - -### Effect v4 and Effect Smol - -Effect v4 moved from the archived `effect-smol` repository into canonical `Effect-TS/effect` in July 2026. When writing or reviewing Effect v4 code: - -1. Read `repos/effect/LLMS.md` before making changes. -2. Use `repos/effect/` as the current source of truth. Its `main` branch contains Effect v4 beta; Effect v3 is on upstream `v3`. -3. Use `repos/effect/packages/effect/src/`, `repos/effect/packages/effect/test/`, and `repos/effect/ai-docs/` for current APIs and idioms. -4. Treat `repos/effect-smol/` as historical only; read its `README.md` before consulting it. -5. Verify API names and signatures against `repos/effect/`; do not rely on Effect v3 knowledge or prefer older Smol APIs. -6. Import only from the installed `effect` package in application code. - -Refresh the current reference only from a clean worktree: - -```sh -git subtree pull --prefix=repos/effect https://github.com/Effect-TS/effect.git main --squash -``` - -The archived Smol subtree should normally stay pinned. If historical synchronization is explicitly required: - -```sh -git subtree pull --prefix=repos/effect-smol https://github.com/Effect-TS/effect-smol.git main --squash -``` +This Bun/TypeScript monorepo uses Bun/Vite+, Convex for the control plane, Effect v4 for daemon/primitives, and Flue in `packages/agents`; use `@code/*` workspace exports, validate environment values in `packages/env`, never edit generated files or `repos/`, and verify changes with the targeted runtime plus `bun run check-types` and `bun run check`. +Before any Flue work, MUST read `.agents/skills/flue/SKILL.md` and use its installed-version `flue docs` references; keep every `AGENTS.md` to 1–2 dense sentences by replacing stale guidance instead of appending rules. diff --git a/README.md b/README.md index 1ab071f..164268f 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,10 @@ This project was created with [Better-T-Stack](https://github.com/AmanVarshney01 - **TailwindCSS** - Utility-first CSS for rapid UI development - **Shared UI package** - shadcn/ui primitives live in `packages/ui` - **Convex** - Reactive backend-as-a-service platform +- **Agent daemon** - Bun/Effect service that leases Convex commands and dispatches them to AgentOS/RivetKit actors - **Authentication** - Better-Auth - **Electrobun** - Lightweight desktop shell for web frontends +- **OpenTUI** - Terminal interface in `apps/tui` - **Oxlint** - Oxlint + Oxfmt (linting & formatting) - **Vite+** - Unified Vite toolchain, workspace task runner, linting, and formatting @@ -44,6 +46,16 @@ bun run dev Open [http://localhost:5173](http://localhost:5173) in your browser to see the web application. Use the Expo Go app to run the mobile application. Your app will connect to the Convex cloud backend automatically. +### Daemon setup + +The daemon is a separate Bun process that connects to Convex, claims queued `daemonCommands`, and runs AgentOS actor actions. Copy `apps/daemon/.env.example` to `apps/daemon/.env`, replace the placeholder `CONVEX_URL`, then run: + +```bash +bun run dev:daemon +``` + +Build the compiled daemon binary with `bun run build:daemon`; the output is `apps/daemon/dist/code-daemon`. + ## UI Customization React web apps in this stack share shadcn/ui primitives through `packages/ui`. @@ -81,11 +93,17 @@ If you want to add app-specific blocks instead of shared primitives, run the sha ``` code/ ├── apps/ -│ ├── web/ # Frontend application (React + React Router) +│ ├── web/ # Web application (React + React Router) │ ├── native/ # Mobile application (React Native, Expo) +│ ├── desktop/ # Electrobun shell around the web build +│ ├── tui/ # OpenTUI terminal client +│ ├── daemon/ # Bun/Effect daemon for AgentOS command execution ├── packages/ -│ ├── ui/ # Shared shadcn/ui components and styles │ ├── backend/ # Convex backend functions and schema +│ ├── primitives/ # Shared Effect services, including AgentOS helpers +│ ├── env/ # Runtime environment validation +│ ├── ui/ # Shared shadcn/ui components and styles +├── repos/ # Vendored upstream references; excluded from normal tooling ``` ## Available Scripts @@ -93,17 +111,22 @@ code/ - `bun run dev`: Start all applications in development mode - `bun run build`: Build all applications - `bun run dev:web`: Start only the web application +- `bun run dev:server`: Start the Convex development server - `bun run dev:setup`: Setup and configure your Convex project - `bun run check-types`: Check TypeScript types across all apps - `bun run dev:native`: Start the React Native/Expo development server +- `bun run dev:tui`: Start the terminal UI - `bun run check`: Run Vite+ format/lint checks and workspace TypeScript checks - `bun run lint`: Run Vite+ lint checks - `bun run format`: Run Vite+ formatting +- `bun run fix`: Apply Ultracite fixes - `bun run staged`: Run Vite+ checks against staged files - `bun run hooks:setup`: Install Vite+ native Git hooks with `vp config` - `bun run dev:desktop`: Start the Electrobun desktop app with HMR - `bun run build:desktop`: Build the stable Electrobun desktop app - `bun run build:desktop:canary`: Build the canary Electrobun desktop app +- `bun run dev:daemon`: Start the daemon with Bun watch mode +- `bun run build:daemon`: Compile the daemon binary - `bun run docs:update [commit-or-range]`: Ask a detected coding-agent CLI to update first-party documentation for a commit or revision range; use `--dry-run` to inspect the prompt - `bun run subtree list`: List configured vendored Git subtrees - `bun run subtree status [name]`: Inspect subtree metadata and local dirtiness diff --git a/skills-lock.json b/skills-lock.json index 7f84ca2..eb727e8 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -25,6 +25,12 @@ "skillPath": "cron-jobs/SKILL.md", "computedHash": "298eb217e7009f128416a97a172ccaa9325e0d3c2ef3d29fc4b894011ebc539d" }, + "flue": { + "source": "withastro/flue", + "sourceType": "github", + "skillPath": "skills/flue/SKILL.md", + "computedHash": "c9ccd18babb912f52037e42b674a6c0de09d0459331000b11be98d31687f35fd" + }, "rivetkit": { "source": "rivet-dev/skills", "sourceType": "github",