@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 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((line) => {
778
- const chunks = line.match(chunkPattern);
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(line) {
3685
+ function readState(line2) {
3686
3686
  let code = codeRegex(true);
3687
- let controlChars = code.exec(line);
3687
+ let controlChars = code.exec(line2);
3688
3688
  let state = {};
3689
3689
  while (controlChars !== null) {
3690
3690
  updateState(state, controlChars);
3691
- controlChars = code.exec(line);
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 line = [];
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(line.join(""));
3838
+ lines.push(line2.join(""));
3839
3839
  }
3840
- line = [word];
3840
+ line2 = [word];
3841
3841
  lineLength = strlen(word);
3842
3842
  } else {
3843
- line.push(whitespace || "", word);
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(line.join(""));
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 line = "";
3855
+ let line2 = "";
3856
3856
  function pushLine(str, ws) {
3857
- if (line.length && ws) line += ws;
3858
- line += str;
3859
- while (line.length > maxLength) {
3860
- lines.push(line.slice(0, maxLength));
3861
- line = line.slice(maxLength);
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 (line.length) lines.push(line);
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 line = rewindState(state, input[i]);
3885
- state = readState(line);
3884
+ let line2 = rewindState(state, input[i]);
3885
+ state = readState(line2);
3886
3886
  let temp = Object.assign({}, state);
3887
- output.push(unwindState(temp, line));
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((line) => utils.hyperlink(this.href, line));
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 line = this.lines[lineNum];
4812
+ let line2 = this.lines[lineNum];
4813
4813
  let len = this.width - (this.paddingLeft + this.paddingRight);
4814
- if (forceTruncationSymbol) line += this.truncate || "\u2026";
4815
- let content = utils.truncate(line, len, this.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 line = [];
5277
+ let line2 = [];
5278
5278
  row.forEach(function(cell) {
5279
- line.push(cell.draw(lineNum));
5279
+ line2.push(cell.draw(lineNum));
5280
5280
  });
5281
- let str = line.join("");
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.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
- async function commentAdd(ctx, taskRef, body) {
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 added = await ctx.client.dispatch("comment.add", slug, {
7035
- taskId: task.id,
7036
- body
7037
- });
7038
- ctx.io.out(
7039
- ctx.config.json ? jsonOutput(added.result) : `Comment added to ${task.identifier}.`
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").action(async (taskId, body) => {
7356
- await commentAdd(contextFor(program2, io2), taskId, body);
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: (line) => {
7394
- process.stdout.write(`${line}
7552
+ out: (line2) => {
7553
+ process.stdout.write(`${line2}
7395
7554
  `);
7396
7555
  },
7397
- err: (line) => {
7398
- process.stderr.write(`${line}
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.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",