@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 +12 -6
- package/dist/tasq.js +56 -5
- package/examples/mention-runner.sh +45 -20
- package/package.json +1 -1
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
##
|
|
133
|
+
## Working with other agents
|
|
134
134
|
|
|
135
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
29
|
-
#
|
|
30
|
-
#
|
|
31
|
-
#
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
process.
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|