superagent-skill 0.1.0 → 0.4.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.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # superagent
2
2
 
3
- An agent that turns requests from GitHub and Feishu into tickets, and runs each ticket on the coding agent you choose.
3
+ An agent that turns requests from GitHub, Feishu, and Twitter/X into tickets, and runs each ticket on the coding agent you choose.
4
4
 
5
5
  - **No web panel.** State is JSON files under `stateDir`, so `ls` and `cat` answer what a dashboard would.
6
6
  - **No vendor lock-in.** The executor is a configuration value: `claude`, `codex` or `opencode`, behind one interface.
@@ -19,12 +19,26 @@ ln -sf "$PWD/bin/superagent.js" ~/.local/bin/superagent
19
19
  ```sh
20
20
  mkdir my-agent && cd my-agent
21
21
  superagent init # writes settings.yaml and state/
22
- $EDITOR settings.yaml # set github.repository, executor.agent, allowed lists
22
+ superagent setup # reads the GitHub account and the Feishu chat from `gh` and `lark-cli`
23
+ $EDITOR settings.yaml # choose executor.agent; adjust what setup filled
23
24
  superagent doctor # confirms the chosen agent is installed
24
25
  superagent run . -p "Read README.md and summarise it in one sentence."
25
26
  superagent status
26
27
  ```
27
28
 
29
+ `superagent setup` asks the CLIs that already know the answers, so no id is copied from a web page:
30
+
31
+ ```sh
32
+ superagent setup . # both Sources, from the CLIs in settings.yaml
33
+ superagent setup . github # only the GitHub section
34
+ superagent setup . feishu --chat Team # the chat by name instead of id
35
+ superagent setup . --allow alice,bob # who may ask; a Feishu user name becomes an open id
36
+ ```
37
+
38
+ It writes the login `gh` acts as, proves the repository is readable, lists the bot's chats, sets `feishu.syncChat` so
39
+ the chat's members may ask, and turns each `--allow` name into the member's open id. It keeps every other line of
40
+ `settings.yaml`. A CLI that cannot answer leaves that section as it was and exits with 1.
41
+
28
42
  `superagent run` is the smallest end-to-end test: it starts the configured agent in the current directory, waits for the
29
43
  turn to end, and prints the report the agent left in `.superagent/report.json`.
30
44
 
@@ -69,25 +83,47 @@ A round reads the agent account's GitHub notifications, keeps the ones for `gith
69
83
  `github.allowed`, builds a Trigger for each mention, and accepts it as a ticket. The ticket runs on
70
84
  `executor.agent`; its report is written under `stateDir/work/<ticket>/.superagent/log.md`.
71
85
 
86
+ A message in a chat the bot reads that names no one is assessed by one `claude -p` call per message, against the
87
+ `policy.rules` in `settings.yaml`. In `observe` mode the verdict is recorded and no ticket starts; `auto` accepts the
88
+ ones the assessor matches. `superagent status` lists the recent judgements.
89
+
72
90
  Arbitrary polling is not yet wired, so a person runs `poll` under cron or a systemd timer:
73
91
 
74
92
  ```cron
75
93
  */1 * * * * cd /path/to/install && superagent poll . --once >> state/poll.log 2>&1
76
94
  ```
77
95
 
96
+ ## Compare with dsh-superagent
97
+
98
+ [`docs/dsh-superagent-comparison.md`](docs/dsh-superagent-comparison.md)([中文版](docs/dsh-superagent-comparison.zh.md))
99
+ compares this project with the earlier `dsh-superagent` DSH bundle: what both keep, what each does differently, and where
100
+ this one is behind.
101
+
102
+ ## Always-on Agent Architecture
103
+
104
+ See [`docs/always-on-architecture.md`](docs/always-on-architecture.md)([中文版](docs/always-on-architecture.zh.md))
105
+ for how superagent incorporates the five core primitives from Anthropic's [*"Building always-on agents"*](https://claude.com/resources/articles/building-always-on-agents) (Event Inbox, Timers, Memory, Permissions, Outbox) and DeepSeek's Super-agent exploration: presence-aware attention routing, read-only autonomy, quiet hours batching, active watchers, and token budget protection.
106
+
78
107
  ## Status
79
108
 
80
109
  Done and tested: the domain, file-backed state, the settings file, three agent runners (verified against the real CLIs),
81
110
  the GitHub notification poller, the Feishu Source, worktree creation per ticket, the round loop, and delivery of the
82
- agent's report back to the conversation. The Feishu path is proven with a stand-in `lark-cli`; a live check against a real
83
- Feishu app is not done yet.
111
+ agent's report back to the conversation. The Feishu path is proven with a stand-in `lark-cli` and once end to end
112
+ against a real Feishu bot.
84
113
 
85
114
  ## Install once
86
115
 
87
116
  ```sh
88
- pnpm build
89
- mkdir ~/superagent && cd ~/superagent
90
- /path/to/superagent-skill/bin/superagent.js init # writes settings.yaml here
117
+ npm install -g superagent-skill
118
+ superagent init ~/my-superagent && cd ~/my-superagent
119
+ superagent doctor
120
+ ```
121
+
122
+ From a checkout instead, build it and link it yourself:
123
+
124
+ ```sh
125
+ pnpm install && pnpm build
126
+ ln -sf "$PWD/bin/superagent.js" ~/.local/bin/superagent # a directory on PATH
91
127
  ```
92
128
 
93
129
  Start the loop from that directory: `superagent poll` keeps running, and `superagent poll --once` runs one round, which
package/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: superagent
3
- description: Run an agent that turns requests from GitHub issues or Feishu chats into tickets and executes each ticket on a configurable coding agent (Claude Code, Codex, opencode). Use when the user wants an agent to watch a repository or a chat, act on @ mentions, and record its work as plain files instead of a dashboard; when they ask what superagent has done, which tickets are open, or to change which coding agent runs tickets.
3
+ description: Run an agent that turns requests from GitHub issues, Feishu chats, or Twitter/X mentions into tickets and executes each ticket on a configurable coding agent (Claude Code, Codex, opencode). Use when the user wants an agent to watch a repository, a chat, or Twitter keywords, act on @ mentions, and record its work as plain files instead of a dashboard; when they ask what superagent has done, which tickets are open, or to change which coding agent runs tickets.
4
4
  ---
5
5
 
6
6
  # Superagent
@@ -76,11 +76,76 @@ feishu:
76
76
  chats: [{ chatId: oc_..., name: Team }]
77
77
  allowed: [] # or set syncChat to copy the chat's members
78
78
  syncChat: oc_...
79
+ twitter:
80
+ cli: opencli # the CLI that acts as Twitter client
81
+ query: "superagent OR @mybot" # keywords or mentions to monitor
82
+ pollSeconds: 300 # how often to search for new tweets
83
+ allowed: [] # empty accepts any user matching query
79
84
  ```
80
85
 
81
86
  The agent acts only as the accounts those CLIs are signed in to. Never point `cli` at a personal login: everything the
82
87
  agent writes would appear under that person's name.
83
88
 
89
+ ### Messages that do not address the agent
90
+
91
+ A message in a chat the bot reads that names no one is assessed, once per message, by one `claude -p` call that prints
92
+ a verdict. Turn this on in `settings.yaml`:
93
+
94
+ ```yaml
95
+ policy:
96
+ mode: observe # off, observe, or auto
97
+ rules:
98
+ - id: unasked # the rule that says the message asks for work at all
99
+ name: Request
100
+ instruction: The discussion asks for a concrete change to this project.
101
+ - id: docs
102
+ name: Documentation
103
+ instruction: The change is to a document in the repository.
104
+ ```
105
+
106
+ `observe` records what `auto` would accept and starts nothing; `auto` accepts the candidates the assessor matches. The
107
+ `unasked` rule is required for an unaddressed message to start work. `superagent status` lists the recent
108
+ judgements under "Unaddressed messages". Keep `observe` until the judgements read right.
109
+
110
+ ## Always-On Autonomous Configuration
111
+
112
+ superagent implements the five core primitives from Anthropic's *"Building always-on agents"*:
113
+
114
+ ```yaml
115
+ # Presence detection & notification quiet hours
116
+ attention:
117
+ idleSecondsThreshold: 300 # consider user away after 5 minutes of input inactivity
118
+ quietHours:
119
+ enabled: true
120
+ start: "23:00"
121
+ end: "08:00"
122
+ morningDigestAt: "08:30"
123
+ minNotifyIntervalMinutes: 10
124
+ maxDailyNotifications: 25
125
+
126
+ # Token and wakeup budget guard (protects API spend)
127
+ budget:
128
+ autonomousCooldownSeconds: 180 # min cooldown between autonomous runs
129
+ maxAutonomousWakesPerDay: 48 # daily autonomous cap
130
+
131
+ # Proactive timers & recurring schedules
132
+ timers:
133
+ enabled: true
134
+ schedules:
135
+ - id: daily-check
136
+ intervalMinutes: 1440
137
+ prompt: "Report summary of open tickets."
138
+
139
+ # Active watchers for pull-based sources without webhooks
140
+ watchers:
141
+ - id: watch-prs
142
+ intervalMinutes: 10
143
+ command: "gh pr list --state open"
144
+ instruction: "Perform read-only code review on newly opened PRs."
145
+ ```
146
+
147
+ In autonomous runs (unaddressed messages, timers, watchers), tools are automatically restricted to read-only mode (`Read`, `Grep`, `Glob` / sandbox read-only) to prevent unintended mutations. When user input or mutation is required, the ticket asks a question and pauses in `blocked`/`attention` state.
148
+
84
149
  ## Rules to keep
85
150
 
86
151
  - **Start narrow.** One repository, one chat, one allowed login. Widen after the agent's work looks right.
@@ -92,7 +157,8 @@ agent writes would appear under that person's name.
92
157
  | Command | Does |
93
158
  | --- | --- |
94
159
  | `superagent init [dir]` | create `settings.yaml` and the state directory; a second run keeps both |
95
- | `superagent status [dir]` | print open and ended tickets as Markdown |
160
+ | `superagent setup [dir] [github\|feishu] [--allow a,b] [--chat id\|name]` | fill the GitHub and Feishu sections from the configured CLIs; a CLI that cannot answer changes nothing and exits 1 |
161
+ | `superagent status [dir]` | print open and ended tickets, and the recent judgements of unaddressed messages, as Markdown |
96
162
  | `superagent doctor [dir]` | show installed agents and the selected one |
97
163
  | `superagent agents` | list the agent names a configuration may use |
98
164
  | `superagent run [dir] -p <text>` | run one prompt on the configured agent and print its report |
@@ -105,6 +171,7 @@ The first argument is the installation directory and defaults to the current dir
105
171
  | Symptom | Cause and fix |
106
172
  | --- | --- |
107
173
  | `No configuration at …` | Run `superagent init` in the installation directory. |
174
+ | `Feishu: … cannot listen to oc_…` | The bot is not in that chat, or the chat listing failed; add the bot, or pass a chat it is in. |
108
175
  | `The configuration at … is invalid` | The message names the key; fix that key in `settings.yaml`. |
109
176
  | `Selected: **x** — not installed` | Install that CLI or choose another `executor.agent`. |
110
177
  | A ticket ends with a failed report | Read `state/tickets/<id>/log.md`; the agent's last message is at the end. |