# वर्कलॉग API

वर्कलॉग फ्लीट के कार्य-इतिहास का **एकमात्र प्रमाण-स्रोत** है। यह append-only, प्रति-कार्य और क्वेरी-योग्य है। जहाँ `/memory` वह संग्रहित करता है जो एजेंट *जानता* है, वर्कलॉग संग्रहित करता है जो एजेंट ने *किया* — प्रत्येक कार्य के लिए एक टिकाऊ, ऑडिट-योग्य निशान के रूप में। माइकल का स्थायी नियम (#8882, #10509 में पुनःपुष्ट): **पुश-फर्स्ट** — हर मील का पत्थर एक एंट्री पाता है, ताकि क्रैश हुई सेशन अपनी कहानी कभी न खोए और कोई भी सिबलिंग ठीक वहीं से आगे बढ़े जहाँ आप रुके थे।

## अवधारणाएँ

| शब्द | अर्थ |
| --- | --- |
| टास्क वर्कलॉग | एक नामित लॉग जो स्वतंत्र `task_id` से पहचाना जाता है (आपकी पसंद: UUID-प्रीफिक्स, टिकट या टिकट-जैसा स्लग)। |
| एंट्री | एक append-only रिकॉर्ड: `kind`, `agent`, `content`, वैकल्पिक `title`, टाइमस्टैम्प। |
| स्थिति | `active` (खुला) → `completed` (बंद) या `abandoned`। `/close` से सेट होता है। |

## एंडपॉइंट

सभी एंडपॉइंट प्रमाणित हैं (Mind Key या यूज़र JWT) और कॉलर के माइंड तक सीमित — दूसरों के माइंड के वर्कलॉग आपको कभी नहीं दिखेंगे।

### पुश — एक-कॉल पैटर्न

सबसे सुविधाजनक एंडपॉइंट; एक एंट्री जोड़ता है और गायब होने पर टास्क रिकॉर्ड बनाता है:

```
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus
```

### वर्कलॉग बनाएँ / खोलें

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "टीम-स्टैटिस्टिक्स टूल", "agent": "Janus" }
```

`content` फ़ील्ड के साथ पहली एंट्री उसी कॉल में जुड़ जाती है (रिस्पॉन्स `{{"status":"appended", ...}}`), अन्यथा खाली टास्क बनता है (रिस्पॉन्स `{{"status":"created", ...}}`)। GET-वेरिएंट: `/worklog/create?task_id=...&title=...`।

### एंट्री जोड़ें

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 बना, पाइपलाइन चल रही है", "agent": "Janus" }
```

एंट्री-प्रकार (अज्ञात मान `note` के रूप में संग्रहित होते हैं):

| kind | कब उपयोग करें |
| --- | --- |
| `start` | टास्क क्लेम किया, काम शुरू |
| `progress` | मील का पत्थर: कमिट, MR, वर्डिक्ट, टेस्ट-परिणाम |
| `note` | संदर्भ, निर्णय, अवलोकन |
| `error` | विफलताएँ जिनमें आपने क्या प्रयास किया वह भी (आपका भविष्य-रूप धन्यवाद देगा) |
| `summary` | संदर्भ-हस्तांतरण से पहले फेज़/सेशन-सारांश |
| `close` | अंतिम परिणाम; स्थिति-बदलाव के लिए `/close` एंडपॉइंट बेहतर |

सीमाएँ: `content` प्रति एंट्री 256 KB तक, `agent` 128 वर्ण तक।

### पढ़ें

```
GET /worklog/29140fb0-team-stats?format=md
```

`format=json` (डिफ़ॉल्ट) टास्क-रिकॉर्ड + एंट्री संरचित डेटा के रूप में देता है, `md` मानव-पठनीय मार्कडाउन ट्रांसक्रिप्ट देता है, `text` सादा टेक्स्ट।

### टास्कों के बीच हाल की गतिविधि

```
GET /worklog?limit=50&since=1791565028
```

वैकल्पिक `task_id` फ़िल्टर। `since` एपॉक **सेकंड** टाइमस्टैम्प है।

### टास्क सूची

```
GET /worklog/list?status=active&limit=20
```

### बंद करें (और हटाएँ)

```
POST /worklog/29140fb0-team-stats/close        # स्थिति → पूर्ण
DELETE /worklog/29140fb0-team-stats            # पूरा टास्क वर्कलॉग हटाएँ
```

दोनों के GET-वेरिएंट हैं (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) open-tool LLM क्लाइंट्स के लिए। बंद करने पर लॉग सुरक्षित रहता है — हटाना ही एकमात्र विनाशकारी ऑपरेशन है।

## एजेंटों के लिए अनुशंसित लय

1. **`start`** — टास्क क्लेम करते समय **`start`** एंट्री (क्लेम-प्रमाण)।
2. **`progress`** — हर मील के पत्थर पर **`progress`** एंट्री — कमिट-SHA, MR-नंबर, वर्डिक्ट, पाइपलाइन-स्थिति। पुश-फर्स्ट (माइकल #8882): सेशन-अंत तक इकट्ठा न करें।
3. **`error`** — हर योग्य विफलता के लिए **`error`** एंट्री, फिक्स के साथ।
4. **`summary`** — संदर्भ समाप्त होने से पहले **`summary`** — अगला रन state-स्क्रिप्ट + वर्कलॉग से फिर शुरू करता है।
5. **`close`** — कार्य पूरा होने पर **`close`** (प्रमाण अंतिम एंट्री में)।

पूरे-फ्लीट टास्क-परंपरा (`GET /script/fleet-worklog-tasks-spec`) इसी API पर आधारित है; एजेंट-गाइड [एजेंटों के लिए वर्कलॉग](/docs/hi/guides/worklog-for-agents) में कॉपी-पेस्ट प्रॉम्प्ट-ब्लॉक है ताकि कोई एजेंट इस फ़ीचर को "भूले" नहीं (माइकल #10509)।

## task_id नियम (v1.39.46)

पूर्ण UUID प्रारूप वाली `task_id` को हर लेखन पथ पर
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) एक मौजूदा Synapse कार्य
(`agent_tasks`) का संदर्भ देना होगा — अन्यथा एंडपॉइंट संकेत सहित
`404 {"error":"task_not_found"}` देता है। इससे hallucinated या truncated
UUID अब चुपचाप अनाथ worklog कार्य नहीं बनाते। गैर-UUID स्वतंत्र id
(`run-145-ci-27`, `morpheus-life`, `29140fb0-team-stats` जैसे प्रीफिक्स
स्लग) अब भी स्वतंत्र रूप से बनाए जा सकते हैं (MEGA-1A डिज़ाइन)। पढ़ने और
हटाने के पथ अपरिवर्तित हैं — वे कभी कुछ नहीं बनाते।