@pantheon.ai/agents 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +99 -74
  2. package/dist/index.js +1985 -29863
  3. package/package.json +3 -7
package/README.md CHANGED
@@ -1,120 +1,145 @@
1
- # `@pantheon.ai/agents`
1
+ # `@pantheon.ai/agents` CLI
2
2
 
3
- This package provides the `pantheon-agents` CLI for managing agent configs and tasks backed by a TiDB/MySQL task list.
3
+ `pantheon-agents` helps you:
4
+ - configure an agent for a Pantheon project
5
+ - queue tasks for that agent
6
+ - run the agent worker loop
7
+ - check task/config status
4
8
 
5
- It includes:
9
+ ## Required Configuration (Users and Developers)
6
10
 
7
- - A **runner loop** (`pantheon-agents run <agent>`) that executes queued tasks via Pantheon and persists status/output to TiDB.
8
- - A **client-facing server** (`pantheon-agents server`) that exposes the same task operations over **HTTP REST** and **MCP (HTTP+SSE)**.
11
+ `.env` is required for both users and developers.
9
12
 
10
- ## Build
13
+ Create/update `.env`:
11
14
 
12
15
  ```bash
13
- npm run -w @pantheon.ai/agents build
16
+ DATABASE_URL=mysql://root@127.0.0.1:4000/pantheon_agents
17
+ PANTHEON_API_KEY=<your_pantheon_api_key>
18
+ DEFAULT_PANTHEON_PROJECT_ID=<optional_default_project_id>
19
+ DEFAULT_PANTHEON_ROOT_BRANCH_ID=<optional_default_root_branch_id>
14
20
  ```
15
21
 
16
- ## Environment variables
22
+ ## Database Setup (One-Time)
17
23
 
18
- - `DATABASE_URL` (required): MySQL/TiDB connection string for the task list database.
19
- - `PANTHEON_API_KEY` (required for some commands): Used to query/execute Pantheon branches.
20
- - `PANTHEON_AGENTS_API_TOKEN` (optional): Bearer token for API auth when running `pantheon-agents server` (defaults for `--token`).
21
- - `DEFAULT_PANTHEON_PROJECT_ID` (optional): Default project id used by CLI commands when `--project-id` is omitted.
22
- - `DEFAULT_PANTHEON_ROOT_BRANCH_ID` (optional): Default root branch id used by `pantheon-agents config` when `--root-branch-id` is omitted.
24
+ If you already have a TiDB/MySQL database with the required tables, skip this section.
23
25
 
24
- Command requirements:
26
+ ### 1) Start local TiDB (with `tiup`)
25
27
 
26
- - `pantheon-agents add-task|delete-task|show-config|show-tasks`: requires `DATABASE_URL`
27
- - `pantheon-agents run`: requires `DATABASE_URL` + `PANTHEON_API_KEY`
28
- - `pantheon-agents config`: requires `DATABASE_URL`, and requires `PANTHEON_API_KEY` only when neither `--root-branch-id` nor `DEFAULT_PANTHEON_ROOT_BRANCH_ID` is provided
29
- - `pantheon-agents reconfig`: requires `DATABASE_URL` + `PANTHEON_API_KEY`
30
- - `pantheon-agents server`: requires `DATABASE_URL`; auth uses `--token` or env `PANTHEON_AGENTS_API_TOKEN` (unless `--no-auth`)
28
+ ```bash
29
+ npm run dev:db:start
30
+ # same as: tiup playground --without-monitor --tag pantheon-agents
31
+ ```
31
32
 
32
- Notes:
33
+ Keep this terminal running.
34
+ Open another terminal for the next steps.
33
35
 
34
- - `PANTHEON_API_KEY` is required for config re-bootstrap server endpoints/tools (`configs.reconfig`), but not for config reads (`configs.get`).
35
- - `config`, `reconfig`, `add-task`, and `show-config` can omit `--project-id` when `DEFAULT_PANTHEON_PROJECT_ID` is set.
36
+ ### 2) Execute the first SQL DDL
36
37
 
37
- ## Show tasks output modes
38
+ ```bash
39
+ mysql --host 127.0.0.1 --port 4000 -u root -e "CREATE DATABASE IF NOT EXISTS pantheon_agents;"
40
+ ```
38
41
 
39
- - Default: concise one-line entries.
40
- - Table output: use `--no-concise`.
41
- - JSON output: use `--json`.
42
- - Time filter: use `--since <time>` (alias: `--from <time>`) with an ISO-8601 timestamp (e.g. `2026-02-12T00:00:00Z`) to only include tasks with `queued_at >= since`.
42
+ ### 3) Initialize tables
43
+
44
+ `src/db/schema/tidb.sql` already includes the DB creation statement as the first line.
45
+ To avoid running it twice, apply the rest of the file to `pantheon_agents`:
46
+
47
+ ```bash
48
+ sed '1d' src/db/schema/tidb.sql | mysql --host 127.0.0.1 --port 4000 -u root pantheon_agents
49
+ ```
43
50
 
44
- ## DB schema / migrations
51
+ ## Developer Local Setup
45
52
 
46
- The schema lives in `packages/agents/src/db/schema/tidb.sql`.
53
+ This section is only for developing this package locally.
54
+ Run these steps inside `packages/agents`.
47
55
 
48
- If you have an existing DB, apply:
56
+ ### 1) Install and build
49
57
 
50
- ```sql
51
- ALTER TABLE task ADD COLUMN cancelled_at DATETIME NULL;
52
- ALTER TABLE task ADD COLUMN parent_task_id BIGINT NULL;
53
- CREATE INDEX idx_task_agent_parent ON task(agent, parent_task_id);
54
- ALTER TABLE agent_project_config ADD COLUMN setup_script VARCHAR(255) NOT NULL DEFAULT 'codex';
58
+ ```bash
59
+ npm install
60
+ npm run build
55
61
  ```
56
62
 
57
- ## Start the server (HTTP + MCP)
63
+ ## Quick Start
58
64
 
59
- Auth is enabled by default. Provide a token via env or flag:
65
+ Use `pantheon-agents ...`.
66
+ If you omit `--project-id`, set `DEFAULT_PANTHEON_PROJECT_ID` in `.env` first.
60
67
 
61
68
  ```bash
62
- export PANTHEON_AGENTS_API_TOKEN="your-token"
63
- pantheon-agents server --host 127.0.0.1 --port 8000 --base-path /
69
+ npm install -g @pantheon.ai/agents@latest
70
+
71
+ pantheon-agents --help
64
72
  ```
65
73
 
66
- To disable auth for local-only use (not recommended):
74
+ ### 1) Queue a config task
67
75
 
68
76
  ```bash
69
- pantheon-agents server --no-auth
77
+ # first-time config for an agent/project requires --role
78
+ pantheon-agents config <agent-name> "<config prompt>" --project-id <project-id> --role <role>
79
+
80
+ # further config requests can omit --role, or pass --role to update it
81
+ pantheon-agents config <agent-name> "<config prompt>" --project-id <project-id>
70
82
  ```
71
83
 
72
- ### REST API
84
+ Example:
73
85
 
74
- Base path: `/api/v1`
86
+ ```bash
87
+ # explicit project id
88
+ pantheon-agents config reviewer "Download some files" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617 --role developer
89
+
90
+ # update role on later config request
91
+ pantheon-agents config reviewer "Switch to review workflow" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617 --role reviewer
92
+ ```
75
93
 
76
- Examples:
94
+ ### 2) Add a task
77
95
 
78
96
  ```bash
79
- TOKEN="$PANTHEON_AGENTS_API_TOKEN"
97
+ # explicit project id
98
+ pantheon-agents add-task <agent-name> "<task prompt>" --project-id <project-id>
80
99
 
81
- curl -sS -H "Authorization: Bearer $TOKEN" \\
82
- http://127.0.0.1:8000/api/v1/agents
100
+ # or use DEFAULT_PANTHEON_PROJECT_ID from .env
101
+ pantheon-agents add-task <agent-name> "<task prompt>"
102
+ ```
83
103
 
84
- curl -sS -H "Authorization: Bearer $TOKEN" \\
85
- "http://127.0.0.1:8000/api/v1/agents/<agent>/tasks?status=pending,running&order_by=queued_at&order_direction=desc&limit=50"
104
+ Example:
86
105
 
87
- curl -sS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \\
88
- -X POST http://127.0.0.1:8000/api/v1/agents/<agent>/tasks \\
89
- -d '{ "project_id": "<project_id>", "task": "Do the thing", "parent_task_id": "<task_id_optional>" }'
106
+ ```bash
107
+ # explicit project id
108
+ pantheon-agents add-task reviewer "Review the latest backend changes" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617
90
109
 
91
- curl -sS -H "Authorization: Bearer $TOKEN" \\
92
- -X POST http://127.0.0.1:8000/api/v1/agents/<agent>/tasks/<task_id>/cancel
110
+ # or use DEFAULT_PANTHEON_PROJECT_ID from .env
111
+ pantheon-agents add-task reviewer "Review the latest backend changes"
112
+ ```
93
113
 
94
- curl -sS -H "Authorization: Bearer $TOKEN" \\
95
- -X DELETE http://127.0.0.1:8000/api/v1/agents/<agent>/tasks/<task_id>
114
+ ### 3) Run the worker
96
115
 
97
- # Get agent config
98
- curl -sS -H "Authorization: Bearer $TOKEN" \\
99
- http://127.0.0.1:8000/api/v1/agents/<agent>/configs/<project_id>
116
+ ```bash
117
+ pantheon-agents run <agent-name>
118
+ ```
119
+
120
+ ### 4) Check status
100
121
 
101
- # Re-bootstrap agent config (like `pantheon-agents reconfig`)
102
- curl -sS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \\
103
- -X POST http://127.0.0.1:8000/api/v1/agents/<agent>/configs/<project_id>/reconfig \\
104
- -d '{ "role": "reviewer", "skills": ["style-reviewer"], "setup_script": "custom-build" }'
122
+ ```bash
123
+ pantheon-agents show-tasks <agent-name>
124
+
125
+ # explicit project id
126
+ pantheon-agents show-config <agent-name> --project-id <project-id>
127
+
128
+ # or use DEFAULT_PANTHEON_PROJECT_ID from .env
129
+ pantheon-agents show-config <agent-name>
105
130
  ```
106
131
 
107
- ### MCP (HTTP+SSE)
132
+ ## Common Commands
108
133
 
109
- The MCP endpoint is exposed at `/mcp` (and `/mcp/messages` for client POSTs).
134
+ ```bash
135
+ pantheon-agents show-tasks --all
136
+ pantheon-agents get-task <agent-name> <task-id>
137
+ pantheon-agents cancel-task <agent-name> <task-id> [reason] --yes
138
+ pantheon-agents delete-task <agent-name> <task-id>
139
+ ```
110
140
 
111
- Tools:
141
+ For full options of any command:
112
142
 
113
- - `agents.list`
114
- - `tasks.list`
115
- - `tasks.get`
116
- - `tasks.create`
117
- - `tasks.cancel`
118
- - `tasks.delete`
119
- - `configs.get`
120
- - `configs.reconfig`
143
+ ```bash
144
+ pantheon-agents <command> --help
145
+ ```