@pxlabz/tasq-cli 0.1.3 → 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, 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, exit codes, and working alongside other agents.
4
4
  ---
5
5
 
6
6
  # Tasq
@@ -76,7 +76,7 @@ A comment goes on a task or a project, never both and never neither: give the ta
76
76
 
77
77
  ## When you are mentioned
78
78
 
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.
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.
80
80
 
81
81
  The loop is:
82
82
 
@@ -97,7 +97,7 @@ A thread is a root message and its replies, on a task or on a project. Its id
97
97
  Two event kinds reach you, and they mean different things:
98
98
 
99
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.
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
101
 
102
102
  Start from the context bundle rather than guessing which entity the thread is on:
103
103
 
@@ -118,7 +118,7 @@ tasq comment add --project <projectName> "…" --thread <threadId>
118
118
 
119
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
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.
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
122
 
123
123
  ## Exit codes
124
124
 
@@ -130,6 +130,12 @@ Isolation still holds inside a thread: another agent's messages never reach you,
130
130
  | 3 | Rate limited; the message says when to retry. `events listen` never exits here — it waits and continues |
131
131
  | 4 | Your policy denied the action. Do not retry it; say what was refused |
132
132
 
133
- ## Isolation
133
+ ## Working with other agents
134
134
 
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.
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.
140
+
141
+ Projects shared with a team that kept isolation stay isolated.
package/dist/tasq.js CHANGED
@@ -6638,7 +6638,17 @@ var TasqClient = class _TasqClient {
6638
6638
  /** The only read that carries a team's statuses. */
6639
6639
  get: async (slug, identifier) => (await this.#get(
6640
6640
  `/workspaces/${encodeURIComponent(slug)}/teams/${encodeURIComponent(identifier)}`
6641
- )).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
+ )
6642
6652
  };
6643
6653
  labels = {
6644
6654
  list: async (slug) => (await this.#get(
@@ -6708,6 +6718,10 @@ var TasqClient = class _TasqClient {
6708
6718
  }
6709
6719
  };
6710
6720
 
6721
+ // ../sdk/src/types.ts
6722
+ var MAX_AGENT_WAKES_PER_MESSAGE = 10;
6723
+ var MAX_CONSECUTIVE_AGENT_MESSAGES = 5;
6724
+
6711
6725
  // src/errors.ts
6712
6726
  var EXIT_OK = 0;
6713
6727
  var EXIT_ERROR = 1;
@@ -6769,7 +6783,7 @@ function reportError(error, io2) {
6769
6783
  // package.json
6770
6784
  var package_default = {
6771
6785
  name: "@pxlabz/tasq-cli",
6772
- version: "0.1.3",
6786
+ version: "0.1.4",
6773
6787
  description: "Command-line client for Tasq, for humans and agents alike",
6774
6788
  keywords: [
6775
6789
  "tasq",
@@ -7127,9 +7141,44 @@ function resolveMentions(members, names) {
7127
7141
  return matched[0]?.agentId ?? "";
7128
7142
  });
7129
7143
  }
7130
- 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) {
7131
7157
  const who = name ?? "an agent";
7132
- 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}`;
7161
+ }
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}`;
7133
7182
  }
7134
7183
  async function resolveProjectId(ctx, slug, ref) {
7135
7184
  const trimmed = ref.trim();
@@ -7210,8 +7259,10 @@ async function commentAdd(ctx, taskRef, body, options = {}) {
7210
7259
  members.map((member) => [member.agentId, member.name])
7211
7260
  );
7212
7261
  for (const mention of added.result.mentions ?? []) {
7213
- ctx.io.out(mentionLine(mention.state, nameById.get(mention.agentId)));
7262
+ ctx.io.out(mentionLine(mention, nameById.get(mention.agentId)));
7214
7263
  }
7264
+ const threadMessages = added.result.threadMessages ?? [];
7265
+ if (threadMessages.length > 0) ctx.io.out(threadLine(threadMessages));
7215
7266
  }
7216
7267
 
7217
7268
  // src/commands/cycle.ts
@@ -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
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.4",
4
4
  "description": "Command-line client for Tasq, for humans and agents alike",
5
5
  "keywords": [
6
6
  "tasq",