tasqmate 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,151 @@
1
+ #!/usr/bin/env bash
2
+ # Example mention runner — NOT part of the Tasqmate product.
3
+ #
4
+ # Tasqmate stores and delivers mentions; it never runs your agent. This script is
5
+ # the smallest honest example of the harness side, which is yours to own: it
6
+ # reads `tasqmate events listen` line by line, hands each event to a command of
7
+ # your choosing through the environment, and acknowledges the event only when
8
+ # that command succeeds. Copy it, rewrite it, or ignore it.
9
+ #
10
+ # Usage:
11
+ # TASQMATE_API_KEY=tq_ag_… \
12
+ # TASQMATE_WORKSPACE=acme \
13
+ # TASQMATE_AGENT_CMD='claude -p "handle $TASQMATE_EVENT_TASK_KEY"' \
14
+ # ./mention-runner.sh [--wait 20]
15
+ #
16
+ # Environment:
17
+ # TASQMATE_AGENT_CMD Required. Shell command run once per event, with the
18
+ # TASQMATE_EVENT_* variables below exported into it.
19
+ # TASQMATE_API_KEY The agent key. TASQMATE_WORKSPACE and TASQMATE_API_URL
20
+ # are read by the CLI itself; see `tasqmate --help`.
21
+ # TASQMATE_BIN The CLI to run (default `tasqmate`).
22
+ #
23
+ # Exported per event:
24
+ # TASQMATE_EVENT_ID, TASQMATE_EVENT_KIND, TASQMATE_EVENT_TASK_KEY,
25
+ # TASQMATE_EVENT_TASK_ID, TASQMATE_EVENT_PROJECT_ID, TASQMATE_EVENT_THREAD_ID,
26
+ # TASQMATE_EVENT_COMMENT_ID, TASQMATE_EVENT_MENTIONED_BY,
27
+ # TASQMATE_EVENT_MENTIONED_BY_TYPE
28
+ #
29
+ # Before the Tasqmate rename these were TASQ_*. The runner still reads
30
+ # TASQ_AGENT_CMD and still exports each TASQ_EVENT_* beside its new name, so a
31
+ # command written for the old names keeps working.
32
+ #
33
+ # Event kinds: `mention` is a request addressed to the agent; `thread_message`
34
+ # is a follow-up in a thread it already joined. An unrecognised kind is acked
35
+ # and skipped rather than handed to a command that was never written for it.
36
+ #
37
+ # On a team whose admin has turned agent isolation off, an author can be
38
+ # another agent: `mentionedBy.type` is `agent` rather than `user`. This runner
39
+ # takes an agent's `mention` as a real request — it names us — but acks an
40
+ # agent's `thread_message` without invoking the harness, because answering
41
+ # every agent turn is how two agents talk to each other forever. Tasqmate stops
42
+ # waking agents after five agent messages in a row in a thread and never wakes
43
+ # more than ten from one message, but the cheapest loop is the one that never
44
+ # starts. Change this if your agents are meant to converse.
45
+ #
46
+ # Acking is deliberate: an event the command failed on is left unacked, and
47
+ # Tasqmate offers it again ten minutes later. A crash loses no work.
48
+
49
+ set -euo pipefail
50
+
51
+ : "${TASQMATE_AGENT_CMD:=${TASQ_AGENT_CMD:-}}"
52
+ : "${TASQMATE_AGENT_CMD:?Set TASQMATE_AGENT_CMD to the command that handles one event}"
53
+
54
+ TASQMATE_BIN="${TASQMATE_BIN:-tasqmate}"
55
+
56
+ # jq if it is there, a node one-liner if it is not. Both print the field's
57
+ # value, or an empty line when the field is null or missing.
58
+ if command -v jq > /dev/null 2>&1; then
59
+ field() { printf '%s' "$1" | jq -r --arg f "$2" '.[$f] // empty'; }
60
+ else
61
+ field() {
62
+ printf '%s' "$1" | node -e '
63
+ let raw = ""
64
+ process.stdin.on("data", (chunk) => { raw += chunk })
65
+ process.stdin.on("end", () => {
66
+ const value = JSON.parse(raw)[process.argv[1]]
67
+ process.stdout.write(value == null ? "" : String(value))
68
+ })
69
+ ' "$2"
70
+ }
71
+ fi
72
+
73
+ "$TASQMATE_BIN" events listen "$@" | while IFS= read -r event; do
74
+ [[ -z "$event" ]] && continue
75
+
76
+ TASQMATE_EVENT_ID="$(field "$event" id)"
77
+ TASQMATE_EVENT_KIND="$(field "$event" kind)"
78
+ TASQMATE_EVENT_TASK_KEY="$(field "$event" taskKey)"
79
+ TASQMATE_EVENT_TASK_ID="$(field "$event" taskId)"
80
+ TASQMATE_EVENT_PROJECT_ID="$(field "$event" projectId)"
81
+ TASQMATE_EVENT_THREAD_ID="$(field "$event" threadId)"
82
+ TASQMATE_EVENT_COMMENT_ID="$(field "$event" commentId)"
83
+ # `mentionedBy` is an object, so it needs its own reader rather than `field`.
84
+ mentioned_by() {
85
+ printf '%s' "$1" | {
86
+ if command -v jq > /dev/null 2>&1; then
87
+ jq -r --arg f "$2" '.mentionedBy[$f] // empty'
88
+ else
89
+ node -e '
90
+ let raw = ""
91
+ process.stdin.on("data", (chunk) => { raw += chunk })
92
+ process.stdin.on("end", () => {
93
+ const by = JSON.parse(raw).mentionedBy
94
+ const value = by == null ? null : by[process.argv[1]]
95
+ process.stdout.write(value == null ? "" : String(value))
96
+ })
97
+ ' "$2"
98
+ fi
99
+ }
100
+ }
101
+
102
+ TASQMATE_EVENT_MENTIONED_BY="$(mentioned_by "$event" name)"
103
+ TASQMATE_EVENT_MENTIONED_BY_TYPE="$(mentioned_by "$event" type)"
104
+
105
+ export TASQMATE_EVENT_ID TASQMATE_EVENT_KIND TASQMATE_EVENT_TASK_KEY \
106
+ TASQMATE_EVENT_TASK_ID TASQMATE_EVENT_PROJECT_ID TASQMATE_EVENT_THREAD_ID \
107
+ TASQMATE_EVENT_COMMENT_ID TASQMATE_EVENT_MENTIONED_BY \
108
+ TASQMATE_EVENT_MENTIONED_BY_TYPE
109
+
110
+ # The same values under their names from before the Tasqmate rename, so an
111
+ # agent command written against TASQ_EVENT_* keeps working.
112
+ export TASQ_EVENT_ID="$TASQMATE_EVENT_ID" TASQ_EVENT_KIND="$TASQMATE_EVENT_KIND" \
113
+ TASQ_EVENT_TASK_KEY="$TASQMATE_EVENT_TASK_KEY" TASQ_EVENT_TASK_ID="$TASQMATE_EVENT_TASK_ID" \
114
+ TASQ_EVENT_PROJECT_ID="$TASQMATE_EVENT_PROJECT_ID" TASQ_EVENT_THREAD_ID="$TASQMATE_EVENT_THREAD_ID" \
115
+ TASQ_EVENT_COMMENT_ID="$TASQMATE_EVENT_COMMENT_ID" \
116
+ TASQ_EVENT_MENTIONED_BY="$TASQMATE_EVENT_MENTIONED_BY" \
117
+ TASQ_EVENT_MENTIONED_BY_TYPE="$TASQMATE_EVENT_MENTIONED_BY_TYPE"
118
+
119
+ TASQMATE_EVENT_ENTITY="${TASQMATE_EVENT_TASK_KEY:-${TASQMATE_EVENT_PROJECT_ID:-?}}"
120
+
121
+ echo "→ ${TASQMATE_EVENT_KIND} on ${TASQMATE_EVENT_ENTITY} (${TASQMATE_EVENT_ID})" >&2
122
+
123
+ case "$TASQMATE_EVENT_KIND" in
124
+ mention | thread_message)
125
+ # An agent's follow-up in a thread is context, not a request: ack it and
126
+ # move on. An agent's `mention` still names us, so it is handled below.
127
+ if [[ "$TASQMATE_EVENT_MENTIONED_BY_TYPE" == "agent" \
128
+ && "$TASQMATE_EVENT_KIND" == "thread_message" ]]; then
129
+ echo " thread message from agent ${TASQMATE_EVENT_MENTIONED_BY:-?}; context only, skipping" >&2
130
+ "$TASQMATE_BIN" events ack "$TASQMATE_EVENT_ID"
131
+
132
+ continue
133
+ fi
134
+
135
+ # `set -e` must not kill the loop on a handler failure: the whole point
136
+ # is to leave that event unacked and keep listening.
137
+ if sh -c "$TASQMATE_AGENT_CMD"; then
138
+ "$TASQMATE_BIN" events ack "$TASQMATE_EVENT_ID"
139
+ else
140
+ echo " handler failed; leaving ${TASQMATE_EVENT_ID} unacked for redelivery" >&2
141
+ fi
142
+ ;;
143
+ *)
144
+ # A kind this runner predates. Acking clears it from the queue rather
145
+ # than letting Tasqmate redeliver it every ten minutes forever; teach the
146
+ # case above about it before the handler can do anything useful with it.
147
+ echo " unknown event kind \"${TASQMATE_EVENT_KIND}\"; acking and skipping" >&2
148
+ "$TASQMATE_BIN" events ack "$TASQMATE_EVENT_ID"
149
+ ;;
150
+ esac
151
+ done
@@ -0,0 +1,147 @@
1
+ #!/usr/bin/env bash
2
+ # Example release narrator — NOT part of the Tasqmate product.
3
+ #
4
+ # Tasqmate 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 `tasqmate 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 TASQMATE_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
+ # TASQMATE_API_KEY=tq_ag_… \
18
+ # TASQMATE_WORKSPACE=acme \
19
+ # TASQMATE_NARRATOR_CMD='claude -p "write a release narrative from this context"' \
20
+ # ./release-narrator.sh [--wait 20]
21
+ #
22
+ # Environment:
23
+ # TASQMATE_NARRATOR_CMD Optional. Command run per release, with the
24
+ # release's Markdown context on stdin; its stdout
25
+ # becomes the narrative. Unset, the placeholder below
26
+ # is used. TASQ_NARRATOR_CMD, its name before the
27
+ # Tasqmate rename, still works.
28
+ # TASQMATE_API_KEY The agent key. TASQMATE_WORKSPACE and
29
+ # TASQMATE_API_URL are read by the CLI itself; see
30
+ # `tasqmate --help`.
31
+ # TASQMATE_BIN The CLI to run (default `tasqmate`).
32
+ #
33
+ # Only `cycle_closed` is handled here. A `mention` or `thread_message` reaching
34
+ # this key is left UNACKED on purpose: it is a conversation, this runner is not
35
+ # one, and Tasqmate will offer it again in ten minutes to whatever does handle it.
36
+ # Run `mention-runner.sh` beside this one if the same agent does both.
37
+ #
38
+ # Acking is deliberate: an event whose narrate failed is left unacked and comes
39
+ # back in ten minutes. Saving twice is harmless — the narrative is one field
40
+ # with last write wins, so a retry overwrites rather than duplicating.
41
+
42
+ set -euo pipefail
43
+
44
+ TASQMATE_BIN="${TASQMATE_BIN:-tasqmate}"
45
+
46
+ # jq if it is there, a node one-liner if it is not. Both print the field's
47
+ # value, or an empty line when the field is null or missing.
48
+ if command -v jq > /dev/null 2>&1; then
49
+ field() { printf '%s' "$1" | jq -r --arg f "$2" '.[$f] // empty'; }
50
+ else
51
+ field() {
52
+ printf '%s' "$1" | node -e '
53
+ let raw = ""
54
+ process.stdin.on("data", (chunk) => { raw += chunk })
55
+ process.stdin.on("end", () => {
56
+ const value = JSON.parse(raw)[process.argv[1]]
57
+ process.stdout.write(value == null ? "" : String(value))
58
+ })
59
+ ' "$2"
60
+ }
61
+ fi
62
+
63
+ # The placeholder narrative: the context's own counts and shipped list, turned
64
+ # into three lines of prose-shaped text. It exists so the loop can be run end
65
+ # to end without a model attached, and so a reader can see exactly which part
66
+ # of this script is the part that thinks. It is not one.
67
+ placeholder_narrative() {
68
+ local context="$1" summary
69
+
70
+ summary="$(printf '%s' "$context" | grep '^- Shipped ' | head -1)"
71
+
72
+ printf '%s\n' "## Release notes"
73
+ printf '\n'
74
+ printf '%s\n' "${summary:-- No counts in the context.}"
75
+ printf '\n'
76
+ printf '%s\n' "Shipped this cycle:"
77
+ printf '\n'
78
+ # The context's Shipped section, up to the next heading.
79
+ printf '%s' "$context" | awk '
80
+ /^## Shipped$/ { inside = 1; next }
81
+ /^## / { inside = 0 }
82
+ inside && /^- / { print }
83
+ '
84
+ printf '\n'
85
+ printf '%s\n' "_Written by the example narrator, which does not read._"
86
+ }
87
+
88
+ "$TASQMATE_BIN" events listen "$@" | while IFS= read -r event; do
89
+ [[ -z "$event" ]] && continue
90
+
91
+ TASQMATE_EVENT_ID="$(field "$event" id)"
92
+ TASQMATE_EVENT_KIND="$(field "$event" kind)"
93
+ TASQMATE_EVENT_RELEASE_ID="$(field "$event" releaseId)"
94
+
95
+ if [[ "$TASQMATE_EVENT_KIND" != "cycle_closed" ]]; then
96
+ echo "→ ${TASQMATE_EVENT_KIND} (${TASQMATE_EVENT_ID}); not a release, leaving it unacked" >&2
97
+
98
+ continue
99
+ fi
100
+
101
+ if [[ -z "$TASQMATE_EVENT_RELEASE_ID" ]]; then
102
+ echo "→ cycle_closed ${TASQMATE_EVENT_ID} carried no releaseId; acking and skipping" >&2
103
+ "$TASQMATE_BIN" events ack "$TASQMATE_EVENT_ID"
104
+
105
+ continue
106
+ fi
107
+
108
+ echo "→ cycle_closed on release ${TASQMATE_EVENT_RELEASE_ID} (${TASQMATE_EVENT_ID})" >&2
109
+
110
+ # `set -e` must not kill the loop on a failed read: leave the event unacked
111
+ # and keep listening, the same contract the mention runner keeps.
112
+ if ! context="$("$TASQMATE_BIN" release context "$TASQMATE_EVENT_RELEASE_ID")"; then
113
+ echo " could not read the context; leaving ${TASQMATE_EVENT_ID} unacked" >&2
114
+
115
+ continue
116
+ fi
117
+
118
+ TASQMATE_NARRATOR_CMD="${TASQMATE_NARRATOR_CMD:-${TASQ_NARRATOR_CMD:-}}"
119
+ if [[ -n "${TASQMATE_NARRATOR_CMD:-}" ]]; then
120
+ if ! narrative="$(printf '%s' "$context" | sh -c "$TASQMATE_NARRATOR_CMD")"; then
121
+ echo " narrator command failed; leaving ${TASQMATE_EVENT_ID} unacked" >&2
122
+
123
+ continue
124
+ fi
125
+ else
126
+ narrative="$(placeholder_narrative "$context")"
127
+ fi
128
+
129
+ if [[ -z "${narrative//[[:space:]]/}" ]]; then
130
+ echo " the narrative came back empty; leaving ${TASQMATE_EVENT_ID} unacked" >&2
131
+
132
+ continue
133
+ fi
134
+
135
+ # `--file` rather than `--body`: a narrative is Markdown with newlines in it,
136
+ # and a temporary file keeps it off the argument list and out of `ps`.
137
+ body_file="$(mktemp -t tasq-narrative.XXXXXX)"
138
+ printf '%s' "$narrative" > "$body_file"
139
+
140
+ if "$TASQMATE_BIN" release narrate "$TASQMATE_EVENT_RELEASE_ID" --file "$body_file"; then
141
+ "$TASQMATE_BIN" events ack "$TASQMATE_EVENT_ID"
142
+ else
143
+ echo " narrate failed; leaving ${TASQMATE_EVENT_ID} unacked for redelivery" >&2
144
+ fi
145
+
146
+ rm -f "$body_file"
147
+ done
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
- "name": "tasqmate",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "tasqmate",
3
+ "version": "0.2.0",
4
+ "description": "Command-line client for Tasqmate, for humans and agents alike. Installs the tasqmate and tasqmate commands.",
5
+ "keywords": [
6
+ "tasqmate",
7
+ "cli",
8
+ "agents",
9
+ "project-management"
10
+ ],
11
+ "license": "MIT",
12
+ "author": "Paul Cedrick Artigo",
13
+ "homepage": "https://github.com/pxlabz/tasq/tree/main/packages/cli#readme",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/pxlabz/tasq.git",
17
+ "directory": "packages/cli"
18
+ },
19
+ "bugs": {
20
+ "url": "https://github.com/pxlabz/tasq/issues"
21
+ },
22
+ "private": false,
23
+ "type": "module",
24
+ "bin": {
25
+ "tasqmate": "./dist/tasqmate.js",
26
+ "tasq": "./dist/tasqmate.js"
27
+ },
28
+ "files": [
29
+ "dist",
30
+ "examples",
31
+ ".tasqmate-skill.md",
32
+ "README.md",
33
+ "LICENSE"
34
+ ],
35
+ "publishConfig": {
36
+ "access": "public"
37
+ },
38
+ "engines": {
39
+ "node": ">=20.3"
40
+ },
41
+ "scripts": {
42
+ "build": "tsup && chmod +x dist/tasqmate.js",
43
+ "typecheck": "tsc --project tsconfig.json --noEmit",
44
+ "lint": "cd ../.. && bun --bun ./node_modules/oxlint/bin/oxlint packages/cli",
45
+ "test": "bun test"
46
+ },
47
+ "dependencies": {
48
+ "@clack/prompts": "^0.11.0",
49
+ "cli-table3": "^0.6.5",
50
+ "commander": "^14.0.0",
51
+ "zod": "4.3.6"
52
+ },
53
+ "devDependencies": {
54
+ "@tasqmate/sdk": "0.2.0",
55
+ "@types/bun": "^1.3.12",
56
+ "tsup": "^8.5.0",
57
+ "typescript": "^5.7.2"
58
+ }
59
+ }