Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
10 changes: 5 additions & 5 deletions .agents/skills/add-api-endpoint/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
---
name: add-api-endpoint
description: Add or modify an OpenBot Hono HTTP route or ConnectRPC method while preserving authentication, provider boundaries, Web-standard request handling, generated contracts, and focused tests.
description: Add or modify a Dispatch Hono HTTP route or ConnectRPC method while preserving authentication, provider boundaries, Web-standard request handling, generated contracts, and focused tests.
metadata:
author: openbot
author: dispatch
version: "1.0.0"
argument-hint: <surface> <change-summary>
---

# Add Or Modify An API Endpoint

OpenBot uses ConnectRPC for authenticated control operations and Hono for protocol-native HTTP routes. Keep handlers thin and portable across the local Node server and Vercel Functions.
Dispatch uses ConnectRPC for authenticated control operations and Hono for protocol-native HTTP routes. Keep handlers thin and portable across the local Node server and Vercel Functions.

## Process

1. Choose the surface:
- ConnectRPC: control-plane methods used by OpenBot clients.
- ConnectRPC: control-plane methods used by Dispatch clients.
- Hono: setup unlock, health, ChatKit compatibility, or signed Tilde webhooks/tools.
2. For ConnectRPC, edit the owning proto, run `pnpm contracts:generate`, then implement the method in `apps/control-service` or `apps/computer-service`.
3. For Hono, edit `apps/control-service/src/app.ts` and keep Web-standard request handling.
4. Validate input at the edge. Use protobuf types for Connect and Zod or narrow parsing for untyped HTTP payloads.
5. Apply the existing authorization mechanism before business work.
6. Delegate external behavior to the owning provider package's `src/core.ts` or `src/core/index.ts` contract and matching adapter. Keep route code provider-neutral.
7. Preserve `Request.signal` through `ProviderCallContext`.
8. When an OpenBot client consumes the endpoint, add or extend the grouped contract and client call in `packages/client-runtime` in the same change. Web and Electron consume it from there; they never declare the request, response, or event shape themselves.
8. When a Dispatch client consumes the endpoint, add or extend the grouped contract and client call in `packages/client-runtime` in the same change. Web and Electron consume it from there; they never declare the request, response, or event shape themselves.
9. Add focused tests beside the server surface. Test status/code, response shape, authorization, and the owning provider call.

## Authentication And Scope
Expand Down
10 changes: 5 additions & 5 deletions .agents/skills/add-db-changes/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
name: add-db-changes
description: Add or alter OpenBot's Drizzle schema, SQLite-compatible migration statements, libSQL/Turso persistence code, and migration tests without moving Tilde-owned data or secrets into the control database.
description: Add or alter Dispatch's Drizzle schema, SQLite-compatible migration statements, libSQL/Turso persistence code, and migration tests without moving Tilde-owned data or secrets into the control database.
metadata:
author: openbot
author: dispatch
version: "1.0.0"
argument-hint: <change-summary>
---

# Database Schema And Query Changes

OpenBot uses Drizzle over local SQLite or remote libSQL/Turso. The database stores installation, onboarding, sandbox lease, and deployment checkpoint state only. Tilde owns agents, chats, tools, skills, and memory. `EnvProvider` owns secrets.
Dispatch uses Drizzle over local SQLite or remote libSQL/Turso. The database stores installation, onboarding, sandbox lease, and deployment checkpoint state only. Tilde owns agents, chats, tools, skills, and memory. `EnvProvider` owns secrets.

The source of truth is:

Expand Down Expand Up @@ -42,8 +42,8 @@ packages/db/src/migrations.test.ts
## Tests

```bash
pnpm --filter @tryopenbot/db test
pnpm --filter @tryopenbot/control-service test
pnpm --filter @trytilde/dispatch-db test
pnpm --filter @trytilde/dispatch-control-service test
pnpm check
```

Expand Down
20 changes: 10 additions & 10 deletions .agents/skills/create-or-update-agent/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: create-or-update-agent
description: Create or modify the full primary OpenBot agent or one of its full subagents under configuration/agent, including its ChatKit endpoint, instructions, instrumentation, tools, skills, library code, and sandbox workspace seed. Use whenever adding an agent, changing an agent's filesystem layout or entrypoint, or updating agent build and deployment discovery.
description: Create or modify the full primary Dispatch agent or one of its full subagents under configuration/agent, including its ChatKit endpoint, instructions, instrumentation, tools, skills, library code, and sandbox workspace seed. Use whenever adding an agent, changing an agent's filesystem layout or entrypoint, or updating agent build and deployment discovery.
---

# Create Or Update Agent
Expand Down Expand Up @@ -34,7 +34,7 @@ configuration/
```

- The primary path has the stable ID `factory`. Derive each subagent ID from its directory name using lowercase kebab-case matching `^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$`.
- To create a subagent interactively, run `pnpm openbot new-agent` and enter its display name. From an agent or other non-interactive shell, run `pnpm openbot new-agent "<display name>"`. The CLI loads `configuration/templates/agent/**/*.hbs`, derives the ID, strips each `.hbs` suffix, materializes the complete full tree below `configuration/agent/subagents/`, then invokes idempotent development provisioning for every authored agent. Customize the generated files afterward. Do not hand-copy another agent directory or duplicate remote provisioning in the command.
- To create a subagent interactively, run `pnpm tilde new-agent` and enter its display name. From an agent or other non-interactive shell, run `pnpm tilde new-agent "<display name>"`. The CLI loads `configuration/templates/agent/**/*.hbs`, derives the ID, strips each `.hbs` suffix, materializes the complete full tree below `configuration/agent/subagents/`, then invokes idempotent development provisioning for every authored agent. Customize the generated files afterward. Do not hand-copy another agent directory or duplicate remote provisioning in the command.
- Treat `configuration/templates/agent/` as fork-owned defaults for future agents. Change it when all newly created agents need different SDK imports, environment variables, tools, skills, instructions, or workspace seeds. Template edits never rewrite existing agents.
- Never import provider packages or `configuration/index.ts` from authored agents. Integrate model, MCP, skills, Composio, and other vendor SDKs directly in agent code so provider abstractions do not constrain agent development.
- Require `agent.ts` and `instructions.ts`.
Expand All @@ -43,8 +43,8 @@ configuration/
- Keep reusable import-only TypeScript in `lib/`.
- Default-export one Vercel AI SDK tool from each file in `tools/`.
- Require the scaffolded computer tools `await_shell.ts`, `bash.ts`, `copy_from_computer.ts`, `copy_to_computer.ts`, `read_file.ts`, `write_file.ts`, `glob.ts`, `grep.ts`, and `screenshot.ts`. Import them explicitly in `agent.ts` under matching tool names.
- Keep each authored computer-tool file as a thin default export from `@tryopenbot/computer-tools`, passing the path-derived agent ID as a fixed option. Shared implementations and Zod schemas belong to that non-provider runtime utility package, not in each agent and not in the proto package. Never call Microsandbox, Vercel Sandbox, `fetch`, or an untyped computer endpoint from an agent tool.
- Authenticate the typed client with the SOPS-installed `OPENBOT_COMPUTER_SERVICE_API_KEY`. Do not generate, derive, return, log, or persist a second agent-local computer credential.
- Keep each authored computer-tool file as a thin default export from `@trytilde/dispatch-computer-tools`, passing the path-derived agent ID as a fixed option. Shared implementations and Zod schemas belong to that non-provider runtime utility package, not in each agent and not in the proto package. Never call Microsandbox, Vercel Sandbox, `fetch`, or an untyped computer endpoint from an agent tool.
- Authenticate the typed client with the SOPS-installed `DISPATCH_COMPUTER_SERVICE_API_KEY`. Do not generate, derive, return, log, or persist a second agent-local computer credential.
- Store specification-conformant skill Markdown files or skill folders under `skills/`.
- Preserve the scaffolded `skills/create-agent/SKILL.md`; it teaches runtime agents to use the non-interactive `new-agent` command from a writable source checkout and to leave deployment explicit.
- Keep skills and sandbox workspace seeds inside their owning agent directory. Never create, read, or migrate content to global `configuration/skills/` or `configuration/sandbox/` directories; those paths are unsupported.
Expand All @@ -53,32 +53,32 @@ configuration/

## Instrument startup

Use `defineInstrumentation({ setup })` from `@tryopenbot/configuration/instrumentation`. Keep `configuration/instrumentation.ts` installation-wide and `instrumentation.ts` in either full agent directory agent-specific. Both are optional at runtime; an empty `setup` function is valid.
Use `defineInstrumentation({ setup })` from `@trytilde/dispatch-configuration/instrumentation`. Keep `configuration/instrumentation.ts` installation-wide and `instrumentation.ts` in either full agent directory agent-specific. Both are optional at runtime; an empty `setup` function is valid.

Run global instrumentation first, agent instrumentation second, and import `agent.ts` only afterward. Supply the path-derived `agentName`. Instrumentation is a server startup hook, not an agent tool or request hook.

## Preserve build and deployment behavior

Treat each `agent.ts` as an independently buildable agent-service entrypoint. Keep local development's combined server and production's separate agent artifacts aligned. Vercel builds must remain concurrent across agents.

All agents share one OpenBot Computer, filesystem, and process identity. If `sandbox/workspace/**` contains files, deployment seeds them once into `/workspace/<agent-id>`. Commands and relative paths default there, but agents can use absolute paths, inspect sibling directories, and administer the shared machine. Treat the agent directory as an organizational default, never as a security boundary.
All agents share one Dispatch Computer, filesystem, and process identity. If `sandbox/workspace/**` contains files, deployment seeds them once into `/workspace/<agent-id>`. Commands and relative paths default there, but agents can use absolute paths, inspect sibling directories, and administer the shared machine. Treat the agent directory as an organizational default, never as a security boundary.

Keep the authored directory name `sandbox/` and Eve-compatible tool filenames only because OpenBot follows Eve's project layout where possible. Use Computer for APIs, environment variables, classes, and prose about the runtime. Computer-service owns agent-ID validation, default-directory selection, and background-job ownership; callers must not send a username or treat the ID as authorization for filesystem paths.
Keep the authored directory name `sandbox/` and Eve-compatible tool filenames only because Dispatch follows Eve's project layout where possible. Use Computer for APIs, environment variables, classes, and prose about the runtime. Computer-service owns agent-ID validation, default-directory selection, and background-job ownership; callers must not send a username or treat the ID as authorization for filesystem paths.

Create `/workspace/<agent-id>` only when the authored `sandbox/workspace/**` is populated, and seed it only once. Never overwrite an existing deployed directory during an ordinary agent deployment. State clearly when changing seed files that already-deployed agents will not receive those changes without explicit future reconciliation or computer replacement. Reject symlinks in agent source and workspace seeds.

Scaffold `sandbox/workspace/.profile`. Bash tools run `bash -lc` with `HOME=/workspace/<agent-id>`, so this is the deterministic startup file for every agent Bash command. Let it source an optional `.bashrc`; keep secrets out of both files. Treat profile edits like every other one-time workspace seed change.

## Initialize examples

Keep `openbot init` seeding the default Handlebars files into `configuration/templates/agent/` without overwriting fork edits, then using them to generate the full primary Factory agent. `openbot new-agent` uses the same template for full subagents. The initial agent includes:
Keep `tilde init` seeding the default Handlebars files into `configuration/templates/agent/` without overwriting fork edits, then using them to generate the full primary Factory agent. `tilde new-agent` uses the same template for full subagents. The initial agent includes:

- `agent.ts` importing `instructions.ts`
- an empty global and agent instrumentation hook
- all standard computer tools; factory-only skills (create-agent, test-agent, deploy-agent, develop-openbot) live in `configuration/templates/factory/` and render into the primary agent only
- all standard computer tools; factory-only skills (create-agent, test-agent, deploy-agent, develop-dispatch) live in `configuration/templates/factory/` and render into the primary agent only
- a sandbox workspace seed with `.profile`

Generate source files from the fork-owned Handlebars template through `@tryopenbot/utilities`; do not embed whole generated files in TypeScript strings. The CLI's packaged assets only seed a missing template during init.
Generate source files from the fork-owned Handlebars template through `@trytilde/dispatch-utilities`; do not embed whole generated files in TypeScript strings. The CLI's packaged assets only seed a missing template during init.

## Verify

Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/create-or-update-agent/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
interface:
display_name: "Create or Update Agent"
short_description: "Maintain OpenBot agent project layouts"
default_prompt: "Use $create-or-update-agent to create or update the primary OpenBot agent or a full subagent under configuration/agent."
short_description: "Maintain Dispatch agent project layouts"
default_prompt: "Use $create-or-update-agent to create or update the primary Dispatch agent or a full subagent under configuration/agent."
Loading