@pxlabz/tasq-cli 0.1.2 → 0.1.3

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 the agent isolation rule.
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. 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 human 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 the human 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.
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
+ Isolation still holds inside a thread: another agent's messages never reach you, and yours never wake another agent. If a thread needs work you cannot do, say so in the thread for a person to pick up.
122
+
81
123
  ## Exit codes
82
124
 
83
125
  | Code | Meaning |
@@ -90,4 +132,4 @@ Ack last, deliberately. An unacknowledged event is offered again ten minutes aft
90
132
 
91
133
  ## Isolation
92
134
 
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.
135
+ 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. The same holds for threads: a message you post never produces a `thread_message` event for any other agent participant, and another agent's messages never reach you. Escalate to a person in the thread instead of trying to hand work to another agent.
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`,
@@ -6879,6 +6766,133 @@ function reportError(error, io2) {
6879
6766
  return EXIT_ERROR;
6880
6767
  }
6881
6768
 
6769
+ // package.json
6770
+ var package_default = {
6771
+ name: "@pxlabz/tasq-cli",
6772
+ version: "0.1.3",
6773
+ description: "Command-line client for Tasq, for humans and agents alike",
6774
+ keywords: [
6775
+ "tasq",
6776
+ "cli",
6777
+ "agents",
6778
+ "project-management"
6779
+ ],
6780
+ license: "MIT",
6781
+ author: "Paul Cedrick Artigo",
6782
+ homepage: "https://github.com/pxlabz/tasq/tree/main/packages/cli#readme",
6783
+ repository: {
6784
+ type: "git",
6785
+ url: "git+https://github.com/pxlabz/tasq.git",
6786
+ directory: "packages/cli"
6787
+ },
6788
+ bugs: {
6789
+ url: "https://github.com/pxlabz/tasq/issues"
6790
+ },
6791
+ private: false,
6792
+ type: "module",
6793
+ bin: {
6794
+ tasq: "./dist/tasq.js"
6795
+ },
6796
+ files: [
6797
+ "dist",
6798
+ "examples",
6799
+ ".tasq-skill.md",
6800
+ "README.md",
6801
+ "LICENSE"
6802
+ ],
6803
+ publishConfig: {
6804
+ access: "public"
6805
+ },
6806
+ engines: {
6807
+ node: ">=20.3"
6808
+ },
6809
+ scripts: {
6810
+ build: "tsup && chmod +x dist/tasq.js",
6811
+ typecheck: "tsc --project tsconfig.json --noEmit",
6812
+ lint: "cd ../.. && bun --bun ./node_modules/oxlint/bin/oxlint packages/cli",
6813
+ test: "bun test"
6814
+ },
6815
+ dependencies: {
6816
+ "@clack/prompts": "^0.11.0",
6817
+ "cli-table3": "^0.6.5",
6818
+ commander: "^14.0.0"
6819
+ },
6820
+ devDependencies: {
6821
+ "@pxlabz/tasq-sdk": "workspace:*",
6822
+ "@types/bun": "^1.3.12",
6823
+ tsup: "^8.5.0",
6824
+ typescript: "^5.7.2"
6825
+ }
6826
+ };
6827
+
6828
+ // src/config.ts
6829
+ import {
6830
+ chmodSync,
6831
+ mkdirSync,
6832
+ readFileSync,
6833
+ writeFileSync
6834
+ } from "fs";
6835
+ import { homedir } from "os";
6836
+ import { join } from "path";
6837
+ var DEFAULT_API_URL = "https://tasq.pxlabz.com";
6838
+ function configDir(env) {
6839
+ if (env.TASQ_CONFIG_DIR !== void 0) return env.TASQ_CONFIG_DIR;
6840
+ const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
6841
+ return join(base, "tasq");
6842
+ }
6843
+ function configFilePath(env) {
6844
+ return join(configDir(env), "config.json");
6845
+ }
6846
+ function readStoredConfig(env) {
6847
+ let raw;
6848
+ try {
6849
+ raw = readFileSync(configFilePath(env), "utf8");
6850
+ } catch {
6851
+ return {};
6852
+ }
6853
+ try {
6854
+ const parsed = JSON.parse(raw);
6855
+ return parsed ?? {};
6856
+ } catch {
6857
+ return {};
6858
+ }
6859
+ }
6860
+ function saveConfig(patch, env) {
6861
+ const dir = configDir(env);
6862
+ mkdirSync(dir, { recursive: true, mode: 448 });
6863
+ const merged = { ...readStoredConfig(env), ...patch };
6864
+ for (const key of Object.keys(merged)) {
6865
+ if (merged[key] === void 0) delete merged[key];
6866
+ }
6867
+ const path = configFilePath(env);
6868
+ writeFileSync(path, `${JSON.stringify(merged, null, 2)}
6869
+ `, { mode: 384 });
6870
+ chmodSync(path, 384);
6871
+ }
6872
+ function credentialFrom(env, stored) {
6873
+ if (env.TASQ_API_KEY !== void 0 && env.TASQ_API_KEY !== "") {
6874
+ return { agentKey: env.TASQ_API_KEY };
6875
+ }
6876
+ if (env.TASQ_USER_TOKEN !== void 0 && env.TASQ_USER_TOKEN !== "") {
6877
+ return { userToken: env.TASQ_USER_TOKEN };
6878
+ }
6879
+ if (stored.userToken !== void 0 && stored.userToken !== "") {
6880
+ return { userToken: stored.userToken };
6881
+ }
6882
+ return void 0;
6883
+ }
6884
+ function loadConfig(input) {
6885
+ const { env, flags } = input;
6886
+ const stored = readStoredConfig(env);
6887
+ return {
6888
+ apiUrl: flags.apiUrl ?? env.TASQ_API_URL ?? stored.apiUrl ?? DEFAULT_API_URL,
6889
+ workspace: flags.workspace ?? env.TASQ_WORKSPACE ?? stored.workspace,
6890
+ credential: credentialFrom(env, stored),
6891
+ json: flags.json === true,
6892
+ env
6893
+ };
6894
+ }
6895
+
6882
6896
  // src/context.ts
6883
6897
  function createClient(config) {
6884
6898
  if (config.credential === void 0) {
@@ -7065,20 +7079,32 @@ async function resolveTaskId(client, slug, ref) {
7065
7079
  }
7066
7080
 
7067
7081
  // src/commands/comment.ts
7082
+ 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
7083
  function commentIdOf(ref) {
7069
7084
  const hash = ref.lastIndexOf("#");
7070
7085
  return hash === -1 ? ref.trim() : ref.slice(hash + 1).trim();
7071
7086
  }
7072
- function resolveParentId(task, ref) {
7087
+ function resolveParentId(comments, entityLabel, ref) {
7073
7088
  const id = commentIdOf(ref);
7074
- const found = task.comments.find((comment) => comment.id === id);
7089
+ const found = comments.find((comment) => comment.id === id);
7075
7090
  if (found === void 0) {
7076
7091
  throw new UsageError(
7077
- `"${ref}" is not a comment on ${task.identifier}. Replies must stay in the same task.`
7092
+ `"${ref}" is not a comment on ${entityLabel}. Replies must stay on the same task or project.`
7078
7093
  );
7079
7094
  }
7080
7095
  return found.id;
7081
7096
  }
7097
+ function replyRef(options) {
7098
+ const { replyTo, thread } = options;
7099
+ if (replyTo === void 0) return thread;
7100
+ if (thread === void 0) return replyTo;
7101
+ if (commentIdOf(replyTo) !== commentIdOf(thread)) {
7102
+ throw new UsageError(
7103
+ `--thread "${thread}" and --reply-to "${replyTo}" name different comments. Pass one.`
7104
+ );
7105
+ }
7106
+ return replyTo;
7107
+ }
7082
7108
  function resolveMentions(members, names) {
7083
7109
  const agents = members.filter(
7084
7110
  (member) => member.type === "agent" && member.agentId !== null
@@ -7105,16 +7131,73 @@ function mentionLine(state, name) {
7105
7131
  const who = name ?? "an agent";
7106
7132
  return state === "suppressed" ? `${who}: suppressed: agents are isolated` : `delivered to ${who}`;
7107
7133
  }
7108
- async function commentAdd(ctx, taskRef, body, options = {}) {
7109
- const slug = requireWorkspace(ctx.config);
7134
+ async function resolveProjectId(ctx, slug, ref) {
7135
+ const trimmed = ref.trim();
7136
+ if (UUID_PATTERN2.test(trimmed)) return trimmed;
7137
+ const wanted = trimmed.toLowerCase();
7138
+ const projects = await ctx.client.projects.list(slug);
7139
+ const matched = projects.filter(
7140
+ (project) => project.name.toLowerCase() === wanted
7141
+ );
7142
+ if (matched.length === 0) {
7143
+ throw new UsageError(
7144
+ `No project named "${ref}" in this workspace. Run "tasq project list" to see the names.`
7145
+ );
7146
+ }
7147
+ if (matched.length > 1) {
7148
+ throw new UsageError(
7149
+ `"${ref}" matches ${matched.length} projects. Pass the project id.`
7150
+ );
7151
+ }
7152
+ return matched[0]?.id ?? "";
7153
+ }
7154
+ function commentPositionals(first, second, project) {
7155
+ if (second !== void 0) return { taskRef: first, body: second };
7156
+ if (project === void 0) {
7157
+ throw new UsageError(
7158
+ "Nothing to comment on. Pass a task key such as ENG-42, or --project <id|name>."
7159
+ );
7160
+ }
7161
+ return { taskRef: void 0, body: first };
7162
+ }
7163
+ async function resolveTarget(ctx, slug, taskRef, project) {
7164
+ if (taskRef !== void 0 && project !== void 0) {
7165
+ throw new UsageError(
7166
+ "Pass either a task or --project <id|name>, not both."
7167
+ );
7168
+ }
7169
+ if (project !== void 0) {
7170
+ const projectId = await resolveProjectId(ctx, slug, project);
7171
+ const detail = await ctx.client.projects.get(slug, projectId);
7172
+ return {
7173
+ input: { projectId: detail.id },
7174
+ label: detail.name,
7175
+ comments: detail.comments
7176
+ };
7177
+ }
7178
+ if (taskRef === void 0) {
7179
+ throw new UsageError(
7180
+ "Nothing to comment on. Pass a task key such as ENG-42, or --project <id|name>."
7181
+ );
7182
+ }
7110
7183
  const taskId = await resolveTaskId(ctx.client, slug, taskRef);
7111
7184
  const task = await ctx.client.tasks.get(slug, taskId);
7185
+ return {
7186
+ input: { taskId: task.id },
7187
+ label: task.identifier,
7188
+ comments: task.comments
7189
+ };
7190
+ }
7191
+ async function commentAdd(ctx, taskRef, body, options = {}) {
7192
+ const slug = requireWorkspace(ctx.config);
7193
+ const target = await resolveTarget(ctx, slug, taskRef, options.project);
7112
7194
  const names = options.mention ?? [];
7113
7195
  const members = names.length === 0 ? [] : await ctx.client.members.list(slug);
7114
7196
  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);
7197
+ const input = { ...target.input, body };
7198
+ const parent = replyRef(options);
7199
+ if (parent !== void 0) {
7200
+ input.parentId = resolveParentId(target.comments, target.label, parent);
7118
7201
  }
7119
7202
  if (mentions.length > 0) input.mentions = mentions;
7120
7203
  const added = await ctx.client.dispatch("comment.add", slug, input);
@@ -7122,7 +7205,7 @@ async function commentAdd(ctx, taskRef, body, options = {}) {
7122
7205
  ctx.io.out(jsonOutput(added.result));
7123
7206
  return;
7124
7207
  }
7125
- ctx.io.out(`Comment added to ${task.identifier}.`);
7208
+ ctx.io.out(`Comment added to ${target.label}.`);
7126
7209
  const nameById = new Map(
7127
7210
  members.map((member) => [member.agentId, member.name])
7128
7211
  );
@@ -7209,6 +7292,109 @@ async function projectList(ctx) {
7209
7292
  ctx.io.out(ctx.config.json ? jsonOutput(projects) : formatProjects(projects));
7210
7293
  }
7211
7294
 
7295
+ // src/render/thread-context.ts
7296
+ function entityHeading(entity) {
7297
+ return entity.key === null ? `**${entity.title}**` : `**${entity.key}** \u2014 ${entity.title}`;
7298
+ }
7299
+ function entityFacts(entity) {
7300
+ const facts = [`- Type: ${entity.type}`, `- Status: ${entity.status ?? "\u2014"}`];
7301
+ if (entity.type === "task") {
7302
+ facts.push(`- Project: ${entity.project?.name ?? "\u2014"}`);
7303
+ return facts;
7304
+ }
7305
+ const teams = entity.teams.map((team) => `${team.name} (${team.identifier})`).join(", ");
7306
+ facts.push(`- Teams: ${teams === "" ? "\u2014" : teams}`);
7307
+ return facts;
7308
+ }
7309
+ function entitySection(entity) {
7310
+ const rows = [entityHeading(entity), "", ...entityFacts(entity), ""];
7311
+ rows.push(
7312
+ entity.description === null || entity.description === "" ? "_No description._" : entity.description
7313
+ );
7314
+ if (entity.descriptionTruncated) rows.push("", "_(description truncated)_");
7315
+ return rows.join("\n");
7316
+ }
7317
+ function messageLine(message) {
7318
+ const author = message.authorName ?? "unknown";
7319
+ const type = message.authorType ?? "unknown";
7320
+ return `- **${author}** (${type}, ${message.createdAt}): ${message.body}`;
7321
+ }
7322
+ function threadSection(thread) {
7323
+ const rows = [];
7324
+ if (thread.truncated) {
7325
+ rows.push(
7326
+ `_(showing last ${thread.messages.length} of ${thread.total} messages)_`,
7327
+ ""
7328
+ );
7329
+ }
7330
+ if (thread.messages.length === 0) {
7331
+ rows.push("_none_");
7332
+ return rows.join("\n");
7333
+ }
7334
+ rows.push(...thread.messages.map(messageLine));
7335
+ return rows.join("\n");
7336
+ }
7337
+ function activitySection(activity) {
7338
+ if (activity.length === 0) return "_none_";
7339
+ return activity.map(
7340
+ (entry) => `- ${entry.createdAt} ${entry.actorName ?? "unknown"}: ${entry.summary}`
7341
+ ).join("\n");
7342
+ }
7343
+ function participantsSection(participants) {
7344
+ if (participants.length === 0) return "_none_";
7345
+ return participants.map(
7346
+ (participant) => `- ${participant.name ?? "unknown"} (${participant.type}, joined via ${participant.joinedVia})`
7347
+ ).join("\n");
7348
+ }
7349
+ function renderThreadContext(bundle) {
7350
+ return [
7351
+ "## Entity",
7352
+ "",
7353
+ entitySection(bundle.entity),
7354
+ "",
7355
+ "## Thread",
7356
+ "",
7357
+ threadSection(bundle.thread),
7358
+ "",
7359
+ "## Recent activity",
7360
+ "",
7361
+ activitySection(bundle.recentActivity),
7362
+ "",
7363
+ "## Participants",
7364
+ "",
7365
+ participantsSection(bundle.participants)
7366
+ ].join("\n");
7367
+ }
7368
+
7369
+ // src/commands/thread.ts
7370
+ function entityLine(entity) {
7371
+ const name = entity.key === null ? entity.title : `${entity.key} \xB7 ${entity.title}`;
7372
+ return `${name} (${entity.status ?? "\u2014"})`;
7373
+ }
7374
+ async function threadView(ctx, threadId) {
7375
+ const slug = requireWorkspace(ctx.config);
7376
+ const bundle = await ctx.client.threads.context(slug, threadId);
7377
+ if (ctx.config.json) {
7378
+ ctx.io.out(jsonOutput(bundle));
7379
+ return;
7380
+ }
7381
+ ctx.io.out(entityLine(bundle.entity));
7382
+ ctx.io.out("");
7383
+ ctx.io.out(`Messages (${bundle.thread.total})`);
7384
+ for (const message of bundle.thread.messages) {
7385
+ const author = message.authorName ?? "unknown";
7386
+ ctx.io.out(` ${message.createdAt} ${author} #${message.id}`);
7387
+ ctx.io.out(` ${message.body}`);
7388
+ }
7389
+ }
7390
+ async function threadContext(ctx, threadId, _options = {}) {
7391
+ const slug = requireWorkspace(ctx.config);
7392
+ const bundle = await ctx.client.threads.context(slug, threadId);
7393
+ ctx.io.out(
7394
+ ctx.config.json ? jsonOutput(bundle) : renderThreadContext(bundle)
7395
+ );
7396
+ }
7397
+
7212
7398
  // src/commands/task.ts
7213
7399
  var PRIORITIES = ["urgent", "high", "medium", "low", "none"];
7214
7400
  function priority(value) {
@@ -7282,7 +7468,8 @@ async function taskView(ctx, taskRef) {
7282
7468
  ctx.io.out(`Comments (${task.comments.length})`);
7283
7469
  for (const comment of task.comments) {
7284
7470
  const author = comment.author?.name ?? comment.author?.email ?? "unknown";
7285
- ctx.io.out(` ${comment.createdAt} ${author}: ${comment.body}`);
7471
+ ctx.io.out(` ${comment.createdAt} ${author} #${comment.id}`);
7472
+ ctx.io.out(` ${comment.body}`);
7286
7473
  }
7287
7474
  ctx.io.out("");
7288
7475
  ctx.io.out(`Activity (${task.activityLog.length})`);
@@ -7424,7 +7611,7 @@ async function workspaceUse(ctx, slug) {
7424
7611
  );
7425
7612
  }
7426
7613
 
7427
- // src/index.ts
7614
+ // src/program.ts
7428
7615
  function contextFor(program2, io2) {
7429
7616
  const flags = program2.opts();
7430
7617
  const config = loadConfig({
@@ -7483,8 +7670,8 @@ function buildProgram(io2) {
7483
7670
  status: options.status
7484
7671
  });
7485
7672
  });
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(
7673
+ const comment = program2.command("comment").description("Task and project comments");
7674
+ 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
7675
  "--mention <agentName>",
7489
7676
  "agent to mention, repeatable",
7490
7677
  (value, previous) => [
@@ -7492,10 +7679,22 @@ function buildProgram(io2) {
7492
7679
  value
7493
7680
  ]
7494
7681
  ).action(
7495
- async (taskId, body, options) => {
7496
- await commentAdd(contextFor(program2, io2), taskId, body, options);
7682
+ async (taskRefOrBody, maybeBody, options) => {
7683
+ const { taskRef, body } = commentPositionals(
7684
+ taskRefOrBody,
7685
+ maybeBody,
7686
+ options.project
7687
+ );
7688
+ await commentAdd(contextFor(program2, io2), taskRef, body, options);
7497
7689
  }
7498
7690
  );
7691
+ const thread = program2.command("thread").description("Conversations on a task or a project");
7692
+ thread.command("view").argument("<threadId>", "thread root comment id").description("Show a thread with its message ids").action(async (threadId) => {
7693
+ await threadView(contextFor(program2, io2), threadId);
7694
+ });
7695
+ 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) => {
7696
+ await threadContext(contextFor(program2, io2), threadId, options);
7697
+ });
7499
7698
  const events = program2.command("events").description("Mentions addressed to this agent");
7500
7699
  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
7700
  const controller = new AbortController();
@@ -7532,6 +7731,8 @@ function buildProgram(io2) {
7532
7731
  auth.command("whoami").description("Show the current principal").action(run((ctx) => authWhoami(ctx)));
7533
7732
  return program2;
7534
7733
  }
7734
+
7735
+ // src/index.ts
7535
7736
  async function main(argv, io2) {
7536
7737
  try {
7537
7738
  await buildProgram(io2).parseAsync(argv, { from: "user" });
@@ -21,7 +21,14 @@
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
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. Both are handed to the same
29
+ # command here — deciding whether a follow-up needs a reply is the agent's
30
+ # job, not the runner's. An unrecognised kind is acked and skipped rather than
31
+ # handed to a command that was never written for it.
25
32
  #
26
33
  # Acking is deliberate: an event the command failed on is left unacked, and
27
34
  # Tasq offers it again ten minutes later. A crash loses no work.
@@ -56,6 +63,8 @@ fi
56
63
  TASQ_EVENT_KIND="$(field "$event" kind)"
57
64
  TASQ_EVENT_TASK_KEY="$(field "$event" taskKey)"
58
65
  TASQ_EVENT_TASK_ID="$(field "$event" taskId)"
66
+ TASQ_EVENT_PROJECT_ID="$(field "$event" projectId)"
67
+ TASQ_EVENT_THREAD_ID="$(field "$event" threadId)"
59
68
  TASQ_EVENT_COMMENT_ID="$(field "$event" commentId)"
60
69
  TASQ_EVENT_MENTIONED_BY="$(printf '%s' "$event" | {
61
70
  if command -v jq > /dev/null 2>&1; then
@@ -73,15 +82,29 @@ fi
73
82
  })"
74
83
 
75
84
  export TASQ_EVENT_ID TASQ_EVENT_KIND TASQ_EVENT_TASK_KEY \
76
- TASQ_EVENT_TASK_ID TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY
85
+ TASQ_EVENT_TASK_ID TASQ_EVENT_PROJECT_ID TASQ_EVENT_THREAD_ID \
86
+ TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY
87
+
88
+ TASQ_EVENT_ENTITY="${TASQ_EVENT_TASK_KEY:-${TASQ_EVENT_PROJECT_ID:-?}}"
77
89
 
78
- echo "→ ${TASQ_EVENT_KIND} on ${TASQ_EVENT_TASK_KEY:-?} (${TASQ_EVENT_ID})" >&2
90
+ echo "→ ${TASQ_EVENT_KIND} on ${TASQ_EVENT_ENTITY} (${TASQ_EVENT_ID})" >&2
79
91
 
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
92
+ case "$TASQ_EVENT_KIND" in
93
+ mention | thread_message)
94
+ # `set -e` must not kill the loop on a handler failure: the whole point
95
+ # is to leave that event unacked and keep listening.
96
+ if sh -c "$TASQ_AGENT_CMD"; then
97
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
98
+ else
99
+ echo " handler failed; leaving ${TASQ_EVENT_ID} unacked for redelivery" >&2
100
+ fi
101
+ ;;
102
+ *)
103
+ # A kind this runner predates. Acking clears it from the queue rather
104
+ # than letting Tasq redeliver it every ten minutes forever; teach the
105
+ # case above about it before the handler can do anything useful with it.
106
+ echo " unknown event kind \"${TASQ_EVENT_KIND}\"; acking and skipping" >&2
107
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
108
+ ;;
109
+ esac
87
110
  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.3",
4
4
  "description": "Command-line client for Tasq, for humans and agents alike",
5
5
  "keywords": [
6
6
  "tasq",