toga-ai 1.0.381 → 1.0.382
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.
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
| [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
|
|
11
11
|
| [ClickUp Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |
|
|
12
12
|
| [ClickUp Subtask Activity → Parent Opportunity/Epic Comments](features/clickup-subtask-activity.md) | Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity** or **Epic** it rolls up to, so a deal/project owner sees activity whe | worker2/Worker/Clickup/Subtask.php, worker2/Worker/Clickup.php, dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql |
|
|
13
|
+
| [ClickUp Task Description Fluffer (Talos KB Investigation)](features/clickup-task-fluffer-talos.md) | `_Worker_Clickup_Fluffer` "fluffs" a ClickUp task by sending its name + existing description to the **Talos `dev-core` KB-investigation agent** and writing the | worker2/Worker/Clickup/Fluffer.php, worker2/Worker/Clickup.php, worker2/Config/production.ini, worker2/Config/beta.ini, worker2/Config/dev-rohan-mac.ini |
|
|
13
14
|
| [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
|
|
14
15
|
| [Compass VIP Support Importer (worker2)](features/compass-vip-support-importer.md) | A worker2 action that ingests Compass's quarterly VIP spreadsheet and assigns each VIP user's support technician by setting `Users.c_supportedByUserId` in `Clie | worker2/Worker/Client/Compass/VipSupport.php |
|
|
15
16
|
| [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: ClickUp Task Description Fluffer (Talos KB Investigation)
|
|
3
|
+
framework: "2.0"
|
|
4
|
+
repo: worker2
|
|
5
|
+
project: Worker
|
|
6
|
+
client: shared
|
|
7
|
+
type: feature
|
|
8
|
+
status: active
|
|
9
|
+
updated: 2026-07-20
|
|
10
|
+
owners: [rgirish]
|
|
11
|
+
files:
|
|
12
|
+
- worker2/Worker/Clickup/Fluffer.php
|
|
13
|
+
- worker2/Worker/Clickup.php
|
|
14
|
+
- worker2/Config/production.ini
|
|
15
|
+
- worker2/Config/beta.ini
|
|
16
|
+
- worker2/Config/dev-rohan-mac.ini
|
|
17
|
+
related:
|
|
18
|
+
- ./clickup-project-routing.md
|
|
19
|
+
- ./clickup-richtext-api.md
|
|
20
|
+
- ./talos-transcript-ingestion.md
|
|
21
|
+
- ./creating-worker-actions.md
|
|
22
|
+
- ../architecture.md
|
|
23
|
+
- ../../talos/features/talos-agent.md
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Summary
|
|
27
|
+
|
|
28
|
+
`_Worker_Clickup_Fluffer` "fluffs" a ClickUp task by sending its name + existing description
|
|
29
|
+
to the **Talos `dev-core` KB-investigation agent** and writing the returned Markdown report
|
|
30
|
+
back onto the task's `markdown_content`. It runs automatically on every ClickUp
|
|
31
|
+
`taskCreated` webhook and on demand via the `Clickup/Fluffer/Process` action. It is
|
|
32
|
+
**async by design** — the ~3-4 minute Talos call runs as its own worker-tier job and never
|
|
33
|
+
blocks the webhook response.
|
|
34
|
+
|
|
35
|
+
This is TOGA-internal team tooling (ClickUp + Talos), not client-specific.
|
|
36
|
+
|
|
37
|
+
## Key files / entry points
|
|
38
|
+
|
|
39
|
+
- `Worker/Clickup/Fluffer.php` — `abstract class _Worker_Clickup_Fluffer`; action method
|
|
40
|
+
`public static function Process(string $taskId, bool $force = false): string`. Invoked as
|
|
41
|
+
action path `Clickup/Fluffer/Process`.
|
|
42
|
+
- `Worker/Clickup.php` — the `taskCreated` case (~line 787) enqueues the fluffer.
|
|
43
|
+
- `Config/*.ini` `[talos]` section — the **new** `agent_endpoint` + `agent_api_key` keys
|
|
44
|
+
(see Configuration; `beta.ini`'s `[talos]` section was newly added this session).
|
|
45
|
+
|
|
46
|
+
## How it works
|
|
47
|
+
|
|
48
|
+
### Enqueue (async)
|
|
49
|
+
`taskCreated` enqueues via
|
|
50
|
+
`_Worker::runTask('Clickup/Fluffer/Process', ['taskId' => $payload->task_id])`. In
|
|
51
|
+
production/beta, `_Worker::runTask` (`_underscore/Worker.php`) does **no MySQL** — it just
|
|
52
|
+
sends the job to SQS and returns immediately, so the fluffer runs later as its own
|
|
53
|
+
worker-tier job and the long Talos call never blocks the webhook response. Only local debug
|
|
54
|
+
mode (`_Environment::isDebugMode()`) runs `runTask` synchronously via a direct HTTP POST to
|
|
55
|
+
the worker.
|
|
56
|
+
|
|
57
|
+
### The Talos agent call
|
|
58
|
+
Uses `_ApiRequest` (not the ClickUp component) for the Talos call:
|
|
59
|
+
`POST https://api.togaiq.com/api/ai/agent`, body:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"assistant_slug": "dev-core",
|
|
64
|
+
"stream": false,
|
|
65
|
+
"format": "json",
|
|
66
|
+
"tool_categories": ["knowledge_base"],
|
|
67
|
+
"messages": [{"role": "user", "content": "<prompt: task name + existing description>"}]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`_ApiRequest` settings: `setTimeout(280)`, `setConnectTimeout(20)`, `setLogging(false)`,
|
|
72
|
+
`throwExceptionsOnFailure = false`; header **`X-API-Key`** (NOT `Authorization: Bearer`);
|
|
73
|
+
`addHeader('Expect','')` to avoid 100-continue flakiness. The agent returns a Markdown
|
|
74
|
+
`## Talos KB Investigation` report.
|
|
75
|
+
|
|
76
|
+
- **`/api/ai/agent` is a DIFFERENT endpoint from the existing `/api/ai/generate`** used by
|
|
77
|
+
the Transcripts/Sprint features, and it uses a **different key** scoped to the `dev-core`
|
|
78
|
+
assistant slug. Both live in **new** `[talos]` INI keys `agent_endpoint` + `agent_api_key`,
|
|
79
|
+
separate from the existing `api_key`/`endpoint`. Read via
|
|
80
|
+
`_Config::talos('agent_endpoint')` / `_Config::talos('agent_api_key')` — never hardcode.
|
|
81
|
+
- The agent endpoint requires the `feature/api-key-agent-bridge` branch deployed to prod
|
|
82
|
+
(verified live this session — prod returned HTTP 200).
|
|
83
|
+
|
|
84
|
+
### Writing back to the task
|
|
85
|
+
Uses `_Component_Api_Clickup::send('GET'|'PUT', '/task/'.$taskId, $payload)` for ClickUp
|
|
86
|
+
reads/writes (the shared component owns the ClickUp token). The report is written to the
|
|
87
|
+
task's `markdown_content`, which ClickUp renders as rich text server-side.
|
|
88
|
+
|
|
89
|
+
### Idempotency & layout
|
|
90
|
+
A styled header line
|
|
91
|
+
`> **_🤖 Generated by Talos KB Investigation — do not edit above this line manually._**`
|
|
92
|
+
(marker substring **"Generated by Talos"**) leads the generated block; the end sentinel
|
|
93
|
+
**"— end of Talos KB Investigation —"** closes it. Layout order:
|
|
94
|
+
|
|
95
|
+
1. header line
|
|
96
|
+
2. Talos report
|
|
97
|
+
3. end sentinel
|
|
98
|
+
4. preserved human-authored text (everything AFTER the end sentinel)
|
|
99
|
+
|
|
100
|
+
`stripTalosBlock()` keeps the portion after the end sentinel, so human edits below the
|
|
101
|
+
sentinel survive regeneration. The auto path **skips** (returns `"skipped: already fluffed"`)
|
|
102
|
+
if the marker substring is already present; `force=true` regenerates.
|
|
103
|
+
|
|
104
|
+
### Rate limiting
|
|
105
|
+
Reuses the shared constant `_Worker_Clickup_Project::RATE_LIMIT_DELAY_US` (120000 µs = 120ms
|
|
106
|
+
→ 500 ClickUp calls/min) via `usleep()` after **each** ClickUp `send()` call — the same
|
|
107
|
+
convention `Project.php` and `Subtask.php` use, so all Clickup workers cooperate on one
|
|
108
|
+
ClickUp rate budget.
|
|
109
|
+
|
|
110
|
+
## Configuration
|
|
111
|
+
|
|
112
|
+
`worker2/Config/{production,beta,dev-rohan-mac}.ini` `[talos]` section adds:
|
|
113
|
+
|
|
114
|
+
- `agent_endpoint` — the `/api/ai/agent` URL.
|
|
115
|
+
- `agent_api_key` — the `dev-core`-scoped key.
|
|
116
|
+
|
|
117
|
+
Both are separate from the existing `[talos]` `api_key`/`endpoint` (used by
|
|
118
|
+
Transcripts/Sprint). Per existing repo convention the secret lives in the committed INI;
|
|
119
|
+
read it via `_Config::talos(...)`, never hardcode. Documented here by key name/account only,
|
|
120
|
+
never by value.
|
|
121
|
+
|
|
122
|
+
## Gotchas / known issues
|
|
123
|
+
|
|
124
|
+
- **Watchdog race.** The fluffer is an **ACTION** job; its watchdog is the Lambda env
|
|
125
|
+
`MAX_EXECUTION_TIME_WORKER_ACTION` (default 300s). The Talos timeout is set to **280** (just
|
|
126
|
+
under 300) so the job doesn't lose the race against its own watchdog out of the box.
|
|
127
|
+
Recommend raising `MAX_EXECUTION_TIME_WORKER_ACTION` to ~420s so slow investigations
|
|
128
|
+
complete.
|
|
129
|
+
- **`_Component_Api_Clickup::send()` fails in a bare CLI harness with a misleading error.**
|
|
130
|
+
`send()` leaves `_ApiRequest` logging **ON** by default, so `execute()` tries to write an
|
|
131
|
+
api-log row to the Client Logs DB (alias resolves to database name `ClientLogs`) **before**
|
|
132
|
+
the curl call. In a bare CLI harness (or the legacy `action` dispatch path) where the logs
|
|
133
|
+
DB isn't registered, this throws `Unknown database 'ClientLogs'` and surfaces as an
|
|
134
|
+
empty-code `API Error … (HTTP ): no error detail` — even though the ClickUp call would have
|
|
135
|
+
succeeded. The production `workerJobId` dispatch path (`Controller/Index.php`) registers
|
|
136
|
+
`DB_LOGS` + `DB_CLIENT_LOGS` before running the action, so `send()`'s logging works there.
|
|
137
|
+
**Workaround for manual/CLI testing:** call the ClickUp API via `_ApiRequest` with
|
|
138
|
+
`setLogging(false)`, or register the logs DBs first. This is a test-harness gotcha, not a
|
|
139
|
+
code bug. (Same DB-registration class of issue as the worker-action gotchas in
|
|
140
|
+
[Creating Worker Actions](./creating-worker-actions.md).)
|
|
141
|
+
- **Distinct Talos endpoint/key.** Do not reuse the Transcripts/Sprint `[talos]` `api_key` /
|
|
142
|
+
`endpoint` for the agent — `/api/ai/agent` needs the `dev-core`-scoped `agent_api_key`, and
|
|
143
|
+
the header is `X-API-Key`, not `Authorization: Bearer`.
|
|
144
|
+
|
|
145
|
+
## Change history
|
|
146
|
+
|
|
147
|
+
- 2026-07-20 — Built the ClickUp task description fluffer: new `_Worker_Clickup_Fluffer`
|
|
148
|
+
(action `Clickup/Fluffer/Process`, `taskCreated` webhook auto-trigger, `force` regenerate)
|
|
149
|
+
calling the Talos `dev-core` KB-investigation agent at `/api/ai/agent` via `_ApiRequest`
|
|
150
|
+
(`X-API-Key`, `Expect:` cleared, 280s timeout). Report written to ClickUp
|
|
151
|
+
`markdown_content` with a "Generated by Talos" marker + end sentinel for idempotency
|
|
152
|
+
(human text below the sentinel is preserved). New `[talos]` `agent_endpoint`/`agent_api_key`
|
|
153
|
+
keys (beta.ini `[talos]` section newly added). Requires `feature/api-key-agent-bridge` in
|
|
154
|
+
prod (verified HTTP 200). Documented the `_Component_Api_Clickup::send()` CLI logging-DB
|
|
155
|
+
gotcha (`Unknown database 'ClientLogs'`). (rgirish)
|
|
156
|
+
</content>
|
package/knowledge/INDEX.md
CHANGED
|
@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
|
|
|
18
18
|
## 2.0 framework
|
|
19
19
|
|
|
20
20
|
- **_underscore** (_Underscore) _(framework core)_ — 35 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
|
|
21
|
-
- **worker2** (Worker) —
|
|
21
|
+
- **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
|
|
22
22
|
- **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
|
|
23
23
|
- **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
|
|
24
24
|
- **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
|
package/package.json
CHANGED