@pxlabz/tasq-cli 0.1.1 → 0.1.2
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/.tasq-skill.md +93 -0
- package/README.md +40 -4
- package/dist/tasq.js +205 -46
- package/examples/mention-runner.sh +87 -0
- package/package.json +4 -2
package/.tasq-skill.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tasq
|
|
3
|
+
description: Read and write Tasq tasks, comments and mentions from the shell with the `tasq` CLI. Use when you are working in a repository whose issues live in Tasq, when someone asks you to look at a task by its key (ENG-42), when you need to comment on or update a task, or when you are running as a Tasq agent and want to receive the mentions addressed to you. Covers authentication, the full command reference, the mention-reply-ack workflow, exit codes, and the agent isolation rule.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Tasq
|
|
7
|
+
|
|
8
|
+
Tasq is a task tracker whose write path is one action registry, reachable equally by a person in the web app and by an agent holding a key — the same permission checks and the same audit trail either way. The `tasq` CLI is that surface for a shell.
|
|
9
|
+
|
|
10
|
+
Tasq is not an agent runtime. It stores work, delivers mentions addressed to you, and records what you did. It never starts, supervises, or schedules you; that harness is the owner's.
|
|
11
|
+
|
|
12
|
+
## When to use it
|
|
13
|
+
|
|
14
|
+
- A task key like `ENG-42` appears in a request, a branch name, or a commit message.
|
|
15
|
+
- You have been asked to read, create, update, or comment on a task.
|
|
16
|
+
- You are running under a Tasq agent key and want the mentions queued for you.
|
|
17
|
+
|
|
18
|
+
Do not reach for it to store notes that belong in the repository, and do not create tasks nobody asked for.
|
|
19
|
+
|
|
20
|
+
## Authentication
|
|
21
|
+
|
|
22
|
+
The CLI reads its credentials from the environment. Nothing needs to be installed beyond the CLI itself.
|
|
23
|
+
|
|
24
|
+
| Variable | Meaning |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `TASQ_API_KEY` | Agent key (`tq_ag_…`). This is what you hold when you run as an agent. |
|
|
27
|
+
| `TASQ_WORKSPACE` | Default workspace slug, so commands need no `--workspace`. |
|
|
28
|
+
| `TASQ_API_URL` | API origin. Defaults to `https://tasq.pxlabz.com`. |
|
|
29
|
+
|
|
30
|
+
A human instead runs `tasq auth login` once, which stores a user token. If `TASQ_API_KEY` is set it wins over any stored token. Never print a key, and never write one into a file in the repository.
|
|
31
|
+
|
|
32
|
+
## Command reference
|
|
33
|
+
|
|
34
|
+
Global flags, valid on every command: `-w, --workspace <slug>`, `--api-url <url>`, `--json`. Task refs accept the human key (`ENG-42`) or the UUID.
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
tasq workspace list
|
|
38
|
+
tasq workspace use <slug>
|
|
39
|
+
|
|
40
|
+
tasq task list [--team <identifier>] [--status <name>] [--assignee <id>]
|
|
41
|
+
[--priority urgent|high|medium|low|none] [--project <id>]
|
|
42
|
+
[--cycle <id>] [-q, --q <text>] [--include-archived]
|
|
43
|
+
tasq task view <ref>
|
|
44
|
+
tasq task create <title> [--team <identifier>] [--description <markdown>]
|
|
45
|
+
[--priority <priority>] [--project <id>]
|
|
46
|
+
[--labels <a,b,c>]
|
|
47
|
+
tasq task update <ref> [--title <title>] [--description <markdown>]
|
|
48
|
+
[--priority <priority>] [--status <name>]
|
|
49
|
+
|
|
50
|
+
tasq comment add <ref> <body> [--reply-to <commentRef>] [--mention <agentName>]…
|
|
51
|
+
|
|
52
|
+
tasq events listen [--wait <seconds>] [--once]
|
|
53
|
+
tasq events ack <id>…
|
|
54
|
+
|
|
55
|
+
tasq project list
|
|
56
|
+
tasq cycle current [--team <identifier>]
|
|
57
|
+
|
|
58
|
+
tasq auth login [--email <email>]
|
|
59
|
+
tasq auth logout
|
|
60
|
+
tasq auth whoami
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`--mention` is repeatable and matches an agent name exactly, ignoring case. `--reply-to` takes a comment id or the `ENG-42#<id>` form that `task view` prints; the parent must be a comment on the same task.
|
|
64
|
+
|
|
65
|
+
## When you are mentioned
|
|
66
|
+
|
|
67
|
+
`tasq events listen` prints NDJSON — one compact JSON object per line, per event — whatever `--json` says, because it is meant to be read by a loop. Each object carries ids only: `{ id, kind, workspace, taskId, taskKey, commentId, mentionedBy, deliveryCount, createdAt }`. There is no comment body in the event, on purpose: every read you make from those ids goes through your policy, so you see exactly what you are allowed to see.
|
|
68
|
+
|
|
69
|
+
The loop is:
|
|
70
|
+
|
|
71
|
+
1. **Listen.** `tasq events listen --wait 20`. Each poll holds the connection open for up to 25 seconds and costs one read, so a listener is about three reads a minute.
|
|
72
|
+
2. **Read the task.** `tasq task view <taskKey> --json`. This is where the body of the mention, the rest of the thread, and the task's state come from.
|
|
73
|
+
3. **Gather context.** The same `task view` payload carries the comments and the activity log. Read before you write.
|
|
74
|
+
4. **Reply in the thread.** `tasq comment add <taskKey> "…" --reply-to <commentId>`, using the `commentId` from the event so your answer lands under the mention rather than at the bottom.
|
|
75
|
+
5. **Acknowledge.** `tasq events ack <eventId>`, and only after the work is done.
|
|
76
|
+
|
|
77
|
+
Ack last, deliberately. An unacknowledged event is offered again ten minutes after delivery, so a crash between step 2 and step 4 costs nothing; an event acked up front is gone. On a 429 the listener sleeps for `Retry-After` and carries on rather than exiting, so do not wrap it in a restart loop that would spend the same budget twice.
|
|
78
|
+
|
|
79
|
+
`examples/mention-runner.sh` in this package is a working reference for steps 1 and 5. It is an example, not a product.
|
|
80
|
+
|
|
81
|
+
## Exit codes
|
|
82
|
+
|
|
83
|
+
| Code | Meaning |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| 0 | Success |
|
|
86
|
+
| 1 | Error; details on stderr |
|
|
87
|
+
| 2 | Usage error — a bad flag, or a `--mention` name matching no agent or more than one |
|
|
88
|
+
| 3 | Rate limited; the message says when to retry. `events listen` never exits here — it waits and continues |
|
|
89
|
+
| 4 | Your policy denied the action. Do not retry it; say what was refused |
|
|
90
|
+
|
|
91
|
+
## Isolation
|
|
92
|
+
|
|
93
|
+
Agents do not deliver mentions to each other. If you `--mention` another agent, the mention is recorded as suppressed and never delivered — the CLI tells you so on the line it prints. Escalate to a person in the thread instead of trying to hand work to another agent.
|
package/README.md
CHANGED
|
@@ -27,7 +27,9 @@ TASQ_API_KEY=tq_ag_… TASQ_WORKSPACE=acme tasq task list
|
|
|
27
27
|
```
|
|
28
28
|
tasq workspace list | use <slug>
|
|
29
29
|
tasq task list | view <ref> | create | update <ref>
|
|
30
|
-
tasq comment add <ref>
|
|
30
|
+
tasq comment add <ref> <body> [--reply-to <commentRef>] [--mention <agentName>]…
|
|
31
|
+
tasq events listen [--wait <seconds>] [--once]
|
|
32
|
+
tasq events ack <id>…
|
|
31
33
|
tasq project list
|
|
32
34
|
tasq cycle current
|
|
33
35
|
tasq auth login | logout
|
|
@@ -35,6 +37,40 @@ tasq auth login | logout
|
|
|
35
37
|
|
|
36
38
|
Every command takes `--json` for raw output and `-w, --workspace <slug>` to override the default. Task refs accept either the human key (`ENG-42`) or the UUID.
|
|
37
39
|
|
|
40
|
+
### Mentions and replies
|
|
41
|
+
|
|
42
|
+
`--mention <agentName>` is repeatable and matches an agent's name exactly, ignoring case. Two agents answering to one name is a usage error (exit 2) rather than a guess. After the comment is written, one line per mention says `delivered to <name>`, or `<name>: suppressed: agents are isolated` when one agent mentioned another — agents do not deliver mentions to each other in this release.
|
|
43
|
+
|
|
44
|
+
`--reply-to` takes a comment id, or the `ENG-42#<id>` form `task view` prints. The parent must be a comment on the same task.
|
|
45
|
+
|
|
46
|
+
### Listening for mentions
|
|
47
|
+
|
|
48
|
+
`tasq events listen` streams NDJSON — one compact JSON object per line, per event — whatever `--json` says, because the output is meant for a runner loop rather than a reader:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
TASQ_API_KEY=tq_ag_… TASQ_WORKSPACE=acme tasq events listen --wait 20 |
|
|
52
|
+
while read -r event; do handle "$event"; done
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Each poll holds the connection open for up to `--wait` seconds (0-25; the server clamps) and is charged once against the read budget, so `--wait 20` costs at most three reads a minute of the 120 available. An empty response means the window expired with nothing waiting, and the listener reconnects at once. On a 429 it sleeps for `Retry-After` and carries on rather than exiting, so a supervised runner cannot turn a rate limit into a restart loop that burns the same budget. Ctrl-C aborts the in-flight poll and exits 0.
|
|
56
|
+
|
|
57
|
+
Events stay deliverable until acknowledged: `tasq events ack <id>…` marks them, and an unacked event is offered again ten minutes after it was delivered. A runner that crashes mid-work therefore sees the event once more rather than losing it.
|
|
58
|
+
|
|
59
|
+
## For agents
|
|
60
|
+
|
|
61
|
+
Two files ship with the package for the agent side of this.
|
|
62
|
+
|
|
63
|
+
- **`.tasq-skill.md`** — a skill file written for a coding agent: what Tasq is, when to reach for it, the full command reference, the mention → read → reply → ack workflow, the exit codes, and the isolation rule. Point your harness at it, or read it yourself.
|
|
64
|
+
- **`examples/mention-runner.sh`** — a reference loop over `tasq events listen`. It exports `TASQ_EVENT_ID`, `TASQ_EVENT_KIND`, `TASQ_EVENT_TASK_KEY`, `TASQ_EVENT_TASK_ID`, `TASQ_EVENT_COMMENT_ID` and `TASQ_EVENT_MENTIONED_BY`, runs `$TASQ_AGENT_CMD` once per event, and acks only when that command exits 0 so a failure is redelivered rather than lost.
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
TASQ_API_KEY=tq_ag_… TASQ_WORKSPACE=acme \
|
|
68
|
+
TASQ_AGENT_CMD='claude -p "handle $TASQ_EVENT_TASK_KEY"' \
|
|
69
|
+
./node_modules/@pxlabz/tasq-cli/examples/mention-runner.sh --wait 20
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Both are examples. Tasq stores and delivers the event; it never runs your agent.
|
|
73
|
+
|
|
38
74
|
## Configuration
|
|
39
75
|
|
|
40
76
|
| Source | Purpose |
|
|
@@ -51,8 +87,8 @@ Every command takes `--json` for raw output and `-w, --workspace <slug>` to over
|
|
|
51
87
|
| --- | --- |
|
|
52
88
|
| 0 | Success |
|
|
53
89
|
| 1 | Error (details on stderr) |
|
|
54
|
-
| 2 | Usage error |
|
|
55
|
-
| 3 | Rate limited; the message includes when to retry |
|
|
90
|
+
| 2 | Usage error — including an `--mention` name that matches no agent or more than one |
|
|
91
|
+
| 3 | Rate limited; the message includes when to retry. `events listen` does not exit here: it sleeps for `Retry-After` and carries on |
|
|
56
92
|
| 4 | The agent's policy denied the action |
|
|
57
93
|
|
|
58
|
-
Built as a single file on top of [`@pxlabz/tasq-sdk`](https://www.npmjs.com/package/@pxlabz/tasq-sdk). Node 20 or newer.
|
|
94
|
+
Built as a single file on top of [`@pxlabz/tasq-sdk`](https://www.npmjs.com/package/@pxlabz/tasq-sdk). Node 20.3 or newer (for `AbortSignal.any`).
|
package/dist/tasq.js
CHANGED
|
@@ -774,8 +774,8 @@ ${itemIndentStr}`);
|
|
|
774
774
|
const rawLines = str.split(/\r\n|\n/);
|
|
775
775
|
const chunkPattern = /[\s]*[^\s]+/g;
|
|
776
776
|
const wrappedLines = [];
|
|
777
|
-
rawLines.forEach((
|
|
778
|
-
const chunks =
|
|
777
|
+
rawLines.forEach((line2) => {
|
|
778
|
+
const chunks = line2.match(chunkPattern);
|
|
779
779
|
if (chunks === null) {
|
|
780
780
|
wrappedLines.push("");
|
|
781
781
|
return;
|
|
@@ -3682,13 +3682,13 @@ var require_utils = __commonJS({
|
|
|
3682
3682
|
state[info.set] = info.to;
|
|
3683
3683
|
}
|
|
3684
3684
|
}
|
|
3685
|
-
function readState(
|
|
3685
|
+
function readState(line2) {
|
|
3686
3686
|
let code = codeRegex(true);
|
|
3687
|
-
let controlChars = code.exec(
|
|
3687
|
+
let controlChars = code.exec(line2);
|
|
3688
3688
|
let state = {};
|
|
3689
3689
|
while (controlChars !== null) {
|
|
3690
3690
|
updateState(state, controlChars);
|
|
3691
|
-
controlChars = code.exec(
|
|
3691
|
+
controlChars = code.exec(line2);
|
|
3692
3692
|
}
|
|
3693
3693
|
return state;
|
|
3694
3694
|
}
|
|
@@ -3824,7 +3824,7 @@ var require_utils = __commonJS({
|
|
|
3824
3824
|
function wordWrap(maxLength, input) {
|
|
3825
3825
|
let lines = [];
|
|
3826
3826
|
let split = input.split(/(\s+)/g);
|
|
3827
|
-
let
|
|
3827
|
+
let line2 = [];
|
|
3828
3828
|
let lineLength = 0;
|
|
3829
3829
|
let whitespace;
|
|
3830
3830
|
for (let i = 0; i < split.length; i += 2) {
|
|
@@ -3835,37 +3835,37 @@ var require_utils = __commonJS({
|
|
|
3835
3835
|
}
|
|
3836
3836
|
if (newLength > maxLength) {
|
|
3837
3837
|
if (lineLength !== 0) {
|
|
3838
|
-
lines.push(
|
|
3838
|
+
lines.push(line2.join(""));
|
|
3839
3839
|
}
|
|
3840
|
-
|
|
3840
|
+
line2 = [word];
|
|
3841
3841
|
lineLength = strlen(word);
|
|
3842
3842
|
} else {
|
|
3843
|
-
|
|
3843
|
+
line2.push(whitespace || "", word);
|
|
3844
3844
|
lineLength = newLength;
|
|
3845
3845
|
}
|
|
3846
3846
|
whitespace = split[i + 1];
|
|
3847
3847
|
}
|
|
3848
3848
|
if (lineLength) {
|
|
3849
|
-
lines.push(
|
|
3849
|
+
lines.push(line2.join(""));
|
|
3850
3850
|
}
|
|
3851
3851
|
return lines;
|
|
3852
3852
|
}
|
|
3853
3853
|
function textWrap(maxLength, input) {
|
|
3854
3854
|
let lines = [];
|
|
3855
|
-
let
|
|
3855
|
+
let line2 = "";
|
|
3856
3856
|
function pushLine(str, ws) {
|
|
3857
|
-
if (
|
|
3858
|
-
|
|
3859
|
-
while (
|
|
3860
|
-
lines.push(
|
|
3861
|
-
|
|
3857
|
+
if (line2.length && ws) line2 += ws;
|
|
3858
|
+
line2 += str;
|
|
3859
|
+
while (line2.length > maxLength) {
|
|
3860
|
+
lines.push(line2.slice(0, maxLength));
|
|
3861
|
+
line2 = line2.slice(maxLength);
|
|
3862
3862
|
}
|
|
3863
3863
|
}
|
|
3864
3864
|
let split = input.split(/(\s+)/g);
|
|
3865
3865
|
for (let i = 0; i < split.length; i += 2) {
|
|
3866
3866
|
pushLine(split[i], i && split[i - 1]);
|
|
3867
3867
|
}
|
|
3868
|
-
if (
|
|
3868
|
+
if (line2.length) lines.push(line2);
|
|
3869
3869
|
return lines;
|
|
3870
3870
|
}
|
|
3871
3871
|
function multiLineWordWrap(maxLength, input, wrapOnWordBoundary = true) {
|
|
@@ -3881,10 +3881,10 @@ var require_utils = __commonJS({
|
|
|
3881
3881
|
let state = {};
|
|
3882
3882
|
let output = [];
|
|
3883
3883
|
for (let i = 0; i < input.length; i++) {
|
|
3884
|
-
let
|
|
3885
|
-
state = readState(
|
|
3884
|
+
let line2 = rewindState(state, input[i]);
|
|
3885
|
+
state = readState(line2);
|
|
3886
3886
|
let temp = Object.assign({}, state);
|
|
3887
|
-
output.push(unwindState(temp,
|
|
3887
|
+
output.push(unwindState(temp, line2));
|
|
3888
3888
|
}
|
|
3889
3889
|
return output;
|
|
3890
3890
|
}
|
|
@@ -4661,7 +4661,7 @@ var require_cell = __commonJS({
|
|
|
4661
4661
|
wrapLines(computedLines) {
|
|
4662
4662
|
const lines = utils.colorizeLines(computedLines);
|
|
4663
4663
|
if (this.href) {
|
|
4664
|
-
return lines.map((
|
|
4664
|
+
return lines.map((line2) => utils.hyperlink(this.href, line2));
|
|
4665
4665
|
}
|
|
4666
4666
|
return lines;
|
|
4667
4667
|
}
|
|
@@ -4809,10 +4809,10 @@ var require_cell = __commonJS({
|
|
|
4809
4809
|
let leftPadding = utils.repeat(" ", this.paddingLeft);
|
|
4810
4810
|
let right = drawRight ? this.chars["right"] : "";
|
|
4811
4811
|
let rightPadding = utils.repeat(" ", this.paddingRight);
|
|
4812
|
-
let
|
|
4812
|
+
let line2 = this.lines[lineNum];
|
|
4813
4813
|
let len = this.width - (this.paddingLeft + this.paddingRight);
|
|
4814
|
-
if (forceTruncationSymbol)
|
|
4815
|
-
let content = utils.truncate(
|
|
4814
|
+
if (forceTruncationSymbol) line2 += this.truncate || "\u2026";
|
|
4815
|
+
let content = utils.truncate(line2, len, this.truncate);
|
|
4816
4816
|
content = utils.pad(content, len, " ", this.hAlign);
|
|
4817
4817
|
content = leftPadding + content + rightPadding;
|
|
4818
4818
|
return this.stylizeLine(left, content, right);
|
|
@@ -5274,11 +5274,11 @@ var require_table = __commonJS({
|
|
|
5274
5274
|
};
|
|
5275
5275
|
Table2.reset = () => debug.reset();
|
|
5276
5276
|
function doDraw(row, lineNum, result) {
|
|
5277
|
-
let
|
|
5277
|
+
let line2 = [];
|
|
5278
5278
|
row.forEach(function(cell) {
|
|
5279
|
-
|
|
5279
|
+
line2.push(cell.draw(lineNum));
|
|
5280
5280
|
});
|
|
5281
|
-
let str =
|
|
5281
|
+
let str = line2.join("");
|
|
5282
5282
|
if (str.length) result.push(str);
|
|
5283
5283
|
}
|
|
5284
5284
|
module.exports = Table2;
|
|
@@ -6412,7 +6412,7 @@ var {
|
|
|
6412
6412
|
// package.json
|
|
6413
6413
|
var package_default = {
|
|
6414
6414
|
name: "@pxlabz/tasq-cli",
|
|
6415
|
-
version: "0.1.
|
|
6415
|
+
version: "0.1.2",
|
|
6416
6416
|
description: "Command-line client for Tasq, for humans and agents alike",
|
|
6417
6417
|
keywords: [
|
|
6418
6418
|
"tasq",
|
|
@@ -6438,6 +6438,8 @@ var package_default = {
|
|
|
6438
6438
|
},
|
|
6439
6439
|
files: [
|
|
6440
6440
|
"dist",
|
|
6441
|
+
"examples",
|
|
6442
|
+
".tasq-skill.md",
|
|
6441
6443
|
"README.md",
|
|
6442
6444
|
"LICENSE"
|
|
6443
6445
|
],
|
|
@@ -6445,7 +6447,7 @@ var package_default = {
|
|
|
6445
6447
|
access: "public"
|
|
6446
6448
|
},
|
|
6447
6449
|
engines: {
|
|
6448
|
-
node: ">=20"
|
|
6450
|
+
node: ">=20.3"
|
|
6449
6451
|
},
|
|
6450
6452
|
scripts: {
|
|
6451
6453
|
build: "tsup && chmod +x dist/tasq.js",
|
|
@@ -6670,7 +6672,7 @@ var TasqClient = class _TasqClient {
|
|
|
6670
6672
|
this.#fetch = options.fetch ?? globalThis.fetch;
|
|
6671
6673
|
}
|
|
6672
6674
|
async #request(path, init = {}) {
|
|
6673
|
-
const { anonymous = false, ...requestInit } = init;
|
|
6675
|
+
const { anonymous = false, timeoutMs, ...requestInit } = init;
|
|
6674
6676
|
const headers = new Headers(requestInit.headers);
|
|
6675
6677
|
if (!anonymous) {
|
|
6676
6678
|
if (this.#token === void 0) throw noCredentialError();
|
|
@@ -6680,9 +6682,15 @@ var TasqClient = class _TasqClient {
|
|
|
6680
6682
|
headers.set("content-type", "application/json");
|
|
6681
6683
|
}
|
|
6682
6684
|
headers.set("accept", "application/json");
|
|
6685
|
+
const timeout = timeoutMs === void 0 ? void 0 : AbortSignal.timeout(timeoutMs);
|
|
6686
|
+
const signals = [requestInit.signal, timeout].filter(
|
|
6687
|
+
(candidate) => candidate != null
|
|
6688
|
+
);
|
|
6689
|
+
const signal = signals.length === 0 ? void 0 : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
|
|
6683
6690
|
const response = await this.#fetch(`${this.#baseUrl}${path}`, {
|
|
6684
6691
|
...requestInit,
|
|
6685
|
-
headers
|
|
6692
|
+
headers,
|
|
6693
|
+
signal
|
|
6686
6694
|
});
|
|
6687
6695
|
if (!response.ok) {
|
|
6688
6696
|
throw await this.#toError(response);
|
|
@@ -6704,8 +6712,8 @@ var TasqClient = class _TasqClient {
|
|
|
6704
6712
|
};
|
|
6705
6713
|
return toTasqError(response.status, body, retryAfter);
|
|
6706
6714
|
}
|
|
6707
|
-
#get(path, params) {
|
|
6708
|
-
return this.#request(`${path}${queryString(params)}
|
|
6715
|
+
#get(path, params, options) {
|
|
6716
|
+
return this.#request(`${path}${queryString(params)}`, options);
|
|
6709
6717
|
}
|
|
6710
6718
|
workspaces = {
|
|
6711
6719
|
list: async () => (await this.#get("/workspaces")).workspaces,
|
|
@@ -6753,6 +6761,33 @@ var TasqClient = class _TasqClient {
|
|
|
6753
6761
|
agents = {
|
|
6754
6762
|
policy: (slug, agentId) => this.#get(
|
|
6755
6763
|
`/workspaces/${encodeURIComponent(slug)}/agents/${encodeURIComponent(agentId)}/policy`
|
|
6764
|
+
),
|
|
6765
|
+
/**
|
|
6766
|
+
* Long-poll for mentions addressed to the agent behind this key.
|
|
6767
|
+
*
|
|
6768
|
+
* The same call acks: ids passed as `ack` are marked before the select
|
|
6769
|
+
* runs, so a runner's next poll is also its acknowledgement of the last
|
|
6770
|
+
* batch (D-5). Agent keys only.
|
|
6771
|
+
*/
|
|
6772
|
+
events: (slug, query = {}, options) => this.#get(
|
|
6773
|
+
`/workspaces/${encodeURIComponent(slug)}/agents/me/events`,
|
|
6774
|
+
{
|
|
6775
|
+
wait: query.wait,
|
|
6776
|
+
limit: query.limit,
|
|
6777
|
+
ack: query.ack === void 0 || query.ack.length === 0 ? void 0 : query.ack.join(",")
|
|
6778
|
+
},
|
|
6779
|
+
options
|
|
6780
|
+
)
|
|
6781
|
+
};
|
|
6782
|
+
members = {
|
|
6783
|
+
list: async (slug) => (await this.#get(
|
|
6784
|
+
`/workspaces/${encodeURIComponent(slug)}/members`
|
|
6785
|
+
)).members
|
|
6786
|
+
};
|
|
6787
|
+
notifications = {
|
|
6788
|
+
list: (slug, query = {}) => this.#get(
|
|
6789
|
+
`/workspaces/${encodeURIComponent(slug)}/notifications`,
|
|
6790
|
+
{ unread: query.unread === true ? 1 : void 0 }
|
|
6756
6791
|
)
|
|
6757
6792
|
};
|
|
6758
6793
|
auth = {
|
|
@@ -6924,6 +6959,9 @@ function formatWorkspaces(workspaces) {
|
|
|
6924
6959
|
])
|
|
6925
6960
|
);
|
|
6926
6961
|
}
|
|
6962
|
+
function line(io2, value) {
|
|
6963
|
+
io2.out(JSON.stringify(value));
|
|
6964
|
+
}
|
|
6927
6965
|
|
|
6928
6966
|
// src/commands/auth.ts
|
|
6929
6967
|
var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
|
|
@@ -7027,17 +7065,70 @@ async function resolveTaskId(client, slug, ref) {
|
|
|
7027
7065
|
}
|
|
7028
7066
|
|
|
7029
7067
|
// src/commands/comment.ts
|
|
7030
|
-
|
|
7068
|
+
function commentIdOf(ref) {
|
|
7069
|
+
const hash = ref.lastIndexOf("#");
|
|
7070
|
+
return hash === -1 ? ref.trim() : ref.slice(hash + 1).trim();
|
|
7071
|
+
}
|
|
7072
|
+
function resolveParentId(task, ref) {
|
|
7073
|
+
const id = commentIdOf(ref);
|
|
7074
|
+
const found = task.comments.find((comment) => comment.id === id);
|
|
7075
|
+
if (found === void 0) {
|
|
7076
|
+
throw new UsageError(
|
|
7077
|
+
`"${ref}" is not a comment on ${task.identifier}. Replies must stay in the same task.`
|
|
7078
|
+
);
|
|
7079
|
+
}
|
|
7080
|
+
return found.id;
|
|
7081
|
+
}
|
|
7082
|
+
function resolveMentions(members, names) {
|
|
7083
|
+
const agents = members.filter(
|
|
7084
|
+
(member) => member.type === "agent" && member.agentId !== null
|
|
7085
|
+
);
|
|
7086
|
+
return names.map((name) => {
|
|
7087
|
+
const wanted = name.trim().toLowerCase();
|
|
7088
|
+
const matched = agents.filter(
|
|
7089
|
+
(agent) => (agent.name ?? "").toLowerCase() === wanted
|
|
7090
|
+
);
|
|
7091
|
+
if (matched.length === 0) {
|
|
7092
|
+
throw new UsageError(
|
|
7093
|
+
`No agent named "${name}" in this workspace. Run "tasq workspace members" to see the names.`
|
|
7094
|
+
);
|
|
7095
|
+
}
|
|
7096
|
+
if (matched.length > 1) {
|
|
7097
|
+
throw new UsageError(
|
|
7098
|
+
`"${name}" matches ${matched.length} agents. Rename one, or pass the agent id.`
|
|
7099
|
+
);
|
|
7100
|
+
}
|
|
7101
|
+
return matched[0]?.agentId ?? "";
|
|
7102
|
+
});
|
|
7103
|
+
}
|
|
7104
|
+
function mentionLine(state, name) {
|
|
7105
|
+
const who = name ?? "an agent";
|
|
7106
|
+
return state === "suppressed" ? `${who}: suppressed: agents are isolated` : `delivered to ${who}`;
|
|
7107
|
+
}
|
|
7108
|
+
async function commentAdd(ctx, taskRef, body, options = {}) {
|
|
7031
7109
|
const slug = requireWorkspace(ctx.config);
|
|
7032
7110
|
const taskId = await resolveTaskId(ctx.client, slug, taskRef);
|
|
7033
7111
|
const task = await ctx.client.tasks.get(slug, taskId);
|
|
7034
|
-
const
|
|
7035
|
-
|
|
7036
|
-
|
|
7037
|
-
}
|
|
7038
|
-
|
|
7039
|
-
|
|
7112
|
+
const names = options.mention ?? [];
|
|
7113
|
+
const members = names.length === 0 ? [] : await ctx.client.members.list(slug);
|
|
7114
|
+
const mentions = resolveMentions(members, names);
|
|
7115
|
+
const input = { taskId: task.id, body };
|
|
7116
|
+
if (options.replyTo !== void 0) {
|
|
7117
|
+
input.parentId = resolveParentId(task, options.replyTo);
|
|
7118
|
+
}
|
|
7119
|
+
if (mentions.length > 0) input.mentions = mentions;
|
|
7120
|
+
const added = await ctx.client.dispatch("comment.add", slug, input);
|
|
7121
|
+
if (ctx.config.json) {
|
|
7122
|
+
ctx.io.out(jsonOutput(added.result));
|
|
7123
|
+
return;
|
|
7124
|
+
}
|
|
7125
|
+
ctx.io.out(`Comment added to ${task.identifier}.`);
|
|
7126
|
+
const nameById = new Map(
|
|
7127
|
+
members.map((member) => [member.agentId, member.name])
|
|
7040
7128
|
);
|
|
7129
|
+
for (const mention of added.result.mentions ?? []) {
|
|
7130
|
+
ctx.io.out(mentionLine(mention.state, nameById.get(mention.agentId)));
|
|
7131
|
+
}
|
|
7041
7132
|
}
|
|
7042
7133
|
|
|
7043
7134
|
// src/commands/cycle.ts
|
|
@@ -7070,6 +7161,47 @@ async function cycleCurrent(ctx, options) {
|
|
|
7070
7161
|
}
|
|
7071
7162
|
}
|
|
7072
7163
|
|
|
7164
|
+
// src/commands/events.ts
|
|
7165
|
+
function defaultSleep(ms) {
|
|
7166
|
+
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
7167
|
+
}
|
|
7168
|
+
function isAbort(error, signal) {
|
|
7169
|
+
if (signal?.aborted === true) return true;
|
|
7170
|
+
return error.name === "AbortError";
|
|
7171
|
+
}
|
|
7172
|
+
async function eventsListen(ctx, options = {}, deps = {}) {
|
|
7173
|
+
const slug = requireWorkspace(ctx.config);
|
|
7174
|
+
const sleep = deps.sleep ?? defaultSleep;
|
|
7175
|
+
const wait = options.wait ?? 20;
|
|
7176
|
+
for (; ; ) {
|
|
7177
|
+
if (deps.signal?.aborted === true) return;
|
|
7178
|
+
let page;
|
|
7179
|
+
try {
|
|
7180
|
+
page = await ctx.client.agents.events(
|
|
7181
|
+
slug,
|
|
7182
|
+
{ wait },
|
|
7183
|
+
{ signal: deps.signal }
|
|
7184
|
+
);
|
|
7185
|
+
} catch (thrown) {
|
|
7186
|
+
if (!(thrown instanceof Error)) throw thrown;
|
|
7187
|
+
const error = thrown;
|
|
7188
|
+
if (isAbort(error, deps.signal)) return;
|
|
7189
|
+
if (error instanceof TasqRateLimitError) {
|
|
7190
|
+
await sleep(error.retryAfterSeconds * 1e3);
|
|
7191
|
+
continue;
|
|
7192
|
+
}
|
|
7193
|
+
throw error;
|
|
7194
|
+
}
|
|
7195
|
+
for (const event of page.events) line(ctx.io, event);
|
|
7196
|
+
if (options.once === true) return;
|
|
7197
|
+
}
|
|
7198
|
+
}
|
|
7199
|
+
async function eventsAck(ctx, ids) {
|
|
7200
|
+
const slug = requireWorkspace(ctx.config);
|
|
7201
|
+
const page = await ctx.client.agents.events(slug, { wait: 0, ack: ids });
|
|
7202
|
+
line(ctx.io, { acked: page.acked });
|
|
7203
|
+
}
|
|
7204
|
+
|
|
7073
7205
|
// src/commands/project.ts
|
|
7074
7206
|
async function projectList(ctx) {
|
|
7075
7207
|
const slug = requireWorkspace(ctx.config);
|
|
@@ -7352,8 +7484,35 @@ function buildProgram(io2) {
|
|
|
7352
7484
|
});
|
|
7353
7485
|
});
|
|
7354
7486
|
const comment = program2.command("comment").description("Task comments");
|
|
7355
|
-
comment.command("add").argument("<taskId>", "task identifier or id").argument("<body>", "comment body").description("Add a comment to a task").
|
|
7356
|
-
|
|
7487
|
+
comment.command("add").argument("<taskId>", "task identifier or id").argument("<body>", "comment body").description("Add a comment to a task").option("--reply-to <commentRef>", "comment id, or ENG-42#<id>, to reply to").option(
|
|
7488
|
+
"--mention <agentName>",
|
|
7489
|
+
"agent to mention, repeatable",
|
|
7490
|
+
(value, previous) => [
|
|
7491
|
+
...previous ?? [],
|
|
7492
|
+
value
|
|
7493
|
+
]
|
|
7494
|
+
).action(
|
|
7495
|
+
async (taskId, body, options) => {
|
|
7496
|
+
await commentAdd(contextFor(program2, io2), taskId, body, options);
|
|
7497
|
+
}
|
|
7498
|
+
);
|
|
7499
|
+
const events = program2.command("events").description("Mentions addressed to this agent");
|
|
7500
|
+
events.command("listen").description("Stream mentions as NDJSON, one JSON object per line").option("--wait <seconds>", "seconds to hold each poll open, 0-25", "20").option("--once", "return after the first response").action(async (options) => {
|
|
7501
|
+
const controller = new AbortController();
|
|
7502
|
+
const stop = () => controller.abort();
|
|
7503
|
+
process.once("SIGINT", stop);
|
|
7504
|
+
try {
|
|
7505
|
+
await eventsListen(
|
|
7506
|
+
contextFor(program2, io2),
|
|
7507
|
+
{ wait: Number(options.wait), once: options.once },
|
|
7508
|
+
{ signal: controller.signal }
|
|
7509
|
+
);
|
|
7510
|
+
} finally {
|
|
7511
|
+
process.removeListener("SIGINT", stop);
|
|
7512
|
+
}
|
|
7513
|
+
});
|
|
7514
|
+
events.command("ack").argument("<id...>", "event ids to acknowledge").description("Acknowledge delivered events").action(async (ids) => {
|
|
7515
|
+
await eventsAck(contextFor(program2, io2), ids);
|
|
7357
7516
|
});
|
|
7358
7517
|
const project = program2.command("project").description("Projects");
|
|
7359
7518
|
project.command("list").description("List projects").action(run((ctx) => projectList(ctx)));
|
|
@@ -7390,12 +7549,12 @@ async function main(argv, io2) {
|
|
|
7390
7549
|
}
|
|
7391
7550
|
}
|
|
7392
7551
|
var io = {
|
|
7393
|
-
out: (
|
|
7394
|
-
process.stdout.write(`${
|
|
7552
|
+
out: (line2) => {
|
|
7553
|
+
process.stdout.write(`${line2}
|
|
7395
7554
|
`);
|
|
7396
7555
|
},
|
|
7397
|
-
err: (
|
|
7398
|
-
process.stderr.write(`${
|
|
7556
|
+
err: (line2) => {
|
|
7557
|
+
process.stderr.write(`${line2}
|
|
7399
7558
|
`);
|
|
7400
7559
|
}
|
|
7401
7560
|
};
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Example mention runner — NOT part of the Tasq product.
|
|
3
|
+
#
|
|
4
|
+
# Tasq stores and delivers mentions; it never runs your agent. This script is
|
|
5
|
+
# the smallest honest example of the harness side, which is yours to own: it
|
|
6
|
+
# reads `tasq events listen` line by line, hands each event to a command of
|
|
7
|
+
# your choosing through the environment, and acknowledges the event only when
|
|
8
|
+
# that command succeeds. Copy it, rewrite it, or ignore it.
|
|
9
|
+
#
|
|
10
|
+
# Usage:
|
|
11
|
+
# TASQ_API_KEY=tq_ag_… \
|
|
12
|
+
# TASQ_WORKSPACE=acme \
|
|
13
|
+
# TASQ_AGENT_CMD='claude -p "handle $TASQ_EVENT_TASK_KEY"' \
|
|
14
|
+
# ./mention-runner.sh [--wait 20]
|
|
15
|
+
#
|
|
16
|
+
# Environment:
|
|
17
|
+
# TASQ_AGENT_CMD Required. Shell command run once per event, with the
|
|
18
|
+
# TASQ_EVENT_* variables below exported into it.
|
|
19
|
+
# TASQ_API_KEY The agent key. TASQ_WORKSPACE and TASQ_API_URL are read by
|
|
20
|
+
# the CLI itself; see `tasq --help`.
|
|
21
|
+
#
|
|
22
|
+
# Exported per event:
|
|
23
|
+
# TASQ_EVENT_ID, TASQ_EVENT_KIND, TASQ_EVENT_TASK_KEY, TASQ_EVENT_TASK_ID,
|
|
24
|
+
# TASQ_EVENT_COMMENT_ID, TASQ_EVENT_MENTIONED_BY
|
|
25
|
+
#
|
|
26
|
+
# Acking is deliberate: an event the command failed on is left unacked, and
|
|
27
|
+
# Tasq offers it again ten minutes later. A crash loses no work.
|
|
28
|
+
|
|
29
|
+
set -euo pipefail
|
|
30
|
+
|
|
31
|
+
: "${TASQ_AGENT_CMD:?Set TASQ_AGENT_CMD to the command that handles one event}"
|
|
32
|
+
|
|
33
|
+
TASQ_BIN="${TASQ_BIN:-tasq}"
|
|
34
|
+
|
|
35
|
+
# jq if it is there, a node one-liner if it is not. Both print the field's
|
|
36
|
+
# value, or an empty line when the field is null or missing.
|
|
37
|
+
if command -v jq > /dev/null 2>&1; then
|
|
38
|
+
field() { printf '%s' "$1" | jq -r --arg f "$2" '.[$f] // empty'; }
|
|
39
|
+
else
|
|
40
|
+
field() {
|
|
41
|
+
printf '%s' "$1" | node -e '
|
|
42
|
+
let raw = ""
|
|
43
|
+
process.stdin.on("data", (chunk) => { raw += chunk })
|
|
44
|
+
process.stdin.on("end", () => {
|
|
45
|
+
const value = JSON.parse(raw)[process.argv[1]]
|
|
46
|
+
process.stdout.write(value == null ? "" : String(value))
|
|
47
|
+
})
|
|
48
|
+
' "$2"
|
|
49
|
+
}
|
|
50
|
+
fi
|
|
51
|
+
|
|
52
|
+
"$TASQ_BIN" events listen "$@" | while IFS= read -r event; do
|
|
53
|
+
[[ -z "$event" ]] && continue
|
|
54
|
+
|
|
55
|
+
TASQ_EVENT_ID="$(field "$event" id)"
|
|
56
|
+
TASQ_EVENT_KIND="$(field "$event" kind)"
|
|
57
|
+
TASQ_EVENT_TASK_KEY="$(field "$event" taskKey)"
|
|
58
|
+
TASQ_EVENT_TASK_ID="$(field "$event" taskId)"
|
|
59
|
+
TASQ_EVENT_COMMENT_ID="$(field "$event" commentId)"
|
|
60
|
+
TASQ_EVENT_MENTIONED_BY="$(printf '%s' "$event" | {
|
|
61
|
+
if command -v jq > /dev/null 2>&1; then
|
|
62
|
+
jq -r '.mentionedBy.name // empty'
|
|
63
|
+
else
|
|
64
|
+
node -e '
|
|
65
|
+
let raw = ""
|
|
66
|
+
process.stdin.on("data", (chunk) => { raw += chunk })
|
|
67
|
+
process.stdin.on("end", () => {
|
|
68
|
+
const by = JSON.parse(raw).mentionedBy
|
|
69
|
+
process.stdout.write(by?.name == null ? "" : String(by.name))
|
|
70
|
+
})
|
|
71
|
+
'
|
|
72
|
+
fi
|
|
73
|
+
})"
|
|
74
|
+
|
|
75
|
+
export TASQ_EVENT_ID TASQ_EVENT_KIND TASQ_EVENT_TASK_KEY \
|
|
76
|
+
TASQ_EVENT_TASK_ID TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY
|
|
77
|
+
|
|
78
|
+
echo "→ ${TASQ_EVENT_KIND} on ${TASQ_EVENT_TASK_KEY:-?} (${TASQ_EVENT_ID})" >&2
|
|
79
|
+
|
|
80
|
+
# `set -e` must not kill the loop on a handler failure: the whole point is
|
|
81
|
+
# to leave that event unacked and keep listening.
|
|
82
|
+
if sh -c "$TASQ_AGENT_CMD"; then
|
|
83
|
+
"$TASQ_BIN" events ack "$TASQ_EVENT_ID"
|
|
84
|
+
else
|
|
85
|
+
echo " handler failed; leaving ${TASQ_EVENT_ID} unacked for redelivery" >&2
|
|
86
|
+
fi
|
|
87
|
+
done
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pxlabz/tasq-cli",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Command-line client for Tasq, for humans and agents alike",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"tasq",
|
|
@@ -26,6 +26,8 @@
|
|
|
26
26
|
},
|
|
27
27
|
"files": [
|
|
28
28
|
"dist",
|
|
29
|
+
"examples",
|
|
30
|
+
".tasq-skill.md",
|
|
29
31
|
"README.md",
|
|
30
32
|
"LICENSE"
|
|
31
33
|
],
|
|
@@ -33,7 +35,7 @@
|
|
|
33
35
|
"access": "public"
|
|
34
36
|
},
|
|
35
37
|
"engines": {
|
|
36
|
-
"node": ">=20"
|
|
38
|
+
"node": ">=20.3"
|
|
37
39
|
},
|
|
38
40
|
"scripts": {
|
|
39
41
|
"build": "tsup && chmod +x dist/tasq.js",
|