@pxlabz/tasq-cli 0.1.3 → 0.1.5

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, 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.
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, release narratives, exit codes, and working alongside other agents.
4
4
  ---
5
5
 
6
6
  # Tasq
@@ -61,6 +61,13 @@ tasq events ack <id>…
61
61
  tasq project list
62
62
  tasq cycle current [--team <identifier>]
63
63
 
64
+ tasq release list [--team <identifier>]
65
+ tasq release view <releaseId>
66
+ tasq release context <releaseId> [--markdown]
67
+ tasq release diff <releaseId>
68
+ tasq release export <releaseId> [--out <file>]
69
+ tasq release narrate <releaseId> (--body <markdown> | --file <path>)
70
+
64
71
  tasq auth login [--email <email>]
65
72
  tasq auth logout
66
73
  tasq auth whoami
@@ -76,7 +83,7 @@ A comment goes on a task or a project, never both and never neither: give the ta
76
83
 
77
84
  ## When you are mentioned
78
85
 
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.
86
+ `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, releaseId, mentionedBy, deliveryCount, createdAt }`. `kind` is `mention`, `thread_message` or `cycle_closed`; on the first two exactly one of `taskId` and `projectId` is set, and `mentionedBy` carries `{ memberId, type, name }` whose `type` is `user` or `agent`. On a `cycle_closed` every one of those is null and only `releaseId` is set — see **Release narratives**. 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.
80
87
 
81
88
  The loop is:
82
89
 
@@ -97,7 +104,7 @@ A thread is a root message and its replies, on a task or on a project. Its id
97
104
  Two event kinds reach you, and they mean different things:
98
105
 
99
106
  - **`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.
107
+ - **`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
108
 
102
109
  Start from the context bundle rather than guessing which entity the thread is on:
103
110
 
@@ -118,7 +125,29 @@ tasq comment add --project <projectName> "…" --thread <threadId>
118
125
 
119
126
  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
127
 
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.
128
+ 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.
129
+
130
+ ## Release narratives
131
+
132
+ When a cycle closes, Tasq writes a **release**: the number, the dates, and every task in the cycle classified as shipped, carried over or dropped, with the ones that arrived mid-cycle marked. It writes that row itself, from the close snapshot, whether or not any agent is connected. The **narrative** is the Markdown body attached to it afterwards, and that is the part you write.
133
+
134
+ If you are set as a team's release narrator, each close sends you one `cycle_closed` event. It is the only event kind that carries a `releaseId`, and it carries nothing else: `taskId`, `taskKey`, `projectId`, `threadId`, `commentId` and `mentionedBy` are all null, because a cycle close is not somebody talking to you. The `releaseId` is the whole payload.
135
+
136
+ The loop is:
137
+
138
+ 1. **Listen.** `tasq events listen --wait 20`, the same listener as for mentions. Filter on `kind == "cycle_closed"` and read `.releaseId`.
139
+ 2. **Read the release.** `tasq release context <releaseId>` prints a Markdown prompt: the cycle and its dates, the shipped / carried over / dropped lists, the change against the previous release, and the previous narrative. `--json` gives the same bundle raw. Each task list is capped at 100; a cut list says so.
140
+ 3. **Write it.** Prose about what the cycle did, for the people who were not in it. The diff and the counts are already on the page — do not just restate them.
141
+ 4. **Save it.** `tasq release narrate <releaseId> --file notes.md`, or `--body "…"` for a short one, or pipe the body in with neither flag. The cap is 50,000 characters.
142
+ 5. **Acknowledge.** `tasq events ack <eventId>`, last, as always.
143
+
144
+ Three things to know before you write:
145
+
146
+ - **The release already exists.** Nothing waits on you. If you never answer, the release stands with an empty narrative and the team still sees what shipped.
147
+ - **It is one field, last write wins.** There is no thread and no version history: `release narrate` replaces whatever is there. A person may have written or edited it in the web app before you ran, and a person may replace yours afterwards. Your name and the time are shown next to it either way, so read the release before overwriting a narrative that is already good.
148
+ - **It is not a thread event.** Isolation and the loop caps govern agents waking agents in conversations; a cycle close is Tasq waking one agent. Neither applies, and your narrative wakes nobody.
149
+
150
+ `tasq release list --team ENG` is the timeline, newest first; `tasq release view <releaseId>` shows one in full; `tasq release export <releaseId>` prints it as Markdown for a changelog. `examples/release-narrator.sh` in this package is a working reference for the loop above, minus the writing.
122
151
 
123
152
  ## Exit codes
124
153
 
@@ -130,6 +159,12 @@ Isolation still holds inside a thread: another agent's messages never reach you,
130
159
  | 3 | Rate limited; the message says when to retry. `events listen` never exits here — it waits and continues |
131
160
  | 4 | Your policy denied the action. Do not retry it; say what was refused |
132
161
 
133
- ## Isolation
162
+ ## Working with other agents
163
+
164
+ 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.
165
+
166
+ 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.
167
+
168
+ 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.
134
169
 
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.
170
+ Projects shared with a team that kept isolation stay isolated.
package/dist/tasq.js CHANGED
@@ -6570,6 +6570,30 @@ var TasqClient = class _TasqClient {
6570
6570
  }
6571
6571
  return await response.json();
6572
6572
  }
6573
+ /**
6574
+ * A read whose body is Markdown rather than JSON.
6575
+ *
6576
+ * The export and the `format=markdown` context are documents, not
6577
+ * envelopes, so they are read as text. Errors still arrive as the JSON
6578
+ * envelope every other route uses, so the failure path is `#toError`'s,
6579
+ * unchanged.
6580
+ */
6581
+ async #text(path, params, options) {
6582
+ const headers = new Headers({ accept: "text/markdown" });
6583
+ if (this.#token === void 0) throw noCredentialError();
6584
+ headers.set("authorization", `Bearer ${this.#token}`);
6585
+ const timeout = options?.timeoutMs === void 0 ? void 0 : AbortSignal.timeout(options.timeoutMs);
6586
+ const signals = [options?.signal, timeout].filter(
6587
+ (candidate) => candidate != null
6588
+ );
6589
+ const signal = signals.length === 0 ? void 0 : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
6590
+ const response = await this.#fetch(
6591
+ `${this.#baseUrl}${path}${queryString(params)}`,
6592
+ { headers, signal }
6593
+ );
6594
+ if (!response.ok) throw await this.#toError(response);
6595
+ return await response.text();
6596
+ }
6573
6597
  async #toError(response) {
6574
6598
  const retryAfter = response.headers.get("retry-after");
6575
6599
  const fallback = {
@@ -6638,7 +6662,17 @@ var TasqClient = class _TasqClient {
6638
6662
  /** The only read that carries a team's statuses. */
6639
6663
  get: async (slug, identifier) => (await this.#get(
6640
6664
  `/workspaces/${encodeURIComponent(slug)}/teams/${encodeURIComponent(identifier)}`
6641
- )).team
6665
+ )).team,
6666
+ /**
6667
+ * Whether agents on this team may wake each other, plus the loop and
6668
+ * fan-out limits that stand behind the open setting (B-04c D-1).
6669
+ *
6670
+ * Read-only here on purpose: saving the setting is admin-only and web-only
6671
+ * (D-8), so no agent key can reach it.
6672
+ */
6673
+ agentSettings: (slug, identifier) => this.#get(
6674
+ `/workspaces/${encodeURIComponent(slug)}/teams/${encodeURIComponent(identifier)}/agent-settings`
6675
+ )
6642
6676
  };
6643
6677
  labels = {
6644
6678
  list: async (slug) => (await this.#get(
@@ -6666,6 +6700,43 @@ var TasqClient = class _TasqClient {
6666
6700
  options
6667
6701
  )
6668
6702
  };
6703
+ /**
6704
+ * Releases: the structural record of a cycle close, and the narrative an
6705
+ * agent or a person attaches to it (B-04d).
6706
+ *
6707
+ * Reads are authorized by the workspace role guard rather than a policy
6708
+ * action, so a read-only agent may pull the context it needs; the write
6709
+ * goes through `release.saveNarrative` like every other action.
6710
+ */
6711
+ releases = {
6712
+ list: async (slug, teamIdentifier) => (await this.#get(
6713
+ `/workspaces/${encodeURIComponent(slug)}/releases`,
6714
+ { team: teamIdentifier }
6715
+ )).releases,
6716
+ get: async (slug, releaseId) => (await this.#get(
6717
+ `/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}`
6718
+ )).release,
6719
+ /**
6720
+ * The context bundle a narrator writes from.
6721
+ *
6722
+ * `format: "markdown"` returns the server-rendered prompt as a string,
6723
+ * which is what a harness pastes into a model; the default returns the
6724
+ * bundle, for a runner that branches on the fields itself.
6725
+ */
6726
+ context: ((slug, releaseId, options = {}) => {
6727
+ const path = `/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}/context`;
6728
+ return options.format === "markdown" ? this.#text(path, { format: "markdown" }, options) : this.#get(path, void 0, options);
6729
+ }),
6730
+ diff: async (slug, releaseId) => (await this.#get(
6731
+ `/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}/diff`
6732
+ )).diff,
6733
+ /** The release as a Markdown document, the same body the web export serves. */
6734
+ export: (slug, releaseId) => this.#text(
6735
+ `/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}/export`
6736
+ ),
6737
+ /** Last write wins; the author and timestamp move with the body (D-3). */
6738
+ saveNarrative: (slug, input) => this.dispatch("release.saveNarrative", slug, input)
6739
+ };
6669
6740
  members = {
6670
6741
  list: async (slug) => (await this.#get(
6671
6742
  `/workspaces/${encodeURIComponent(slug)}/members`
@@ -6708,6 +6779,11 @@ var TasqClient = class _TasqClient {
6708
6779
  }
6709
6780
  };
6710
6781
 
6782
+ // ../sdk/src/types.ts
6783
+ var MAX_AGENT_WAKES_PER_MESSAGE = 10;
6784
+ var MAX_CONSECUTIVE_AGENT_MESSAGES = 5;
6785
+ var RELEASE_NARRATIVE_MAX = 5e4;
6786
+
6711
6787
  // src/errors.ts
6712
6788
  var EXIT_OK = 0;
6713
6789
  var EXIT_ERROR = 1;
@@ -6769,7 +6845,7 @@ function reportError(error, io2) {
6769
6845
  // package.json
6770
6846
  var package_default = {
6771
6847
  name: "@pxlabz/tasq-cli",
6772
- version: "0.1.3",
6848
+ version: "0.1.5",
6773
6849
  description: "Command-line client for Tasq, for humans and agents alike",
6774
6850
  keywords: [
6775
6851
  "tasq",
@@ -6962,6 +7038,21 @@ function formatCycles(cycles) {
6962
7038
  ])
6963
7039
  );
6964
7040
  }
7041
+ function formatReleases(releases) {
7042
+ if (releases.length === 0) return "No releases.";
7043
+ return table(
7044
+ ["#", "Cycle", "Closed", "Shipped", "Carried", "Dropped", "Narrative by"],
7045
+ releases.map((release) => [
7046
+ String(release.number),
7047
+ dash(release.cycleName),
7048
+ release.closedAt.slice(0, 10),
7049
+ String(release.counts.shipped),
7050
+ String(release.counts.carriedOver),
7051
+ String(release.counts.dropped),
7052
+ dash(release.narrativeAuthor?.name)
7053
+ ])
7054
+ );
7055
+ }
6965
7056
  function formatWorkspaces(workspaces) {
6966
7057
  if (workspaces.length === 0) return "No workspaces.";
6967
7058
  return table(
@@ -7127,9 +7218,44 @@ function resolveMentions(members, names) {
7127
7218
  return matched[0]?.agentId ?? "";
7128
7219
  });
7129
7220
  }
7130
- function mentionLine(state, name) {
7221
+ function reasonPhrase(reason) {
7222
+ switch (reason) {
7223
+ case "isolation":
7224
+ return "agents are isolated on this team";
7225
+ case "loop_cap":
7226
+ return `loop stopped after ${MAX_CONSECUTIVE_AGENT_MESSAGES} agent messages in a row; waiting for a person`;
7227
+ case "fanout_cap":
7228
+ return `fan-out cap of ${MAX_AGENT_WAKES_PER_MESSAGE} reached`;
7229
+ default:
7230
+ return null;
7231
+ }
7232
+ }
7233
+ function mentionLine(outcome, name) {
7131
7234
  const who = name ?? "an agent";
7132
- return state === "suppressed" ? `${who}: suppressed: agents are isolated` : `delivered to ${who}`;
7235
+ if (outcome.state !== "suppressed") return `delivered to ${who}`;
7236
+ const phrase = reasonPhrase(outcome.reason);
7237
+ return phrase === null ? `${who}: suppressed` : `${who}: suppressed: ${phrase}`;
7238
+ }
7239
+ function agentCount(count) {
7240
+ return count === 1 ? "1 agent" : `${count} agents`;
7241
+ }
7242
+ function threadLine(outcomes) {
7243
+ const delivered = outcomes.filter(
7244
+ (outcome) => outcome.state !== "suppressed"
7245
+ ).length;
7246
+ const suppressed = outcomes.length - delivered;
7247
+ if (suppressed === 0) return `thread: delivered to ${agentCount(delivered)}`;
7248
+ const phrases = [
7249
+ ...new Set(
7250
+ outcomes.flatMap((outcome) => {
7251
+ if (outcome.state !== "suppressed") return [];
7252
+ const phrase = reasonPhrase(outcome.reason);
7253
+ return phrase === null ? [] : [phrase];
7254
+ })
7255
+ )
7256
+ ];
7257
+ const why = phrases.length === 0 ? "" : ` (${phrases.join("; ")})`;
7258
+ return `thread: delivered to ${agentCount(delivered)}, ${suppressed} suppressed${why}`;
7133
7259
  }
7134
7260
  async function resolveProjectId(ctx, slug, ref) {
7135
7261
  const trimmed = ref.trim();
@@ -7210,8 +7336,10 @@ async function commentAdd(ctx, taskRef, body, options = {}) {
7210
7336
  members.map((member) => [member.agentId, member.name])
7211
7337
  );
7212
7338
  for (const mention of added.result.mentions ?? []) {
7213
- ctx.io.out(mentionLine(mention.state, nameById.get(mention.agentId)));
7339
+ ctx.io.out(mentionLine(mention, nameById.get(mention.agentId)));
7214
7340
  }
7341
+ const threadMessages = added.result.threadMessages ?? [];
7342
+ if (threadMessages.length > 0) ctx.io.out(threadLine(threadMessages));
7215
7343
  }
7216
7344
 
7217
7345
  // src/commands/cycle.ts
@@ -7292,6 +7420,140 @@ async function projectList(ctx) {
7292
7420
  ctx.io.out(ctx.config.json ? jsonOutput(projects) : formatProjects(projects));
7293
7421
  }
7294
7422
 
7423
+ // src/commands/release.ts
7424
+ import { writeFileSync as writeFileSync2 } from "fs";
7425
+ import { readFileSync as readFileSync2 } from "fs";
7426
+ async function releaseList(ctx, options) {
7427
+ const slug = requireWorkspace(ctx.config);
7428
+ const releases = await ctx.client.releases.list(slug, options.team);
7429
+ ctx.io.out(ctx.config.json ? jsonOutput(releases) : formatReleases(releases));
7430
+ }
7431
+ function taskLine(task) {
7432
+ const suffix = task.addedMidCycle ? " (added mid-cycle)" : "";
7433
+ return ` ${task.taskIdentifier} \u2014 ${task.title}${suffix}`;
7434
+ }
7435
+ function taskList(io2, heading, tasks) {
7436
+ io2.out(`${heading} (${tasks.length})`);
7437
+ if (tasks.length === 0) {
7438
+ io2.out(" \u2014");
7439
+ } else {
7440
+ for (const task of tasks) io2.out(taskLine(task));
7441
+ }
7442
+ io2.out("");
7443
+ }
7444
+ function countsLine(release) {
7445
+ const { shipped, carriedOver, dropped, addedMidCycle } = release.counts;
7446
+ return `Shipped ${shipped} \xB7 carried over ${carriedOver} \xB7 dropped ${dropped} \xB7 added mid-cycle ${addedMidCycle}`;
7447
+ }
7448
+ async function releaseView(ctx, releaseId) {
7449
+ const slug = requireWorkspace(ctx.config);
7450
+ const release = await ctx.client.releases.get(slug, releaseId);
7451
+ if (ctx.config.json) {
7452
+ ctx.io.out(jsonOutput(release));
7453
+ return;
7454
+ }
7455
+ ctx.io.out(`${release.teamIdentifier} \u2014 Release ${release.number}`);
7456
+ ctx.io.out(`${release.cycleName ?? "unnamed cycle"} closed ${release.closedAt}`);
7457
+ ctx.io.out(countsLine(release));
7458
+ ctx.io.out("");
7459
+ const author = release.narrativeAuthor;
7460
+ ctx.io.out(
7461
+ author === null ? "Narrative" : `Narrative \u2014 ${author.name ?? "unknown"} (${author.type ?? "unknown"}, ${author.updatedAt})`
7462
+ );
7463
+ ctx.io.out("");
7464
+ ctx.io.out(release.narrative ?? "_No narrative yet._");
7465
+ ctx.io.out("");
7466
+ const by = (disposition) => release.tasks.filter((task) => task.disposition === disposition);
7467
+ taskList(ctx.io, "Shipped", by("shipped"));
7468
+ taskList(ctx.io, "Carried over", by("carried_over"));
7469
+ taskList(ctx.io, "Dropped", by("dropped"));
7470
+ }
7471
+ async function releaseContext(ctx, releaseId, _options = {}) {
7472
+ const slug = requireWorkspace(ctx.config);
7473
+ if (ctx.config.json) {
7474
+ const bundle = await ctx.client.releases.context(slug, releaseId);
7475
+ ctx.io.out(jsonOutput(bundle));
7476
+ return;
7477
+ }
7478
+ ctx.io.out(
7479
+ await ctx.client.releases.context(slug, releaseId, {
7480
+ format: "markdown"
7481
+ })
7482
+ );
7483
+ }
7484
+ function diffList(io2, heading, tasks) {
7485
+ taskList(io2, heading, tasks);
7486
+ }
7487
+ async function releaseDiff(ctx, releaseId) {
7488
+ const slug = requireWorkspace(ctx.config);
7489
+ const diff = await ctx.client.releases.diff(slug, releaseId);
7490
+ if (ctx.config.json) {
7491
+ ctx.io.out(jsonOutput(diff));
7492
+ return;
7493
+ }
7494
+ ctx.io.out(
7495
+ diff.previousReleaseNumber === null ? "No previous release: this is the first release for this team." : `Compared with release ${diff.previousReleaseNumber}`
7496
+ );
7497
+ ctx.io.out("");
7498
+ diffList(ctx.io, "Added", diff.added);
7499
+ diffList(ctx.io, "Completed", diff.completed);
7500
+ diffList(ctx.io, "Still carried", diff.carried);
7501
+ diffList(ctx.io, "Dropped since", diff.dropped);
7502
+ }
7503
+ async function releaseExport(ctx, releaseId, options, deps = {}) {
7504
+ const slug = requireWorkspace(ctx.config);
7505
+ const markdown = await ctx.client.releases.export(slug, releaseId);
7506
+ if (options.out === void 0) {
7507
+ ctx.io.out(markdown);
7508
+ return;
7509
+ }
7510
+ const write = deps.writeFile ?? ((path, body) => writeFileSync2(path, body));
7511
+ write(options.out, markdown);
7512
+ ctx.io.err(`Wrote ${options.out}`);
7513
+ }
7514
+ async function narrativeBody(options, deps) {
7515
+ if (options.body !== void 0 && options.file !== void 0) {
7516
+ throw new UsageError(
7517
+ "Pass --body or --file, not both. With neither, the body is read from stdin."
7518
+ );
7519
+ }
7520
+ if (options.body !== void 0) return options.body;
7521
+ if (options.file !== void 0) {
7522
+ const read = deps.readFile ?? ((path) => readFileSync2(path, "utf8"));
7523
+ return read(options.file);
7524
+ }
7525
+ const readStdin = deps.readStdin ?? defaultReadStdin;
7526
+ return await readStdin();
7527
+ }
7528
+ async function defaultReadStdin() {
7529
+ const chunks = [];
7530
+ for await (const chunk of process.stdin) chunks.push(chunk);
7531
+ return Buffer.concat(chunks).toString("utf8");
7532
+ }
7533
+ async function releaseNarrate(ctx, releaseId, options, deps = {}) {
7534
+ const slug = requireWorkspace(ctx.config);
7535
+ const narrative = await narrativeBody(options, deps);
7536
+ if (narrative.trim() === "") {
7537
+ throw new UsageError(
7538
+ "The narrative is empty. Pass --body, --file, or pipe the body in."
7539
+ );
7540
+ }
7541
+ if (narrative.length > RELEASE_NARRATIVE_MAX) {
7542
+ throw new UsageError(
7543
+ `The narrative is ${narrative.length} characters; the limit is ${RELEASE_NARRATIVE_MAX}.`
7544
+ );
7545
+ }
7546
+ const { result } = await ctx.client.releases.saveNarrative(slug, {
7547
+ releaseId,
7548
+ narrative
7549
+ });
7550
+ if (ctx.config.json) {
7551
+ ctx.io.out(jsonOutput(result.release));
7552
+ return;
7553
+ }
7554
+ ctx.io.out(`Narrative saved on release ${result.release.number}.`);
7555
+ }
7556
+
7295
7557
  // src/render/thread-context.ts
7296
7558
  function entityHeading(entity) {
7297
7559
  return entity.key === null ? `**${entity.title}**` : `**${entity.key}** \u2014 ${entity.title}`;
@@ -7429,7 +7691,7 @@ function filters(options) {
7429
7691
  );
7430
7692
  return Object.fromEntries(entries);
7431
7693
  }
7432
- async function taskList(ctx, options) {
7694
+ async function taskList2(ctx, options) {
7433
7695
  const slug = requireWorkspace(ctx.config);
7434
7696
  const query = filters(options);
7435
7697
  if (options.status !== void 0) {
@@ -7637,7 +7899,7 @@ function buildProgram(io2) {
7637
7899
  });
7638
7900
  const task = program2.command("task").description("Tasks");
7639
7901
  task.command("list").description("List tasks").option("--team <identifier>", "team identifier").option("--status <name>", "status name").option("--assignee <id>", "assignee member id").option("--priority <priority>", "urgent | high | medium | low | none").option("--project <id>", "project id").option("--cycle <id>", "cycle id").option("-q, --q <text>", "search text").option("--include-archived", "include archived tasks").action(async (options) => {
7640
- await taskList(contextFor(program2, io2), {
7902
+ await taskList2(contextFor(program2, io2), {
7641
7903
  team: options.team,
7642
7904
  status: options.status,
7643
7905
  assignee: options.assignee,
@@ -7719,6 +7981,27 @@ function buildProgram(io2) {
7719
7981
  cycle.command("current").description("Show the active cycle and its tasks").option("--team <identifier>", "team identifier").action(async (options) => {
7720
7982
  await cycleCurrent(contextFor(program2, io2), { team: options.team });
7721
7983
  });
7984
+ const release = program2.command("release").description("Releases: what a closed cycle shipped, and its narrative");
7985
+ release.command("list").description("List releases, newest first").option("--team <identifier>", "team identifier").action(async (options) => {
7986
+ await releaseList(contextFor(program2, io2), { team: options.team });
7987
+ });
7988
+ release.command("view").argument("<releaseId>", "release id").description("Show a release with its narrative and task lists").action(async (releaseId) => {
7989
+ await releaseView(contextFor(program2, io2), releaseId);
7990
+ });
7991
+ release.command("context").argument("<releaseId>", "release id").description("Print the release's context bundle as a Markdown prompt").option("--markdown", "render Markdown (the default)").action(async (releaseId, options) => {
7992
+ await releaseContext(contextFor(program2, io2), releaseId, options);
7993
+ });
7994
+ release.command("diff").argument("<releaseId>", "release id").description("Show the change against the previous release").action(async (releaseId) => {
7995
+ await releaseDiff(contextFor(program2, io2), releaseId);
7996
+ });
7997
+ release.command("export").argument("<releaseId>", "release id").description("Print the release as Markdown").option("--out <file>", "write to a file instead of stdout").action(async (releaseId, options) => {
7998
+ await releaseExport(contextFor(program2, io2), releaseId, options);
7999
+ });
8000
+ release.command("narrate").argument("<releaseId>", "release id").description("Attach a Markdown narrative to a release").usage("[options] <releaseId>\n \u2026 | tasq release narrate <releaseId>").option("--body <markdown>", "the narrative itself").option("--file <path>", "read the narrative from a file").action(
8001
+ async (releaseId, options) => {
8002
+ await releaseNarrate(contextFor(program2, io2), releaseId, options);
8003
+ }
8004
+ );
7722
8005
  const auth = program2.command("auth").description("Authentication");
7723
8006
  auth.command("login").description("Sign in and store a CLI token").option("--email <email>", "email address").action(async (options) => {
7724
8007
  await authLogin(
@@ -22,13 +22,20 @@
22
22
  # Exported per event:
23
23
  # TASQ_EVENT_ID, TASQ_EVENT_KIND, TASQ_EVENT_TASK_KEY, TASQ_EVENT_TASK_ID,
24
24
  # TASQ_EVENT_PROJECT_ID, TASQ_EVENT_THREAD_ID, TASQ_EVENT_COMMENT_ID,
25
- # TASQ_EVENT_MENTIONED_BY
25
+ # TASQ_EVENT_MENTIONED_BY, TASQ_EVENT_MENTIONED_BY_TYPE
26
26
  #
27
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.
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.
32
39
  #
33
40
  # Acking is deliberate: an event the command failed on is left unacked, and
34
41
  # Tasq offers it again ten minutes later. A crash loses no work.
@@ -66,24 +73,32 @@ fi
66
73
  TASQ_EVENT_PROJECT_ID="$(field "$event" projectId)"
67
74
  TASQ_EVENT_THREAD_ID="$(field "$event" threadId)"
68
75
  TASQ_EVENT_COMMENT_ID="$(field "$event" commentId)"
69
- TASQ_EVENT_MENTIONED_BY="$(printf '%s' "$event" | {
70
- if command -v jq > /dev/null 2>&1; then
71
- jq -r '.mentionedBy.name // empty'
72
- else
73
- node -e '
74
- let raw = ""
75
- process.stdin.on("data", (chunk) => { raw += chunk })
76
- process.stdin.on("end", () => {
77
- const by = JSON.parse(raw).mentionedBy
78
- process.stdout.write(by?.name == null ? "" : String(by.name))
79
- })
80
- '
81
- fi
82
- })"
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)"
83
97
 
84
98
  export TASQ_EVENT_ID TASQ_EVENT_KIND TASQ_EVENT_TASK_KEY \
85
99
  TASQ_EVENT_TASK_ID TASQ_EVENT_PROJECT_ID TASQ_EVENT_THREAD_ID \
86
- TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY
100
+ TASQ_EVENT_COMMENT_ID TASQ_EVENT_MENTIONED_BY \
101
+ TASQ_EVENT_MENTIONED_BY_TYPE
87
102
 
88
103
  TASQ_EVENT_ENTITY="${TASQ_EVENT_TASK_KEY:-${TASQ_EVENT_PROJECT_ID:-?}}"
89
104
 
@@ -91,6 +106,16 @@ fi
91
106
 
92
107
  case "$TASQ_EVENT_KIND" in
93
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"
115
+
116
+ continue
117
+ fi
118
+
94
119
  # `set -e` must not kill the loop on a handler failure: the whole point
95
120
  # is to leave that event unacked and keep listening.
96
121
  if sh -c "$TASQ_AGENT_CMD"; then
@@ -0,0 +1,142 @@
1
+ #!/usr/bin/env bash
2
+ # Example release narrator — NOT part of the Tasq product.
3
+ #
4
+ # Tasq writes the release row itself on every cycle close and then sends one
5
+ # `cycle_closed` event to the team's release narrator, if one is set. This
6
+ # script is the smallest honest example of the harness side of that loop: it
7
+ # reads `tasq events listen` line by line, and for each `cycle_closed` it
8
+ # pulls the release context, writes a narrative, saves it, and acks.
9
+ #
10
+ # The narrative it writes is a PLACEHOLDER assembled from the context itself.
11
+ # This script calls no model and has no opinion about what a release means —
12
+ # that is the part you replace. Set TASQ_NARRATOR_CMD to a command that reads
13
+ # the context on stdin and writes the narrative on stdout, and this runner
14
+ # will use it instead.
15
+ #
16
+ # Usage:
17
+ # TASQ_API_KEY=tq_ag_… \
18
+ # TASQ_WORKSPACE=acme \
19
+ # TASQ_NARRATOR_CMD='claude -p "write a release narrative from this context"' \
20
+ # ./release-narrator.sh [--wait 20]
21
+ #
22
+ # Environment:
23
+ # TASQ_NARRATOR_CMD Optional. Command run per release, with the release's
24
+ # Markdown context on stdin; its stdout becomes the
25
+ # narrative. Unset, the placeholder below is used.
26
+ # TASQ_API_KEY The agent key. TASQ_WORKSPACE and TASQ_API_URL are read
27
+ # by the CLI itself; see `tasq --help`.
28
+ #
29
+ # Only `cycle_closed` is handled here. A `mention` or `thread_message` reaching
30
+ # this key is left UNACKED on purpose: it is a conversation, this runner is not
31
+ # one, and Tasq will offer it again in ten minutes to whatever does handle it.
32
+ # Run `mention-runner.sh` beside this one if the same agent does both.
33
+ #
34
+ # Acking is deliberate: an event whose narrate failed is left unacked and comes
35
+ # back in ten minutes. Saving twice is harmless — the narrative is one field
36
+ # with last write wins, so a retry overwrites rather than duplicating.
37
+
38
+ set -euo pipefail
39
+
40
+ TASQ_BIN="${TASQ_BIN:-tasq}"
41
+
42
+ # jq if it is there, a node one-liner if it is not. Both print the field's
43
+ # value, or an empty line when the field is null or missing.
44
+ if command -v jq > /dev/null 2>&1; then
45
+ field() { printf '%s' "$1" | jq -r --arg f "$2" '.[$f] // empty'; }
46
+ else
47
+ field() {
48
+ printf '%s' "$1" | node -e '
49
+ let raw = ""
50
+ process.stdin.on("data", (chunk) => { raw += chunk })
51
+ process.stdin.on("end", () => {
52
+ const value = JSON.parse(raw)[process.argv[1]]
53
+ process.stdout.write(value == null ? "" : String(value))
54
+ })
55
+ ' "$2"
56
+ }
57
+ fi
58
+
59
+ # The placeholder narrative: the context's own counts and shipped list, turned
60
+ # into three lines of prose-shaped text. It exists so the loop can be run end
61
+ # to end without a model attached, and so a reader can see exactly which part
62
+ # of this script is the part that thinks. It is not one.
63
+ placeholder_narrative() {
64
+ local context="$1" summary
65
+
66
+ summary="$(printf '%s' "$context" | grep '^- Shipped ' | head -1)"
67
+
68
+ printf '%s\n' "## Release notes"
69
+ printf '\n'
70
+ printf '%s\n' "${summary:-- No counts in the context.}"
71
+ printf '\n'
72
+ printf '%s\n' "Shipped this cycle:"
73
+ printf '\n'
74
+ # The context's Shipped section, up to the next heading.
75
+ printf '%s' "$context" | awk '
76
+ /^## Shipped$/ { inside = 1; next }
77
+ /^## / { inside = 0 }
78
+ inside && /^- / { print }
79
+ '
80
+ printf '\n'
81
+ printf '%s\n' "_Written by the example narrator, which does not read._"
82
+ }
83
+
84
+ "$TASQ_BIN" events listen "$@" | while IFS= read -r event; do
85
+ [[ -z "$event" ]] && continue
86
+
87
+ TASQ_EVENT_ID="$(field "$event" id)"
88
+ TASQ_EVENT_KIND="$(field "$event" kind)"
89
+ TASQ_EVENT_RELEASE_ID="$(field "$event" releaseId)"
90
+
91
+ if [[ "$TASQ_EVENT_KIND" != "cycle_closed" ]]; then
92
+ echo "→ ${TASQ_EVENT_KIND} (${TASQ_EVENT_ID}); not a release, leaving it unacked" >&2
93
+
94
+ continue
95
+ fi
96
+
97
+ if [[ -z "$TASQ_EVENT_RELEASE_ID" ]]; then
98
+ echo "→ cycle_closed ${TASQ_EVENT_ID} carried no releaseId; acking and skipping" >&2
99
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
100
+
101
+ continue
102
+ fi
103
+
104
+ echo "→ cycle_closed on release ${TASQ_EVENT_RELEASE_ID} (${TASQ_EVENT_ID})" >&2
105
+
106
+ # `set -e` must not kill the loop on a failed read: leave the event unacked
107
+ # and keep listening, the same contract the mention runner keeps.
108
+ if ! context="$("$TASQ_BIN" release context "$TASQ_EVENT_RELEASE_ID")"; then
109
+ echo " could not read the context; leaving ${TASQ_EVENT_ID} unacked" >&2
110
+
111
+ continue
112
+ fi
113
+
114
+ if [[ -n "${TASQ_NARRATOR_CMD:-}" ]]; then
115
+ if ! narrative="$(printf '%s' "$context" | sh -c "$TASQ_NARRATOR_CMD")"; then
116
+ echo " narrator command failed; leaving ${TASQ_EVENT_ID} unacked" >&2
117
+
118
+ continue
119
+ fi
120
+ else
121
+ narrative="$(placeholder_narrative "$context")"
122
+ fi
123
+
124
+ if [[ -z "${narrative//[[:space:]]/}" ]]; then
125
+ echo " the narrative came back empty; leaving ${TASQ_EVENT_ID} unacked" >&2
126
+
127
+ continue
128
+ fi
129
+
130
+ # `--file` rather than `--body`: a narrative is Markdown with newlines in it,
131
+ # and a temporary file keeps it off the argument list and out of `ps`.
132
+ body_file="$(mktemp -t tasq-narrative.XXXXXX)"
133
+ printf '%s' "$narrative" > "$body_file"
134
+
135
+ if "$TASQ_BIN" release narrate "$TASQ_EVENT_RELEASE_ID" --file "$body_file"; then
136
+ "$TASQ_BIN" events ack "$TASQ_EVENT_ID"
137
+ else
138
+ echo " narrate failed; leaving ${TASQ_EVENT_ID} unacked for redelivery" >&2
139
+ fi
140
+
141
+ rm -f "$body_file"
142
+ done
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pxlabz/tasq-cli",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Command-line client for Tasq, for humans and agents alike",
5
5
  "keywords": [
6
6
  "tasq",