superagent-skill 0.2.0 → 0.4.1

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
 
@@ -85,6 +99,11 @@ Arbitrary polling is not yet wired, so a person runs `poll` under cron or a syst
85
99
  compares this project with the earlier `dsh-superagent` DSH bundle: what both keep, what each does differently, and where
86
100
  this one is behind.
87
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
+
88
107
  ## Status
89
108
 
90
109
  Done and tested: the domain, file-backed state, the settings file, three agent runners (verified against the real CLIs),
@@ -119,3 +138,12 @@ is what a cron entry calls each minute.
119
138
  pnpm check # typecheck, unit tests, build
120
139
  SUPERAGENT_LIVE=1 SUPERAGENT_AGENT=codex pnpm test # also runs a real agent end to end
121
140
  ```
141
+
142
+ ## Lessons
143
+
144
+ [`LESSONS.md`](LESSONS.md) keeps what already cost a second pass here — a
145
+ setting shipped but read nowhere, a note written after the worker that needed
146
+ it started, a doc line that claimed a test nobody ran — as rules with the
147
+ commit or test that taught them. Read it before changing code; every task ends
148
+ by adding a lesson, raising one's `Seen` count, or saying why it taught
149
+ nothing.
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,6 +76,11 @@ 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
@@ -102,6 +107,45 @@ policy:
102
107
  `unasked` rule is required for an unaddressed message to start work. `superagent status` lists the recent
103
108
  judgements under "Unaddressed messages". Keep `observe` until the judgements read right.
104
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
+
105
149
  ## Rules to keep
106
150
 
107
151
  - **Start narrow.** One repository, one chat, one allowed login. Widen after the agent's work looks right.
@@ -113,6 +157,7 @@ judgements under "Unaddressed messages". Keep `observe` until the judgements rea
113
157
  | Command | Does |
114
158
  | --- | --- |
115
159
  | `superagent init [dir]` | create `settings.yaml` and the state directory; a second run keeps both |
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 |
116
161
  | `superagent status [dir]` | print open and ended tickets, and the recent judgements of unaddressed messages, as Markdown |
117
162
  | `superagent doctor [dir]` | show installed agents and the selected one |
118
163
  | `superagent agents` | list the agent names a configuration may use |
@@ -126,6 +171,7 @@ The first argument is the installation directory and defaults to the current dir
126
171
  | Symptom | Cause and fix |
127
172
  | --- | --- |
128
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. |
129
175
  | `The configuration at … is invalid` | The message names the key; fix that key in `settings.yaml`. |
130
176
  | `Selected: **x** — not installed` | Install that CLI or choose another `executor.agent`. |
131
177
  | A ticket ends with a failed report | Read `state/tickets/<id>/log.md`; the agent's last message is at the end. |