Skip to content
Merged
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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
name: Bug report
description: Something doesn't work as it should.
labels: [bug]
body:
- type: markdown
attributes:
value: |
Thanks for reporting. **Security problems go to SECURITY.md, not here.**
Don't paste tokens, cookies, API keys or private messages. Settings → Diagnostics exports a report with those removed.
- type: textarea
id: what
attributes:
label: What happened
description: What you did, what you expected, and what happened instead.
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
placeholder: |
1. Connect …
2. Send …
3. See …
validations:
required: true
- type: dropdown
id: area
attributes:
label: Area
options:
- Inbox and chat
- Approvals
- Ask an agent / drafts
- Notifications
- Connector: Grok Bot
- Connector: Muse
- Connector: ChatGPT Dots
- Connector: Cue
- Agents on the server (Concierge, A2A, ACP, endpoint)
- Local dev stack (dev:up, Synapse, Postgres)
- Mobile
- Other
validations:
required: true
- type: input
id: version
attributes:
label: Commit or version
description: "`git rev-parse --short HEAD`"
- type: input
id: macos
attributes:
label: macOS version and Mac
placeholder: macOS 26.1, Apple M3
- type: textarea
id: logs
attributes:
label: Logs or diagnostics
description: The relevant part of `.local/logs/<service>.log`, or the exported diagnostics. Check it has no private content first.
render: text
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Report a security vulnerability
url: https://github.com/DolphinMiner/agentstudio/security/advisories/new
about: Privately, so it can be fixed before it's public. See SECURITY.md.
24 changes: 24 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Feature request
description: Suggest an idea or a change.
labels: [enhancement]
body:
- type: textarea
id: problem
attributes:
label: The problem
description: What are you trying to do, and what gets in the way today?
validations:
required: true
- type: textarea
id: idea
attributes:
label: What you'd like
description: How it could work. Sketches welcome.
- type: textarea
id: alternatives
attributes:
label: Alternatives you've considered
- type: markdown
attributes:
value: |
New connectors for third-party services must keep to personal use with your own account (see README). Check docs/roadmap.md first: it may already be planned.
13 changes: 13 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
## What and why

<!-- What does this change, and why? Link the issue it closes, if any. -->

## How I tested it

<!-- Unit tests, the e2e specs you ran (`cd e2e && npx playwright test specs/<spec>.ts`), and anything you checked by hand. -->

## Checklist

- [ ] Docs updated where behavior changed (`docs/`, README, `docs/clients.md` test ids)
- [ ] No tokens, cookies, API keys or real messages in code, fixtures or logs
- [ ] Connector changes keep to personal use with the user's own account (see CONTRIBUTING.md)
50 changes: 50 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
name: CI

on:
push:
branches: [main, "feat/**"]
pull_request:

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

jobs:
go:
name: Go (vet, test)
runs-on: ubuntu-latest
defaults:
run:
working-directory: server
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: server/go.mod
cache-dependency-path: server/go.sum
# v0.1 has no end-to-end encryption, so mautrix is built without libolm (-tags nocrypto).
# The integration tests need the local stack and skip themselves here (AGENTSTUDIO_IT unset).
- run: go vet -tags nocrypto ./...
- run: go test -tags nocrypto ./...

typescript:
name: TypeScript (typecheck, unit tests)
runs-on: ubuntu-latest
env:
# Unit tests don't start Electron; skip downloading it.
ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm --filter @agentstudio/core build
- run: pnpm -r --if-present typecheck
- run: pnpm run test:dev
- run: pnpm -r --if-present test
52 changes: 52 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Dependencies
node_modules/

# Local dev stack: databases, Synapse, logs, generated configs and secrets
.local/

# Build output
dist/
out/
build/
*.tsbuildinfo
server/bin/
/server/agentstudio-*
apps/mobile/web-build/

# Expo / React Native
.expo/
apps/mobile/ios/
apps/mobile/android/

# Tests
coverage/
test-results/
playwright-report/
blob-report/
playwright/.cache/
e2e-smoke/artifacts/
apps/desktop/e2e-smoke/artifacts/

# Environment and secrets
.env
.env.*
!.env.example
*.pem
*.p12
*.key

# Logs
*.log
npm-debug.log*
pnpm-debug.log*

# Editors and OS
.DS_Store
.idea/
.vscode/*
!.vscode/extensions.json
*.swp

# Claude Code (per-user)
.claude/settings.local.json
.claude/worktrees/
50 changes: 50 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# AgentStudio: working agreement for humans and coding agents

AgentStudio is an open-source inbox for your chats and your AI agents (Apache-2.0). Read these first; they are the contracts:

- `docs/architecture.md`: scope, processes, ports, layout
- `docs/api.md`: REST API
- `docs/agent-protocol.md`: how agents connect
- `docs/matrix-events.md`: Matrix conventions, custom events, demo network
- `docs/clients.md`: screens and the `data-testid` contract used by e2e
- `docs/connectors.md`: the Mac app's connectors for Grok Bot, Muse, ChatGPT Dots and Cue (personal use only: see README)
- `docs/roadmap.md`: what's done and what's next
- `CONTRIBUTING.md`, `SECURITY.md`: how to contribute, and how to report a vulnerability

When code and these docs disagree, fix whichever one is wrong in the same change. Never leave them out of sync.

## Commands

| Command | What |
|---|---|
| `pnpm install` | install JS workspace deps |
| `pnpm dev:up` | build Go binaries and start the whole local stack (idempotent) |
| `pnpm dev:down` | stop everything |
| `pnpm dev:status` | show process health |
| `pnpm dev:reset` | stop and wipe `.local/` |
| `pnpm dev:desktop` | run the Electron app (electron-vite dev mode) against the local stack |
| `pnpm dev:mobile` | run Expo (web) against the local stack on http://localhost:18300 |
| `pnpm test` | unit tests: stack manager (`node --test dev/stack.test.mjs`), Go (`cd server && go test -tags nocrypto ./...`) and TS (vitest) |
| `pnpm test:e2e` | e2e (Playwright projects `desktop` and `mobile-web`) against the local stack; starts it if needed and builds both apps. See `e2e/README.md` |

Runtime state, logs and generated secrets live in `.local/`, which is git-ignored:

- logs: `.local/logs/<process>.log`
- generated env: `.local/env`

## Conventions

- **Go:**
- module `github.com/DolphinMiner/agentstudio/server`
- Go 1.26, `log/slog` for logs, `pgx/v5` for Postgres
- bridges are built on `maunium.net/go/mautrix` bridgev2
- always build/test with `-tags nocrypto` (no E2EE in v0.1, so mautrix is built without libolm; plain `go build ./...` fails on `olm/olm.h`)
- never log message bodies or tokens
- **TypeScript:**
- strict mode, ESM, pnpm workspaces
- `@agentstudio/core` must not import DOM, Node or React Native APIs
- React 19 function components
- **Tests:** select elements only by `data-testid` / `testID` from `docs/clients.md`. Use no sleeps when a condition can be awaited.
- **No Docker.** The local stack runs native processes: Homebrew Postgres 18 in a private cluster under `.local/pg`, and Synapse in a uv venv.
- **Keep diffs focused.** Do not reformat files you did not change.
- **Connectors for third-party services** reach the user's own agents with the user's own account, on the user's Mac. Don't add anything that works at scale, for other people's accounts, or around a service's limits. Never commit real transcripts, tokens or cookies; scrub fixtures to their structure.
1 change: 1 addition & 0 deletions CLAUDE.md
13 changes: 13 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Code of Conduct

AgentStudio follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

In short: be welcoming, be kind, and assume good intent. Harassment, insults, and personal or political attacks aren't accepted, in any of the project's spaces (issues, pull requests, discussions, and anywhere you represent the project).

## Reporting

If someone's behavior concerns you, report it privately to the maintainers: open a private security advisory (**Security → Report a vulnerability**) and say it's a conduct report, or contact a maintainer directly. Reports are handled confidentially.

## Enforcement

Maintainers decide on the response, following the Contributor Covenant's enforcement guidelines: from a private correction to a temporary or permanent ban from the project's spaces.
52 changes: 52 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Contributing to AgentStudio

Thanks for helping. AgentStudio is alpha, so the code moves fast; small, focused changes are the easiest to review.

## Before you start

- **Bugs:** open an issue with the bug template. For anything security-related, follow [SECURITY.md](SECURITY.md) instead.
- **Features and bigger changes:** open an issue (or a discussion) first, so we can agree on the approach before you write the code. The plan lives in [docs/roadmap.md](docs/roadmap.md).
- **Read the contracts.** [AGENTS.md](AGENTS.md) lists the docs that define how things work (architecture, API, agent protocol, Matrix events, the client test ids, connectors). When code and docs disagree, fix the wrong one in the same change.

## Set up

Requirements: macOS, Go 1.26+, Node 22+, pnpm, Homebrew PostgreSQL 18 and uv.

```bash
pnpm install
pnpm dev:up # Postgres, Synapse, the API, bridges and reference agents
pnpm dev:desktop # the Mac app in dev mode
```

More in [README.md](README.md).

## Make the change

- **Go:** build and test with `-tags nocrypto`. Use `log/slog`, and never log message bodies or tokens.
- **TypeScript:** strict mode, ESM. `@agentstudio/core` must not import DOM, Node or React Native APIs.
- **UI:** follow [docs/design.md](docs/design.md). Icons come from Lucide (desktop) and Ionicons (mobile); service images from `packages/brand`. Don't draw icons by hand.
- **Tests:** select elements only by the `data-testid` values in [docs/clients.md](docs/clients.md), and wait for conditions instead of sleeping.
- **Keep diffs focused.** Don't reformat code you didn't change.

### Connectors for other services

Changes to the Grok Bot, Muse, Dots or Cue connectors must keep to their purpose: reaching **your own** agents, with **your own** account, on **your own** Mac. We won't accept changes that make them work at scale, for other people's accounts, or that get around a service's limits or protections. See the note in [README.md](README.md#disclaimer).

When a service changes, start the app with `AGENTSTUDIO_CONNECTOR_TRACE=1` (or `AGENTSTUDIO_CONNECTOR_TRACE_NETWORK=1` for Muse and Dots) and compare with the fakes in `e2e/fakes/agents.ts`. Never commit a real transcript or token; scrub fixtures down to their structure, like `apps/desktop/test/fixtures/grok-entries.json`.

## Test

```bash
pnpm test # unit tests: stack manager, Go, TypeScript
pnpm test:e2e # Playwright against the local stack (desktop and mobile web)
```

Run the e2e specs your change touches, for example `cd e2e && npx playwright test specs/local-agents.spec.ts --project desktop`. CI runs the unit tests and type checks on every pull request.

## Send it

- Open a pull request against the development branch with the template filled in: what changed, why, and how you tested it.
- Update the docs in the same pull request when behavior changes.
- By contributing, you agree that your contribution is licensed under the [Apache License 2.0](LICENSE).

Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md).
Loading
Loading