@pxlabz/tasq-cli 0.1.0 → 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 +261 -45
- package/examples/mention-runner.sh +87 -0
- package/package.json +5 -3
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;
|
|
@@ -6409,6 +6409,65 @@ var {
|
|
|
6409
6409
|
Help
|
|
6410
6410
|
} = import_index.default;
|
|
6411
6411
|
|
|
6412
|
+
// package.json
|
|
6413
|
+
var package_default = {
|
|
6414
|
+
name: "@pxlabz/tasq-cli",
|
|
6415
|
+
version: "0.1.2",
|
|
6416
|
+
description: "Command-line client for Tasq, for humans and agents alike",
|
|
6417
|
+
keywords: [
|
|
6418
|
+
"tasq",
|
|
6419
|
+
"cli",
|
|
6420
|
+
"agents",
|
|
6421
|
+
"project-management"
|
|
6422
|
+
],
|
|
6423
|
+
license: "MIT",
|
|
6424
|
+
author: "Paul Cedrick Artigo",
|
|
6425
|
+
homepage: "https://github.com/pxlabz/tasq/tree/main/packages/cli#readme",
|
|
6426
|
+
repository: {
|
|
6427
|
+
type: "git",
|
|
6428
|
+
url: "git+https://github.com/pxlabz/tasq.git",
|
|
6429
|
+
directory: "packages/cli"
|
|
6430
|
+
},
|
|
6431
|
+
bugs: {
|
|
6432
|
+
url: "https://github.com/pxlabz/tasq/issues"
|
|
6433
|
+
},
|
|
6434
|
+
private: false,
|
|
6435
|
+
type: "module",
|
|
6436
|
+
bin: {
|
|
6437
|
+
tasq: "./dist/tasq.js"
|
|
6438
|
+
},
|
|
6439
|
+
files: [
|
|
6440
|
+
"dist",
|
|
6441
|
+
"examples",
|
|
6442
|
+
".tasq-skill.md",
|
|
6443
|
+
"README.md",
|
|
6444
|
+
"LICENSE"
|
|
6445
|
+
],
|
|
6446
|
+
publishConfig: {
|
|
6447
|
+
access: "public"
|
|
6448
|
+
},
|
|
6449
|
+
engines: {
|
|
6450
|
+
node: ">=20.3"
|
|
6451
|
+
},
|
|
6452
|
+
scripts: {
|
|
6453
|
+
build: "tsup && chmod +x dist/tasq.js",
|
|
6454
|
+
typecheck: "tsc --project tsconfig.json --noEmit",
|
|
6455
|
+
lint: "cd ../.. && bun --bun ./node_modules/oxlint/bin/oxlint packages/cli",
|
|
6456
|
+
test: "bun test"
|
|
6457
|
+
},
|
|
6458
|
+
dependencies: {
|
|
6459
|
+
"@clack/prompts": "^0.11.0",
|
|
6460
|
+
"cli-table3": "^0.6.5",
|
|
6461
|
+
commander: "^14.0.0"
|
|
6462
|
+
},
|
|
6463
|
+
devDependencies: {
|
|
6464
|
+
"@pxlabz/tasq-sdk": "workspace:*",
|
|
6465
|
+
"@types/bun": "^1.3.12",
|
|
6466
|
+
tsup: "^8.5.0",
|
|
6467
|
+
typescript: "^5.7.2"
|
|
6468
|
+
}
|
|
6469
|
+
};
|
|
6470
|
+
|
|
6412
6471
|
// src/config.ts
|
|
6413
6472
|
import {
|
|
6414
6473
|
chmodSync,
|
|
@@ -6613,7 +6672,7 @@ var TasqClient = class _TasqClient {
|
|
|
6613
6672
|
this.#fetch = options.fetch ?? globalThis.fetch;
|
|
6614
6673
|
}
|
|
6615
6674
|
async #request(path, init = {}) {
|
|
6616
|
-
const { anonymous = false, ...requestInit } = init;
|
|
6675
|
+
const { anonymous = false, timeoutMs, ...requestInit } = init;
|
|
6617
6676
|
const headers = new Headers(requestInit.headers);
|
|
6618
6677
|
if (!anonymous) {
|
|
6619
6678
|
if (this.#token === void 0) throw noCredentialError();
|
|
@@ -6623,9 +6682,15 @@ var TasqClient = class _TasqClient {
|
|
|
6623
6682
|
headers.set("content-type", "application/json");
|
|
6624
6683
|
}
|
|
6625
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);
|
|
6626
6690
|
const response = await this.#fetch(`${this.#baseUrl}${path}`, {
|
|
6627
6691
|
...requestInit,
|
|
6628
|
-
headers
|
|
6692
|
+
headers,
|
|
6693
|
+
signal
|
|
6629
6694
|
});
|
|
6630
6695
|
if (!response.ok) {
|
|
6631
6696
|
throw await this.#toError(response);
|
|
@@ -6647,8 +6712,8 @@ var TasqClient = class _TasqClient {
|
|
|
6647
6712
|
};
|
|
6648
6713
|
return toTasqError(response.status, body, retryAfter);
|
|
6649
6714
|
}
|
|
6650
|
-
#get(path, params) {
|
|
6651
|
-
return this.#request(`${path}${queryString(params)}
|
|
6715
|
+
#get(path, params, options) {
|
|
6716
|
+
return this.#request(`${path}${queryString(params)}`, options);
|
|
6652
6717
|
}
|
|
6653
6718
|
workspaces = {
|
|
6654
6719
|
list: async () => (await this.#get("/workspaces")).workspaces,
|
|
@@ -6696,6 +6761,33 @@ var TasqClient = class _TasqClient {
|
|
|
6696
6761
|
agents = {
|
|
6697
6762
|
policy: (slug, agentId) => this.#get(
|
|
6698
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 }
|
|
6699
6791
|
)
|
|
6700
6792
|
};
|
|
6701
6793
|
auth = {
|
|
@@ -6867,6 +6959,9 @@ function formatWorkspaces(workspaces) {
|
|
|
6867
6959
|
])
|
|
6868
6960
|
);
|
|
6869
6961
|
}
|
|
6962
|
+
function line(io2, value) {
|
|
6963
|
+
io2.out(JSON.stringify(value));
|
|
6964
|
+
}
|
|
6870
6965
|
|
|
6871
6966
|
// src/commands/auth.ts
|
|
6872
6967
|
var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
|
|
@@ -6970,17 +7065,70 @@ async function resolveTaskId(client, slug, ref) {
|
|
|
6970
7065
|
}
|
|
6971
7066
|
|
|
6972
7067
|
// src/commands/comment.ts
|
|
6973
|
-
|
|
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 = {}) {
|
|
6974
7109
|
const slug = requireWorkspace(ctx.config);
|
|
6975
7110
|
const taskId = await resolveTaskId(ctx.client, slug, taskRef);
|
|
6976
7111
|
const task = await ctx.client.tasks.get(slug, taskId);
|
|
6977
|
-
const
|
|
6978
|
-
|
|
6979
|
-
|
|
6980
|
-
}
|
|
6981
|
-
|
|
6982
|
-
|
|
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])
|
|
6983
7128
|
);
|
|
7129
|
+
for (const mention of added.result.mentions ?? []) {
|
|
7130
|
+
ctx.io.out(mentionLine(mention.state, nameById.get(mention.agentId)));
|
|
7131
|
+
}
|
|
6984
7132
|
}
|
|
6985
7133
|
|
|
6986
7134
|
// src/commands/cycle.ts
|
|
@@ -7013,6 +7161,47 @@ async function cycleCurrent(ctx, options) {
|
|
|
7013
7161
|
}
|
|
7014
7162
|
}
|
|
7015
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
|
+
|
|
7016
7205
|
// src/commands/project.ts
|
|
7017
7206
|
async function projectList(ctx) {
|
|
7018
7207
|
const slug = requireWorkspace(ctx.config);
|
|
@@ -7250,7 +7439,7 @@ function contextFor(program2, io2) {
|
|
|
7250
7439
|
}
|
|
7251
7440
|
function buildProgram(io2) {
|
|
7252
7441
|
const program2 = new Command();
|
|
7253
|
-
program2.name("tasq").description("Command-line client for Tasq").version(
|
|
7442
|
+
program2.name("tasq").description("Command-line client for Tasq").version(package_default.version).option("-w, --workspace <slug>", "workspace slug").option("--api-url <url>", "API base URL").option("--json", "print raw JSON instead of a table").exitOverride();
|
|
7254
7443
|
const run = (handler) => async () => {
|
|
7255
7444
|
await handler(contextFor(program2, io2));
|
|
7256
7445
|
};
|
|
@@ -7295,8 +7484,35 @@ function buildProgram(io2) {
|
|
|
7295
7484
|
});
|
|
7296
7485
|
});
|
|
7297
7486
|
const comment = program2.command("comment").description("Task comments");
|
|
7298
|
-
comment.command("add").argument("<taskId>", "task identifier or id").argument("<body>", "comment body").description("Add a comment to a task").
|
|
7299
|
-
|
|
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);
|
|
7300
7516
|
});
|
|
7301
7517
|
const project = program2.command("project").description("Projects");
|
|
7302
7518
|
project.command("list").description("List projects").action(run((ctx) => projectList(ctx)));
|
|
@@ -7333,12 +7549,12 @@ async function main(argv, io2) {
|
|
|
7333
7549
|
}
|
|
7334
7550
|
}
|
|
7335
7551
|
var io = {
|
|
7336
|
-
out: (
|
|
7337
|
-
process.stdout.write(`${
|
|
7552
|
+
out: (line2) => {
|
|
7553
|
+
process.stdout.write(`${line2}
|
|
7338
7554
|
`);
|
|
7339
7555
|
},
|
|
7340
|
-
err: (
|
|
7341
|
-
process.stderr.write(`${
|
|
7556
|
+
err: (line2) => {
|
|
7557
|
+
process.stderr.write(`${line2}
|
|
7342
7558
|
`);
|
|
7343
7559
|
}
|
|
7344
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",
|
|
@@ -43,11 +45,11 @@
|
|
|
43
45
|
},
|
|
44
46
|
"dependencies": {
|
|
45
47
|
"@clack/prompts": "^0.11.0",
|
|
46
|
-
"@pxlabz/tasq-sdk": "0.1.0",
|
|
47
48
|
"cli-table3": "^0.6.5",
|
|
48
49
|
"commander": "^14.0.0"
|
|
49
50
|
},
|
|
50
51
|
"devDependencies": {
|
|
52
|
+
"@pxlabz/tasq-sdk": "0.1.0",
|
|
51
53
|
"@types/bun": "^1.3.12",
|
|
52
54
|
"tsup": "^8.5.0",
|
|
53
55
|
"typescript": "^5.7.2"
|