@pxlabz/tasq-cli 0.1.2 → 0.1.4

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
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.
3
+ description: Read and write Tasq tasks, projects, threads, 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 and thread messages addressed to you. Covers authentication, the full command reference, the mention-reply-ack workflow, threads, exit codes, and working alongside other agents.
4
4
  ---
5
5
 
6
6
  # Tasq
@@ -47,7 +47,13 @@ tasq task create <title> [--team <identifier>] [--description <markdown>]
47
47
  tasq task update <ref> [--title <title>] [--description <markdown>]
48
48
  [--priority <priority>] [--status <name>]
49
49
 
50
- tasq comment add <ref> <body> [--reply-to <commentRef>] [--mention <agentName>]…
50
+ tasq comment add <ref> <body> [--reply-to <commentRef>] [--thread <threadId>]
51
+ [--mention <agentName>]…
52
+ tasq comment add --project <id|name> <body> [--reply-to <commentRef>]
53
+ [--thread <threadId>] [--mention <agentName>]…
54
+
55
+ tasq thread view <threadId>
56
+ tasq thread context <threadId> [--markdown]
51
57
 
52
58
  tasq events listen [--wait <seconds>] [--once]
53
59
  tasq events ack <id>…
@@ -60,24 +66,60 @@ tasq auth logout
60
66
  tasq auth whoami
61
67
  ```
62
68
 
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.
69
+ `--mention` is repeatable and matches an agent name exactly, ignoring case.
70
+
71
+ `task view` and `thread view` print every message with its id on the header line, as ` <createdAt> <author> #<id>` with the body indented beneath it. That `#<id>` is what `--reply-to` and `--thread` take; the `ENG-42#<id>` form is also accepted. The parent must be a message on the same task or project.
72
+
73
+ `--thread <threadId>` is an alias for `--reply-to` that reads right when you are answering an event: the `threadId` an event carries is exactly what it wants. Passing both is fine if they name the same message; two different ids is a usage error.
74
+
75
+ A comment goes on a task or a project, never both and never neither: give the task ref as the argument, or pass `--project <id|name>` instead. Project names match exactly, ignoring case.
64
76
 
65
77
  ## When you are mentioned
66
78
 
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.
79
+ `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, projectId, threadId, commentId, mentionedBy, deliveryCount, createdAt }`. `kind` is `mention` or `thread_message`; exactly one of `taskId` and `projectId` is set; `mentionedBy` carries `{ memberId, type, name }`, and its `type` is `user` or `agent`. 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
80
 
69
81
  The loop is:
70
82
 
71
83
  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
84
  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.
85
+ 3. **Gather context.** `tasq thread context <threadId>` assembles the entity, the transcript and the recent activity in one call — see **Threads** below. The `task view` payload carries the same comments and activity log if the mention is on a task and you want the raw shape. Read before you write.
86
+ 4. **Reply in the thread.** `tasq comment add <taskKey> "…" --thread <threadId>`, using the `threadId` from the event so your answer lands in the conversation rather than at the bottom. On a project mention, `tasq comment add --project <id|name> "…" --thread <threadId>`.
75
87
  5. **Acknowledge.** `tasq events ack <eventId>`, and only after the work is done.
76
88
 
77
89
  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
90
 
79
91
  `examples/mention-runner.sh` in this package is a working reference for steps 1 and 5. It is an example, not a product.
80
92
 
93
+ ## Threads
94
+
95
+ A thread is a root message and its replies, on a task or on a project. Its id — the `threadId` an event carries — is the root message's id.
96
+
97
+ Two event kinds reach you, and they mean different things:
98
+
99
+ - **`mention`** is a request addressed to you. Somebody typed your name. Read it and act.
100
+ - **`thread_message`** is a later message in a thread you are already in — you were mentioned in it once, or you have spoken in it, so Tasq keeps sending you the conversation without anybody re-typing `@`. Read it, and reply only if it actually needs you. Most of the time it is context, not a request; a thread does not need you to answer every turn. Check `mentionedBy.type`: on an open team it may be another agent's message (see **Working with other agents**).
101
+
102
+ Start from the context bundle rather than guessing which entity the thread is on:
103
+
104
+ ```
105
+ tasq thread context <threadId>
106
+ ```
107
+
108
+ That prints a Markdown prompt with four sections in a fixed order — **Entity**, **Thread**, **Recent activity**, **Participants** — covering the task or project the thread hangs off, the transcript so far, what else happened on that entity, and who is in the conversation. `--json` gives the same bundle raw if you would rather branch on the fields. The lists are capped (last 50 messages, last 20 activity rows, description cut at 8k chars); anything cut says so, so a `_(showing last 50 of 130 messages)_` line means there is more you are not seeing.
109
+
110
+ `tasq thread view <threadId>` is the short form: the entity line and the transcript with each message's id, when all you need is an id to reply to.
111
+
112
+ Reply into the thread with the id the event gave you, whichever entity it is on:
113
+
114
+ ```
115
+ tasq comment add <taskKey> "…" --thread <threadId>
116
+ tasq comment add --project <projectName> "…" --thread <threadId>
117
+ ```
118
+
119
+ Acknowledge both kinds the same way, with `tasq events ack <eventId>`, and only after you are done — including when you decide a `thread_message` needed nothing from you. An unacked event comes back in ten minutes.
120
+
121
+ On an isolated team — the default — another agent's messages do not reach you and yours do not wake another agent, so a thread that needs work you cannot do is a thread to escalate to a person. See **Working with other agents** below.
122
+
81
123
  ## Exit codes
82
124
 
83
125
  | Code | Meaning |
@@ -88,6 +130,12 @@ Ack last, deliberately. An unacknowledged event is offered again ten minutes aft
88
130
  | 3 | Rate limited; the message says when to retry. `events listen` never exits here — it waits and continues |
89
131
  | 4 | Your policy denied the action. Do not retry it; say what was refused |
90
132
 
91
- ## Isolation
133
+ ## Working with other agents
134
+
135
+ Isolation is the default. On an isolated team your mentions of other agents and your thread messages are recorded but never delivered, and the CLI line tells you so: `hermes: suppressed: agents are isolated on this team`. Nothing you write reaches another agent, and nothing another agent writes reaches you. When a thread needs work you cannot do, escalate to a person in the thread rather than trying to hand it to an agent.
136
+
137
+ A team admin can turn isolation off for a team in **Settings → Teams → Agents**. On an open team your messages wake the other agents on that team's tasks and projects, and theirs wake you. An event whose `mentionedBy.type` is `agent` is another agent's message, not a person's: reply only when you add something. Never reply just to acknowledge, and never re-mention an agent that mentioned you unless you actually need something from it.
138
+
139
+ Two limits stand behind an open team. After 5 agent messages in a row in one thread, Tasq stops waking agents until a person posts (`suppressed: loop stopped after 5 agent messages in a row; waiting for a person`). One message never wakes more than 10 agents (`suppressed: fan-out cap of 10 reached`). Both are reported on the line `comment add` prints and in your activity timeline; the comment itself is still saved either way, and the people in the thread are still notified.
92
140
 
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.
141
+ Projects shared with a team that kept isolation stay isolated.
package/dist/tasq.js CHANGED
@@ -6409,133 +6409,6 @@ 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
-
6471
- // src/config.ts
6472
- import {
6473
- chmodSync,
6474
- mkdirSync,
6475
- readFileSync,
6476
- writeFileSync
6477
- } from "fs";
6478
- import { homedir } from "os";
6479
- import { join } from "path";
6480
- var DEFAULT_API_URL = "https://tasq.pxlabz.com";
6481
- function configDir(env) {
6482
- if (env.TASQ_CONFIG_DIR !== void 0) return env.TASQ_CONFIG_DIR;
6483
- const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
6484
- return join(base, "tasq");
6485
- }
6486
- function configFilePath(env) {
6487
- return join(configDir(env), "config.json");
6488
- }
6489
- function readStoredConfig(env) {
6490
- let raw;
6491
- try {
6492
- raw = readFileSync(configFilePath(env), "utf8");
6493
- } catch {
6494
- return {};
6495
- }
6496
- try {
6497
- const parsed = JSON.parse(raw);
6498
- return parsed ?? {};
6499
- } catch {
6500
- return {};
6501
- }
6502
- }
6503
- function saveConfig(patch, env) {
6504
- const dir = configDir(env);
6505
- mkdirSync(dir, { recursive: true, mode: 448 });
6506
- const merged = { ...readStoredConfig(env), ...patch };
6507
- for (const key of Object.keys(merged)) {
6508
- if (merged[key] === void 0) delete merged[key];
6509
- }
6510
- const path = configFilePath(env);
6511
- writeFileSync(path, `${JSON.stringify(merged, null, 2)}
6512
- `, { mode: 384 });
6513
- chmodSync(path, 384);
6514
- }
6515
- function credentialFrom(env, stored) {
6516
- if (env.TASQ_API_KEY !== void 0 && env.TASQ_API_KEY !== "") {
6517
- return { agentKey: env.TASQ_API_KEY };
6518
- }
6519
- if (env.TASQ_USER_TOKEN !== void 0 && env.TASQ_USER_TOKEN !== "") {
6520
- return { userToken: env.TASQ_USER_TOKEN };
6521
- }
6522
- if (stored.userToken !== void 0 && stored.userToken !== "") {
6523
- return { userToken: stored.userToken };
6524
- }
6525
- return void 0;
6526
- }
6527
- function loadConfig(input) {
6528
- const { env, flags } = input;
6529
- const stored = readStoredConfig(env);
6530
- return {
6531
- apiUrl: flags.apiUrl ?? env.TASQ_API_URL ?? stored.apiUrl ?? DEFAULT_API_URL,
6532
- workspace: flags.workspace ?? env.TASQ_WORKSPACE ?? stored.workspace,
6533
- credential: credentialFrom(env, stored),
6534
- json: flags.json === true,
6535
- env
6536
- };
6537
- }
6538
-
6539
6412
  // ../sdk/src/prefixes.ts
6540
6413
  var AGENT_KEY_PREFIX = "tq_ag_";
6541
6414
  var USER_TOKEN_PREFIX = "tq_us_";
@@ -6738,6 +6611,20 @@ var TasqClient = class _TasqClient {
6738
6611
  `/workspaces/${encodeURIComponent(slug)}/projects/${encodeURIComponent(projectId)}`
6739
6612
  )).project
6740
6613
  };
6614
+ threads = {
6615
+ /**
6616
+ * The context bundle for one thread: the entity it hangs off, the
6617
+ * transcript, recent activity, and the participants (D-6).
6618
+ *
6619
+ * Authorized by the entity's own read rule, so a read-only agent may
6620
+ * pull it. Lists are capped per D-8 with `truncated` flags.
6621
+ */
6622
+ context: (slug, threadId, options) => this.#get(
6623
+ `/workspaces/${encodeURIComponent(slug)}/threads/${encodeURIComponent(threadId)}/context`,
6624
+ void 0,
6625
+ options
6626
+ )
6627
+ };
6741
6628
  cycles = {
6742
6629
  list: async (slug, filters2) => (await this.#get(
6743
6630
  `/workspaces/${encodeURIComponent(slug)}/cycles`,
@@ -6751,7 +6638,17 @@ var TasqClient = class _TasqClient {
6751
6638
  /** The only read that carries a team's statuses. */
6752
6639
  get: async (slug, identifier) => (await this.#get(
6753
6640
  `/workspaces/${encodeURIComponent(slug)}/teams/${encodeURIComponent(identifier)}`
6754
- )).team
6641
+ )).team,
6642
+ /**
6643
+ * Whether agents on this team may wake each other, plus the loop and
6644
+ * fan-out limits that stand behind the open setting (B-04c D-1).
6645
+ *
6646
+ * Read-only here on purpose: saving the setting is admin-only and web-only
6647
+ * (D-8), so no agent key can reach it.
6648
+ */
6649
+ agentSettings: (slug, identifier) => this.#get(
6650
+ `/workspaces/${encodeURIComponent(slug)}/teams/${encodeURIComponent(identifier)}/agent-settings`
6651
+ )
6755
6652
  };
6756
6653
  labels = {
6757
6654
  list: async (slug) => (await this.#get(
@@ -6821,6 +6718,10 @@ var TasqClient = class _TasqClient {
6821
6718
  }
6822
6719
  };
6823
6720
 
6721
+ // ../sdk/src/types.ts
6722
+ var MAX_AGENT_WAKES_PER_MESSAGE = 10;
6723
+ var MAX_CONSECUTIVE_AGENT_MESSAGES = 5;
6724
+
6824
6725
  // src/errors.ts
6825
6726
  var EXIT_OK = 0;
6826
6727
  var EXIT_ERROR = 1;
@@ -6879,6 +6780,133 @@ function reportError(error, io2) {
6879
6780
  return EXIT_ERROR;
6880
6781
  }
6881
6782
 
6783
+ // package.json
6784
+ var package_default = {
6785
+ name: "@pxlabz/tasq-cli",
6786
+ version: "0.1.4",
6787
+ description: "Command-line client for Tasq, for humans and agents alike",
6788
+ keywords: [
6789
+ "tasq",
6790
+ "cli",
6791
+ "agents",
6792
+ "project-management"
6793
+ ],
6794
+ license: "MIT",
6795
+ author: "Paul Cedrick Artigo",
6796
+ homepage: "https://github.com/pxlabz/tasq/tree/main/packages/cli#readme",
6797
+ repository: {
6798
+ type: "git",
6799
+ url: "git+https://github.com/pxlabz/tasq.git",
6800
+ directory: "packages/cli"
6801
+ },
6802
+ bugs: {
6803
+ url: "https://github.com/pxlabz/tasq/issues"
6804
+ },
6805
+ private: false,
6806
+ type: "module",
6807
+ bin: {
6808
+ tasq: "./dist/tasq.js"
6809
+ },
6810
+ files: [
6811
+ "dist",
6812
+ "examples",
6813
+ ".tasq-skill.md",
6814
+ "README.md",
6815
+ "LICENSE"
6816
+ ],
6817
+ publishConfig: {
6818
+ access: "public"
6819
+ },
6820
+ engines: {
6821
+ node: ">=20.3"
6822
+ },
6823
+ scripts: {
6824
+ build: "tsup && chmod +x dist/tasq.js",
6825
+ typecheck: "tsc --project tsconfig.json --noEmit",
6826
+ lint: "cd ../.. && bun --bun ./node_modules/oxlint/bin/oxlint packages/cli",
6827
+ test: "bun test"
6828
+ },
6829
+ dependencies: {
6830
+ "@clack/prompts": "^0.11.0",
6831
+ "cli-table3": "^0.6.5",
6832
+ commander: "^14.0.0"
6833
+ },
6834
+ devDependencies: {
6835
+ "@pxlabz/tasq-sdk": "workspace:*",
6836
+ "@types/bun": "^1.3.12",
6837
+ tsup: "^8.5.0",
6838
+ typescript: "^5.7.2"
6839
+ }
6840
+ };
6841
+
6842
+ // src/config.ts
6843
+ import {
6844
+ chmodSync,
6845
+ mkdirSync,
6846
+ readFileSync,
6847
+ writeFileSync
6848
+ } from "fs";
6849
+ import { homedir } from "os";
6850
+ import { join } from "path";
6851
+ var DEFAULT_API_URL = "https://tasq.pxlabz.com";
6852
+ function configDir(env) {
6853
+ if (env.TASQ_CONFIG_DIR !== void 0) return env.TASQ_CONFIG_DIR;
6854
+ const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
6855
+ return join(base, "tasq");
6856
+ }
6857
+ function configFilePath(env) {
6858
+ return join(configDir(env), "config.json");
6859
+ }
6860
+ function readStoredConfig(env) {
6861
+ let raw;
6862
+ try {
6863
+ raw = readFileSync(configFilePath(env), "utf8");
6864
+ } catch {
6865
+ return {};
6866
+ }
6867
+ try {
6868
+ const parsed = JSON.parse(raw);
6869
+ return parsed ?? {};
6870
+ } catch {
6871
+ return {};
6872
+ }
6873
+ }
6874
+ function saveConfig(patch, env) {
6875
+ const dir = configDir(env);
6876
+ mkdirSync(dir, { recursive: true, mode: 448 });
6877
+ const merged = { ...readStoredConfig(env), ...patch };
6878
+ for (const key of Object.keys(merged)) {
6879
+ if (merged[key] === void 0) delete merged[key];
6880
+ }
6881
+ const path = configFilePath(env);
6882
+ writeFileSync(path, `${JSON.stringify(merged, null, 2)}
6883
+ `, { mode: 384 });
6884
+ chmodSync(path, 384);
6885
+ }
6886
+ function credentialFrom(env, stored) {
6887
+ if (env.TASQ_API_KEY !== void 0 && env.TASQ_API_KEY !== "") {
6888
+ return { agentKey: env.TASQ_API_KEY };
6889
+ }
6890
+ if (env.TASQ_USER_TOKEN !== void 0 && env.TASQ_USER_TOKEN !== "") {
6891
+ return { userToken: env.TASQ_USER_TOKEN };
6892
+ }
6893
+ if (stored.userToken !== void 0 && stored.userToken !== "") {
6894
+ return { userToken: stored.userToken };
6895
+ }
6896
+ return void 0;
6897
+ }
6898
+ function loadConfig(input) {
6899
+ const { env, flags } = input;
6900
+ const stored = readStoredConfig(env);
6901
+ return {
6902
+ apiUrl: flags.apiUrl ?? env.TASQ_API_URL ?? stored.apiUrl ?? DEFAULT_API_URL,
6903
+ workspace: flags.workspace ?? env.TASQ_WORKSPACE ?? stored.workspace,
6904
+ credential: credentialFrom(env, stored),
6905
+ json: flags.json === true,
6906
+ env
6907
+ };
6908
+ }
6909
+
6882
6910
  // src/context.ts
6883
6911
  function createClient(config) {
6884
6912
  if (config.credential === void 0) {
@@ -7065,20 +7093,32 @@ async function resolveTaskId(client, slug, ref) {
7065
7093
  }
7066
7094
 
7067
7095
  // src/commands/comment.ts
7096
+ var UUID_PATTERN2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
7068
7097
  function commentIdOf(ref) {
7069
7098
  const hash = ref.lastIndexOf("#");
7070
7099
  return hash === -1 ? ref.trim() : ref.slice(hash + 1).trim();
7071
7100
  }
7072
- function resolveParentId(task, ref) {
7101
+ function resolveParentId(comments, entityLabel, ref) {
7073
7102
  const id = commentIdOf(ref);
7074
- const found = task.comments.find((comment) => comment.id === id);
7103
+ const found = comments.find((comment) => comment.id === id);
7075
7104
  if (found === void 0) {
7076
7105
  throw new UsageError(
7077
- `"${ref}" is not a comment on ${task.identifier}. Replies must stay in the same task.`
7106
+ `"${ref}" is not a comment on ${entityLabel}. Replies must stay on the same task or project.`
7078
7107
  );
7079
7108
  }
7080
7109
  return found.id;
7081
7110
  }
7111
+ function replyRef(options) {
7112
+ const { replyTo, thread } = options;
7113
+ if (replyTo === void 0) return thread;
7114
+ if (thread === void 0) return replyTo;
7115
+ if (commentIdOf(replyTo) !== commentIdOf(thread)) {
7116
+ throw new UsageError(
7117
+ `--thread "${thread}" and --reply-to "${replyTo}" name different comments. Pass one.`
7118
+ );
7119
+ }
7120
+ return replyTo;
7121
+ }
7082
7122
  function resolveMentions(members, names) {
7083
7123
  const agents = members.filter(
7084
7124
  (member) => member.type === "agent" && member.agentId !== null
@@ -7101,20 +7141,112 @@ function resolveMentions(members, names) {
7101
7141
  return matched[0]?.agentId ?? "";
7102
7142
  });
7103
7143
  }
7104
- function mentionLine(state, name) {
7144
+ function reasonPhrase(reason) {
7145
+ switch (reason) {
7146
+ case "isolation":
7147
+ return "agents are isolated on this team";
7148
+ case "loop_cap":
7149
+ return `loop stopped after ${MAX_CONSECUTIVE_AGENT_MESSAGES} agent messages in a row; waiting for a person`;
7150
+ case "fanout_cap":
7151
+ return `fan-out cap of ${MAX_AGENT_WAKES_PER_MESSAGE} reached`;
7152
+ default:
7153
+ return null;
7154
+ }
7155
+ }
7156
+ function mentionLine(outcome, name) {
7105
7157
  const who = name ?? "an agent";
7106
- return state === "suppressed" ? `${who}: suppressed: agents are isolated` : `delivered to ${who}`;
7158
+ if (outcome.state !== "suppressed") return `delivered to ${who}`;
7159
+ const phrase = reasonPhrase(outcome.reason);
7160
+ return phrase === null ? `${who}: suppressed` : `${who}: suppressed: ${phrase}`;
7107
7161
  }
7108
- async function commentAdd(ctx, taskRef, body, options = {}) {
7109
- const slug = requireWorkspace(ctx.config);
7162
+ function agentCount(count) {
7163
+ return count === 1 ? "1 agent" : `${count} agents`;
7164
+ }
7165
+ function threadLine(outcomes) {
7166
+ const delivered = outcomes.filter(
7167
+ (outcome) => outcome.state !== "suppressed"
7168
+ ).length;
7169
+ const suppressed = outcomes.length - delivered;
7170
+ if (suppressed === 0) return `thread: delivered to ${agentCount(delivered)}`;
7171
+ const phrases = [
7172
+ ...new Set(
7173
+ outcomes.flatMap((outcome) => {
7174
+ if (outcome.state !== "suppressed") return [];
7175
+ const phrase = reasonPhrase(outcome.reason);
7176
+ return phrase === null ? [] : [phrase];
7177
+ })
7178
+ )
7179
+ ];
7180
+ const why = phrases.length === 0 ? "" : ` (${phrases.join("; ")})`;
7181
+ return `thread: delivered to ${agentCount(delivered)}, ${suppressed} suppressed${why}`;
7182
+ }
7183
+ async function resolveProjectId(ctx, slug, ref) {
7184
+ const trimmed = ref.trim();
7185
+ if (UUID_PATTERN2.test(trimmed)) return trimmed;
7186
+ const wanted = trimmed.toLowerCase();
7187
+ const projects = await ctx.client.projects.list(slug);
7188
+ const matched = projects.filter(
7189
+ (project) => project.name.toLowerCase() === wanted
7190
+ );
7191
+ if (matched.length === 0) {
7192
+ throw new UsageError(
7193
+ `No project named "${ref}" in this workspace. Run "tasq project list" to see the names.`
7194
+ );
7195
+ }
7196
+ if (matched.length > 1) {
7197
+ throw new UsageError(
7198
+ `"${ref}" matches ${matched.length} projects. Pass the project id.`
7199
+ );
7200
+ }
7201
+ return matched[0]?.id ?? "";
7202
+ }
7203
+ function commentPositionals(first, second, project) {
7204
+ if (second !== void 0) return { taskRef: first, body: second };
7205
+ if (project === void 0) {
7206
+ throw new UsageError(
7207
+ "Nothing to comment on. Pass a task key such as ENG-42, or --project <id|name>."
7208
+ );
7209
+ }
7210
+ return { taskRef: void 0, body: first };
7211
+ }
7212
+ async function resolveTarget(ctx, slug, taskRef, project) {
7213
+ if (taskRef !== void 0 && project !== void 0) {
7214
+ throw new UsageError(
7215
+ "Pass either a task or --project <id|name>, not both."
7216
+ );
7217
+ }
7218
+ if (project !== void 0) {
7219
+ const projectId = await resolveProjectId(ctx, slug, project);
7220
+ const detail = await ctx.client.projects.get(slug, projectId);
7221
+ return {
7222
+ input: { projectId: detail.id },
7223
+ label: detail.name,
7224
+ comments: detail.comments
7225
+ };
7226
+ }
7227
+ if (taskRef === void 0) {
7228
+ throw new UsageError(
7229
+ "Nothing to comment on. Pass a task key such as ENG-42, or --project <id|name>."
7230
+ );
7231
+ }
7110
7232
  const taskId = await resolveTaskId(ctx.client, slug, taskRef);
7111
7233
  const task = await ctx.client.tasks.get(slug, taskId);
7234
+ return {
7235
+ input: { taskId: task.id },
7236
+ label: task.identifier,
7237
+ comments: task.comments
7238
+ };
7239
+ }
7240
+ async function commentAdd(ctx, taskRef, body, options = {}) {
7241
+ const slug = requireWorkspace(ctx.config);
7242
+ const target = await resolveTarget(ctx, slug, taskRef, options.project);
7112
7243
  const names = options.mention ?? [];
7113
7244
  const members = names.length === 0 ? [] : await ctx.client.members.list(slug);
7114
7245
  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);
7246
+ const input = { ...target.input, body };
7247
+ const parent = replyRef(options);
7248
+ if (parent !== void 0) {
7249
+ input.parentId = resolveParentId(target.comments, target.label, parent);
7118
7250
  }
7119
7251
  if (mentions.length > 0) input.mentions = mentions;
7120
7252
  const added = await ctx.client.dispatch("comment.add", slug, input);
@@ -7122,13 +7254,15 @@ async function commentAdd(ctx, taskRef, body, options = {}) {
7122
7254
  ctx.io.out(jsonOutput(added.result));
7123
7255
  return;
7124
7256
  }
7125
- ctx.io.out(`Comment added to ${task.identifier}.`);
7257
+ ctx.io.out(`Comment added to ${target.label}.`);
7126
7258
  const nameById = new Map(
7127
7259
  members.map((member) => [member.agentId, member.name])
7128
7260
  );
7129
7261
  for (const mention of added.result.mentions ?? []) {
7130
- ctx.io.out(mentionLine(mention.state, nameById.get(mention.agentId)));
7262
+ ctx.io.out(mentionLine(mention, nameById.get(mention.agentId)));
7131
7263
  }
7264
+ const threadMessages = added.result.threadMessages ?? [];
7265
+ if (threadMessages.length > 0) ctx.io.out(threadLine(threadMessages));
7132
7266
  }
7133
7267
 
7134
7268
  // src/commands/cycle.ts
@@ -7209,6 +7343,109 @@ async function projectList(ctx) {
7209
7343
  ctx.io.out(ctx.config.json ? jsonOutput(projects) : formatProjects(projects));
7210
7344
  }
7211
7345
 
7346
+ // src/render/thread-context.ts
7347
+ function entityHeading(entity) {
7348
+ return entity.key === null ? `**${entity.title}**` : `**${entity.key}** \u2014 ${entity.title}`;
7349
+ }
7350
+ function entityFacts(entity) {
7351
+ const facts = [`- Type: ${entity.type}`, `- Status: ${entity.status ?? "\u2014"}`];
7352
+ if (entity.type === "task") {
7353
+ facts.push(`- Project: ${entity.project?.name ?? "\u2014"}`);
7354
+ return facts;
7355
+ }
7356
+ const teams = entity.teams.map((team) => `${team.name} (${team.identifier})`).join(", ");
7357
+ facts.push(`- Teams: ${teams === "" ? "\u2014" : teams}`);
7358
+ return facts;
7359
+ }
7360
+ function entitySection(entity) {
7361
+ const rows = [entityHeading(entity), "", ...entityFacts(entity), ""];
7362
+ rows.push(
7363
+ entity.description === null || entity.description === "" ? "_No description._" : entity.description
7364
+ );
7365
+ if (entity.descriptionTruncated) rows.push("", "_(description truncated)_");
7366
+ return rows.join("\n");
7367
+ }
7368
+ function messageLine(message) {
7369
+ const author = message.authorName ?? "unknown";
7370
+ const type = message.authorType ?? "unknown";
7371
+ return `- **${author}** (${type}, ${message.createdAt}): ${message.body}`;
7372
+ }
7373
+ function threadSection(thread) {
7374
+ const rows = [];
7375
+ if (thread.truncated) {
7376
+ rows.push(
7377
+ `_(showing last ${thread.messages.length} of ${thread.total} messages)_`,
7378
+ ""
7379
+ );
7380
+ }
7381
+ if (thread.messages.length === 0) {
7382
+ rows.push("_none_");
7383
+ return rows.join("\n");
7384
+ }
7385
+ rows.push(...thread.messages.map(messageLine));
7386
+ return rows.join("\n");
7387
+ }
7388
+ function activitySection(activity) {
7389
+ if (activity.length === 0) return "_none_";
7390
+ return activity.map(
7391
+ (entry) => `- ${entry.createdAt} ${entry.actorName ?? "unknown"}: ${entry.summary}`
7392
+ ).join("\n");
7393
+ }
7394
+ function participantsSection(participants) {
7395
+ if (participants.length === 0) return "_none_";
7396
+ return participants.map(
7397
+ (participant) => `- ${participant.name ?? "unknown"} (${participant.type}, joined via ${participant.joinedVia})`
7398
+ ).join("\n");
7399
+ }
7400
+ function renderThreadContext(bundle) {
7401
+ return [
7402
+ "## Entity",
7403
+ "",
7404
+ entitySection(bundle.entity),
7405
+ "",
7406
+ "## Thread",
7407
+ "",
7408
+ threadSection(bundle.thread),
7409
+ "",
7410
+ "## Recent activity",
7411
+ "",
7412
+ activitySection(bundle.recentActivity),
7413
+ "",
7414
+ "## Participants",
7415
+ "",
7416
+ participantsSection(bundle.participants)
7417
+ ].join("\n");
7418
+ }
7419
+
7420
+ // src/commands/thread.ts
7421
+ function entityLine(entity) {
7422
+ const name = entity.key === null ? entity.title : `${entity.key} \xB7 ${entity.title}`;
7423
+ return `${name} (${entity.status ?? "\u2014"})`;
7424
+ }
7425
+ async function threadView(ctx, threadId) {
7426
+ const slug = requireWorkspace(ctx.config);
7427
+ const bundle = await ctx.client.threads.context(slug, threadId);
7428
+ if (ctx.config.json) {
7429
+ ctx.io.out(jsonOutput(bundle));
7430
+ return;
7431
+ }
7432
+ ctx.io.out(entityLine(bundle.entity));
7433
+ ctx.io.out("");
7434
+ ctx.io.out(`Messages (${bundle.thread.total})`);
7435
+ for (const message of bundle.thread.messages) {
7436
+ const author = message.authorName ?? "unknown";
7437
+ ctx.io.out(` ${message.createdAt} ${author} #${message.id}`);
7438
+ ctx.io.out(` ${message.body}`);
7439
+ }
7440
+ }
7441
+ async function threadContext(ctx, threadId, _options = {}) {
7442
+ const slug = requireWorkspace(ctx.config);
7443
+ const bundle = await ctx.client.threads.context(slug, threadId);
7444
+ ctx.io.out(
7445
+ ctx.config.json ? jsonOutput(bundle) : renderThreadContext(bundle)
7446
+ );
7447
+ }
7448
+
7212
7449
  // src/commands/task.ts
7213
7450
  var PRIORITIES = ["urgent", "high", "medium", "low", "none"];
7214
7451
  function priority(value) {
@@ -7282,7 +7519,8 @@ async function taskView(ctx, taskRef) {
7282
7519
  ctx.io.out(`Comments (${task.comments.length})`);
7283
7520
  for (const comment of task.comments) {
7284
7521
  const author = comment.author?.name ?? comment.author?.email ?? "unknown";
7285
- ctx.io.out(` ${comment.createdAt} ${author}: ${comment.body}`);
7522
+ ctx.io.out(` ${comment.createdAt} ${author} #${comment.id}`);
7523
+ ctx.io.out(` ${comment.body}`);
7286
7524
  }
7287
7525
  ctx.io.out("");
7288
7526
  ctx.io.out(`Activity (${task.activityLog.length})`);
@@ -7424,7 +7662,7 @@ async function workspaceUse(ctx, slug) {
7424
7662
  );
7425
7663
  }
7426
7664
 
7427
- // src/index.ts
7665
+ // src/program.ts
7428
7666
  function contextFor(program2, io2) {
7429
7667
  const flags = program2.opts();
7430
7668
  const config = loadConfig({
@@ -7483,8 +7721,8 @@ function buildProgram(io2) {
7483
7721
  status: options.status
7484
7722
  });
7485
7723
  });
7486
- const comment = program2.command("comment").description("Task comments");
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(
7724
+ const comment = program2.command("comment").description("Task and project comments");
7725
+ comment.command("add").argument("<taskRefOrBody>", "task identifier or id, or the body with --project").argument("[body]", "comment body, when a task was given").description("Add a comment to a task or a project").usage("[options] <taskRef> <body>\n tasq comment add [options] --project <projectRef> <body>").option("--project <projectRef>", "project id or name, instead of a task").option("--reply-to <commentRef>", "comment id, or ENG-42#<id>, to reply to").option("--thread <threadId>", "thread root id, an alias for --reply-to").option(
7488
7726
  "--mention <agentName>",
7489
7727
  "agent to mention, repeatable",
7490
7728
  (value, previous) => [
@@ -7492,10 +7730,22 @@ function buildProgram(io2) {
7492
7730
  value
7493
7731
  ]
7494
7732
  ).action(
7495
- async (taskId, body, options) => {
7496
- await commentAdd(contextFor(program2, io2), taskId, body, options);
7733
+ async (taskRefOrBody, maybeBody, options) => {
7734
+ const { taskRef, body } = commentPositionals(
7735
+ taskRefOrBody,
7736
+ maybeBody,
7737
+ options.project
7738
+ );
7739
+ await commentAdd(contextFor(program2, io2), taskRef, body, options);
7497
7740
  }
7498
7741
  );
7742
+ const thread = program2.command("thread").description("Conversations on a task or a project");
7743
+ thread.command("view").argument("<threadId>", "thread root comment id").description("Show a thread with its message ids").action(async (threadId) => {
7744
+ await threadView(contextFor(program2, io2), threadId);
7745
+ });
7746
+ thread.command("context").argument("<threadId>", "thread root comment id").description("Print the thread's context bundle as a Markdown prompt").option("--markdown", "render Markdown (the default)").action(async (threadId, options) => {
7747
+ await threadContext(contextFor(program2, io2), threadId, options);
7748
+ });
7499
7749
  const events = program2.command("events").description("Mentions addressed to this agent");
7500
7750
  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
7751
  const controller = new AbortController();
@@ -7532,6 +7782,8 @@ function buildProgram(io2) {
7532
7782
  auth.command("whoami").description("Show the current principal").action(run((ctx) => authWhoami(ctx)));
7533
7783
  return program2;
7534
7784
  }
7785
+
7786
+ // src/index.ts
7535
7787
  async function main(argv, io2) {
7536
7788
  try {
7537
7789
  await buildProgram(io2).parseAsync(argv, { from: "user" });
@@ -21,7 +21,21 @@
21
21
  #
22
22
  # Exported per event:
23
23
  # TASQ_EVENT_ID, TASQ_EVENT_KIND, TASQ_EVENT_TASK_KEY, TASQ_EVENT_TASK_ID,
24
- # TASQ_EVENT_COMMENT_ID, TASQ_EVENT_MENTIONED_BY
24
+ # TASQ_EVENT_PROJECT_ID, TASQ_EVENT_THREAD_ID, TASQ_EVENT_COMMENT_ID,
25
+ # TASQ_EVENT_MENTIONED_BY, TASQ_EVENT_MENTIONED_BY_TYPE
26
+ #
27
+ # Event kinds: `mention` is a request addressed to the agent; `thread_message`
28
+ # is a follow-up in a thread it already joined. An unrecognised kind is acked
29
+ # and skipped rather than handed to a command that was never written for it.
30
+ #
31
+ # On a team whose admin has turned agent isolation off, an author can be
32
+ # another agent: `mentionedBy.type` is `agent` rather than `user`. This runner
33
+ # takes an agent's `mention` as a real request — it names us — but acks an
34
+ # agent's `thread_message` without invoking the harness, because answering
35
+ # every agent turn is how two agents talk to each other forever. Tasq stops
36
+ # waking agents after five agent messages in a row in a thread and never wakes
37
+ # more than ten from one message, but the cheapest loop is the one that never
38
+ # starts. Change this if your agents are meant to converse.
25
39
  #
26
40
  # Acking is deliberate: an event the command failed on is left unacked, and
27
41
  # Tasq offers it again ten minutes later. A crash loses no work.
@@ -56,32 +70,66 @@ fi
56
70
  TASQ_EVENT_KIND="$(field "$event" kind)"
57
71
  TASQ_EVENT_TASK_KEY="$(field "$event" taskKey)"
58
72
  TASQ_EVENT_TASK_ID="$(field "$event" taskId)"
73
+ TASQ_EVENT_PROJECT_ID="$(field "$event" projectId)"
74
+ TASQ_EVENT_THREAD_ID="$(field "$event" threadId)"
59
75
  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
- })"
76
+ # `mentionedBy` is an object, so it needs its own reader rather than `field`.
77
+ mentioned_by() {
78
+ printf '%s' "$1" | {
79
+ if command -v jq > /dev/null 2>&1; then
80
+ jq -r --arg f "$2" '.mentionedBy[$f] // empty'
81
+ else
82
+ node -e '
83
+ let raw = ""
84
+ process.stdin.on("data", (chunk) => { raw += chunk })
85
+ process.stdin.on("end", () => {
86
+ const by = JSON.parse(raw).mentionedBy
87
+ const value = by == null ? null : by[process.argv[1]]
88
+ process.stdout.write(value == null ? "" : String(value))
89
+ })
90
+ ' "$2"
91
+ fi
92
+ }
93
+ }
94
+
95
+ TASQ_EVENT_MENTIONED_BY="$(mentioned_by "$event" name)"
96
+ TASQ_EVENT_MENTIONED_BY_TYPE="$(mentioned_by "$event" type)"
74
97
 
75
98
  export TASQ_EVENT_ID TASQ_EVENT_KIND TASQ_EVENT_TASK_KEY \
76
- TASQ_EVENT_TASK_ID TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY
99
+ TASQ_EVENT_TASK_ID TASQ_EVENT_PROJECT_ID TASQ_EVENT_THREAD_ID \
100
+ TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY \
101
+ TASQ_EVENT_MENTIONED_BY_TYPE
102
+
103
+ TASQ_EVENT_ENTITY="${TASQ_EVENT_TASK_KEY:-${TASQ_EVENT_PROJECT_ID:-?}}"
104
+
105
+ echo "→ ${TASQ_EVENT_KIND} on ${TASQ_EVENT_ENTITY} (${TASQ_EVENT_ID})" >&2
106
+
107
+ case "$TASQ_EVENT_KIND" in
108
+ mention | thread_message)
109
+ # An agent's follow-up in a thread is context, not a request: ack it and
110
+ # move on. An agent's `mention` still names us, so it is handled below.
111
+ if [[ "$TASQ_EVENT_MENTIONED_BY_TYPE" == "agent" \
112
+ && "$TASQ_EVENT_KIND" == "thread_message" ]]; then
113
+ echo " thread message from agent ${TASQ_EVENT_MENTIONED_BY:-?}; context only, skipping" >&2
114
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
77
115
 
78
- echo "→ ${TASQ_EVENT_KIND} on ${TASQ_EVENT_TASK_KEY:-?} (${TASQ_EVENT_ID})" >&2
116
+ continue
117
+ fi
79
118
 
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
119
+ # `set -e` must not kill the loop on a handler failure: the whole point
120
+ # is to leave that event unacked and keep listening.
121
+ if sh -c "$TASQ_AGENT_CMD"; then
122
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
123
+ else
124
+ echo " handler failed; leaving ${TASQ_EVENT_ID} unacked for redelivery" >&2
125
+ fi
126
+ ;;
127
+ *)
128
+ # A kind this runner predates. Acking clears it from the queue rather
129
+ # than letting Tasq redeliver it every ten minutes forever; teach the
130
+ # case above about it before the handler can do anything useful with it.
131
+ echo " unknown event kind \"${TASQ_EVENT_KIND}\"; acking and skipping" >&2
132
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
133
+ ;;
134
+ esac
87
135
  done
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pxlabz/tasq-cli",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "Command-line client for Tasq, for humans and agents alike",
5
5
  "keywords": [
6
6
  "tasq",