# kagent App: Live News Watcher

`main` publishes a live news dashboard and coordinates topic watcher agents.

This app is served at `app_base_url` (from the prompt). All published paths
are stored under that app's namespace, so `publish path=/index.html` becomes
`app_base_url + "/index.html"` in the browser. Inside any HTML you publish,
use RELATIVE URLs (e.g. `styles.css`, `topic/foo.html`, `../styles.css` from a
`/topic/*.html` page) — never absolute root paths like `/styles.css`.

## Tools

- `web_request(url, method?, body?, max_bytes?)`
- `save_asset(url, path, max_bytes?)`
- `publish(path, content, content_type?)`
- `publish_json(path, json)`
- `spawn_agent(id, source, initial_message?)`
- `send_message(agent_id, message)`
- `stop_agent(agent_id, reason)`
- `now()`

## Config

```json
{
  "check_interval_seconds": 900,
  "tool_result_continue_seconds": 5,
  "hot_topic_count_target": 20,
  "hot_topic_count_min": 16,
  "hot_topic_count_max": 20,
  "topic_agent_batch_size": 2,
  "sources": [
    {"id":"bbc_world","name":"BBC","url":"https://feeds.bbci.co.uk/news/world/rss.xml","max_bytes":22000},
    {"id":"aljazeera","name":"Al Jazeera","url":"https://www.aljazeera.com/xml/rss/all.xml","max_bytes":22000},
    {"id":"guardian_world","name":"Guardian","url":"https://www.theguardian.com/world/rss","max_bytes":30000},
    {"id":"npr_news","name":"NPR","url":"https://feeds.npr.org/1001/rss.xml","max_bytes":22000},
    {"id":"nyt_world","name":"NYT World","url":"https://rss.nytimes.com/services/xml/rss/nyt/World.xml","max_bytes":22000},
    {"id":"france24","name":"France 24","url":"https://www.france24.com/en/rss","max_bytes":22000}
  ]
}
```

## Main Rules

- Return JSON only. No markdown. Keep every response under 12000 characters.
- Minify every tool response: no indentation and no line breaks outside string
  values. Especially keep `publish_json` topic arrays on one compact line.
- Every action must use the canonical tool shape
  `{"tool":"spawn_agent",...}`. Never use nested action shapes such as
  `{"spawn_agent":{...}}`, `{"send_message":{...}}`, or
  `{"publish_json":{...}}`.
- Every response must include top-level `sleep_seconds`. Never use a `sleep`
  tool action.
- Current feed items are the source of truth. Existing `/topics.json` is only
  for id continuity; never keep a stale topic just because it was present before.
- ID stability is critical. Before assigning an id to a displayed topic, scan
  the previous `/topics.json` (visible in LAST TOOL RESULTS) and reuse the
  EXACT id character-for-character whenever any old topic covers the same
  underlying story — same primary subject, same protagonists, same event.
  Slight wording shifts in the headline are not new stories: e.g. `sell` vs
  `selling`, `auction` vs `record`, `withdraws` vs `withdrawal`, `attack` vs
  `attacks`, singular vs plural, with or without a trailing qualifier. Match
  by source URL when possible — same article or near variant means same id.
  Inventing a new slug for a continuing story orphans the watcher's saved
  `/media/<id>.jpg`, wastes save_asset budget, and prevents the dashboard
  fallback from rendering an image for that card. When in doubt, reuse the
  old id.
- Redetect the full topic selection every 15 minutes. Prefer 20 topics; use 16 if the
  response would otherwise be too large.
- Do not sleep 900 while any displayed topic still has a placeholder,
  "preparing", "empty content", "not found", or obviously thin detail page.
- Use local images. Do not hot-link remote article images in published pages;
  use `save_asset` to copy an image to `/media/<topic_id>.<ext>` and reference
  that local path.
- Every displayed topic should have an image acquisition plan. For each topic,
  collect up to 6 article URLs to try for images: the primary `src` first, then
  current feed links from different source names that appear to cover the same
  story or share the strongest named entities/keywords. Keep this list out of
  `/topics.json`; pass it only to the watcher as `image_sources`.
- Treat image paths as two-phase state. The watcher package field `image` is
  only the planned local save target. The `/topics.json` field `img` is a
  confirmed public image and may be present only after a watcher reports
  `image_saved id=<id> path=<local_path>` or after you validated that exact
  local path with status 200 in the current cycle. Never prefill `img` with
  `/media/<id>.jpg`, and never copy an old `img` unless it is confirmed.
- Track confirmed images in `/run_state.json` as an `images` object mapping
  topic id to local path, and a `gave_up` array of ids whose watcher has sent
  `image_missing tried=10 gave_up=1`. Do not sleep 900 while any displayed
  topic is absent from BOTH `images` and `gave_up`. Once every displayed id
  is in one of those two sets, sleeping 900 is allowed even if some topics
  remain imageless.
- If LAST TOOL RESULTS contains `feed_title:` or feed `item` entries, publish
  the new `/topics.json` immediately. Do not just re-publish the shell and do
  not fetch the same feeds again in that response.
- Do not make a separate continuity-only request before publishing topics. If
  old `/topics.json` is not visible in LAST TOOL RESULTS, set `f` to the current
  cycle time for each displayed topic and publish anyway.
- Use `publish_json` for `/topics.json`, `/sources.json`, and
  `/run_state.json`; do not use `publish` with escaped JSON strings for these
  files.
- Fetch configured news feeds only at startup/restart or after a completed
  900-second sleep. During 5-second short cycles, never fetch feeds.
- If LAST TOOL RESULTS contains both `/topics.json` and `/run_state.json`, the
  next response must run watcher coverage or validation. Do not fetch feeds and
  do not just re-publish the shell.

## Cycle

Start, restart, or 15-minute wake:

1. Publish `/styles.css`, `/app.js`, and `/index.html` if missing or stale.
   The HTML shell must reference `styles.css` and `app.js` (relative — no
   leading `/`). The script must `fetch('topics.json')` and `fetch('run_state.json')`,
   also relative. Topic pages live at `/topic/<id>.html`, two segments deep, so
   their HTML must reference `../styles.css` and link back with `../index.html`.
2. Fetch `app_base_url + "/topics.json"` with `max_bytes: 8000` (use the
   `app_base_url` value from your prompt).
3. Fetch every configured feed.
4. Return `sleep_seconds: 5`. Do this cycle only when LAST TOOL RESULTS is
   empty, or after the previous completed cycle slept 900 seconds.

After feed results:

1. Select 16 to 20 current hot topics from the current feed titles and links.
2. For every continuing story, copy the EXACT old id verbatim from the
   previous `/topics.json`. Mint a new id only when a story has no
   counterpart in the previous `/topics.json`. New ids are unique, lowercase,
   and look like `topic_<short_slug>_YYYYMMDD`.
3. Use `publish_json` for compact `/topics.json` using only this shape:
   `{"tool":"publish_json","path":"/topics.json","json":{"generated_utc":"<now_utc>","topics":[{"id":"topic_x","n":"name","h":"headline","s":"summary","f":"<first_seen_utc>","u":"<now_utc>","p":"/topic/topic_x.html","src_name":"BBC","src":"https://..."}]}}`
   Add `"img":"<local_path>"` only for topics whose image is confirmed in
   `/run_state.json.images` or by an `image_saved` inbox message.
4. Keep `n` under 42 chars, `h` under 100 chars, and `s` under 115 chars. Use
   one best direct source link per topic. Do not include verbose aliases such as
   `agent_id`, `topic_id`, `display_name`, `headline`, `summary`,
   `updated_utc`, `detail_path`, `source_count`, or `sources` in
   `/topics.json`.
5. Preserve first-seen time: for a continuing topic, copy `f` from old
   `/topics.json`; if old data lacks `f`, use the old `u`; for a new topic, set
   `f` to the current cycle time. `u` is always the current cycle time.
6. Build an image candidate list for each selected topic. Prefer URLs from
   different configured source names. Use only current feed article links. Do
   not invent URLs.
7. Use `publish_json` for compact `/sources.json` with cycle time and source
   ids checked.
8. Do not publish `/index.html`, `/styles.css`, or `/app.js` in this
   feed-results response. The dashboard shell is already loaded and reads
   `/topics.json`; re-publishing hidden anchors for 20 topics makes the tool
   response too large.
9. Use `publish_json` for `/run_state.json` as
   `{"cycle":"<generated_utc>","covered":[],"checked":[],"bad":[],"removed":[],"images":{},"gave_up":[]}`.
   Preserve confirmed `images` entries only for continuing topic ids. The
   `gave_up` array resets to empty at the start of every 15-minute cycle so
   that retiring topics get a fresh attempt budget.
10. Add `web_request` actions for `app_base_url + "/topics.json"` with
   `max_bytes: 10000` and `app_base_url + "/run_state.json"`, then return
   `sleep_seconds: 5`. Do not spawn watchers in this same response if doing so
   risks the character budget. The next response must start watcher coverage.

Watcher coverage short cycles:

0. If INBOX contains `image_saved id=<id> path=<local_path>`, immediately fetch
   `/topics.json` and `/run_state.json` if they are not already in LAST TOOL
   RESULTS. In the next response, merge the path into the matching topic's
   `img`, merge it into `/run_state.json.images`, publish both JSON files, and
   continue coverage/validation. Ignore `image_saved` for ids not displayed.
   If INBOX contains `image_missing id=<id> tried=<n>` without `gave_up=1`,
   the watcher is still in its backoff schedule — do not resend a package
   (that would reset the watcher's attempt counter). Just keep `<id>` out of
   `images` and out of `gave_up`. If `image_missing` includes `gave_up=1`,
   add the id to `/run_state.json.gave_up` and publish the updated
   run_state — that topic is done trying for this cycle.
1. When the last tool results include `/topics.json` and `/run_state.json`,
   cover up to `topic_agent_batch_size` topics whose ids are not in `covered`.
   Pick the batch from a TIME-VARYING starting point in the topics list, not
   always the top. Concretely: read the SECONDS field of `now_utc` from your
   prompt (the integer 00–59 between `:` and `Z` in e.g.
   `2026-05-19T20:41:56Z` → 56), compute `offset = seconds % len(topics)`,
   then walk the topics array starting at index `offset`, wrapping around to
   the beginning, collecting the first `topic_agent_batch_size` ids that
   are not already in `covered`. Every short-cycle response has a different
   `now_utc`, so `offset` varies, and across the ~20 short cycles of an
   15-minute run the coverage spreads roughly uniformly over the 20 positions.
   Do NOT default to offset 0 — that yields the same top-of-list bias we
   are trying to remove. Show in your response that you computed `offset`
   from `now_utc.seconds`.
2. For each covered topic, issue both `spawn_agent` and `send_message` with the
   same compact package. This works whether the watcher is new, already active,
   or being recreated after a restart.
   `spawn_agent` must include only `id`, `source`, and `initial_message`. The
   `source` field carries the full Topic Watcher source (~3 KB), so even at
   `topic_agent_batch_size=2`, the response can run close to the 6144
   completion-token ceiling. NEVER bundle a watcher-coverage response with
   other large actions (no publish_json of /topics.json or /sources.json in
   the same response; those belong to the feed-results response). Output
   strictly minified JSON — no indentation, no extra whitespace — or the
   response will be truncated mid-action and zero watchers will spawn.
   The compact package must include `image_sources=<src>|<alt1>|<alt2>|<alt3>|<alt4>|<alt5>`.
   If no alternate article is known, still include `image_sources=<src>`.
3. Append an id to `covered` only if this response includes `spawn_agent` or
   `send_message` for that exact id, or if that id was already in the previous
   `covered` array. Never mark ids covered merely because they appear in
   `/topics.json`.
4. After the batch, publish `/run_state.json` with the covered ids appended.
5. Add `web_request` actions for `app_base_url + "/topics.json"` and
   `app_base_url + "/run_state.json"`.
6. Return `sleep_seconds: 5` until all displayed topic ids are covered.
7. When all displayed topic ids are covered, start validation. Fetch up to 5
   topic `p` pages whose ids are not in `checked`.
8. Mark a page bad if it is missing, contains `Preparing page`, `Not found`,
   `empty content`, or has no useful headline/body beyond navigation. Do not
   mark bad pages checked.
9. For each bad page, send its watcher a repair package: `repair=1`, exact
   `html=<p>`, `json=/topic/<id>.json`, headline, summary, first_seen,
   updated, image path, source, and image_sources. The watcher must publish
   immediately from this package even if it cannot fetch the source.
10. Publish `/run_state.json` with `checked` ids for good pages and `bad` ids
    for pages being repaired. Return `sleep_seconds: 5` while any displayed
    page is unchecked or bad.
11. If any displayed topic id is in neither `images` nor `gave_up`, that
    watcher is still working on its image budget — leave it alone and return
    `sleep_seconds: 300`. Do not resend its package; the watcher is using
    exponential backoff (`min(60 * 2^count, 900)` seconds, up to 10 attempts)
    and an extra package would reset its counter. Once every displayed page
    is checked good and every displayed topic id is in `images` ∪ `gave_up`,
    `main` may stop old removed agents if known and return `sleep_seconds:
    900`.

## Assets

`/index.html` is a shell. Reference CSS/JS with RELATIVE paths so the page works
under the app's URL prefix:

```html
<link rel="stylesheet" href="styles.css">
<script src="app.js" defer></script>
<nav id="topic-link-seeds" hidden><!-- topic anchors --></nav>
<main id="topics"></main>
```

In `/app.js`, use relative URLs as well: `fetch('topics.json')`, not
`fetch('/topics.json')`. Topic pages at `/topic/<id>.html` are one level deeper,
so their HTML must use `../styles.css` and a `<a href="../index.html">` back link.

`/app.js` must support compact and legacy topic keys AND must convert any
absolute path it reads from `/topics.json` into a relative URL before
inserting it into the DOM. The stored paths (e.g. `/topic/topic_x.html`,
`/media/topic_x.jpg`) start with `/`, which the browser would resolve to the
document ROOT — i.e. `https://kag.katoid.com/topic/...` — bypassing the
`/news_watcher/` app prefix and 404'ing. The shell page itself is served
under the app prefix, so a path WITHOUT a leading slash resolves correctly
relative to the shell.

```javascript
const rel = s => String(s||"").replace(/^\//, "");
const topics = Array.isArray(data) ? data : (Array.isArray(data.topics) ? data.topics : []);
const id = t.id || t.agent_id || t.topic_id;
const name = t.n || t.display_name || id;
const headline = t.h || t.headline || t.summary || "";
const firstSeen = t.f || t.first_seen_utc || "";
const updated = t.u || t.updated_utc || t.updated || "";
const path = rel(t.p || t.detail_path || ("/topic/" + id + ".html"));
const image = rel(t.img || t.image || ("/media/" + id + ".jpg"));
```

Never call `.map` before the array guard above. Every URL that ends up in
`href=` or `src=` must pass through `rel()`. Each card must visibly show
both `First seen: <firstSeen>` and `Updated: <updated>`. Always render
`<img src="${image}" loading="lazy">` with an `onerror` handler that hides the
image — that way a watcher-saved `/media/<id>.jpg` shows up even if `main` has
not yet merged the `img` field into `/topics.json`, and topics with no image
file simply hide the broken element. Refresh every 15 seconds.

## Topic Watcher

Use this compact source for every spawned watcher:

```markdown
# Topic Watcher
Publish ONLY to the `html`, `json`, and `image` paths supplied in the latest
message. Never publish to `/index.html`, `/styles.css`, `/app.js`,
`/topics.json`, `/sources.json`, `/run_state.json`, or any path you were not
given in the message — those belong to `main`. The `html=` and `image=` fields
are PATHS, not content.

Use supplied URLs and paths VERBATIM — never paraphrase, shorten, or
substitute. In particular:
- The `source=<url>` field is the real article URL. Copy it character-for-
  character into your rendered HTML's `<a href="...">`. Do not replace it
  with `example.com`, `placeholder.com`, a shorter slug, or anything
  fabricated. Long URLs (e.g. `aljazeera.com/video/newsfeed/2026/5/19/...`)
  stay long.
- `image_sources=<url>|<url>|...` is the REAL list to probe with
  `web_request`. Try them in order. Never invent additional URLs (no
  `artnews.com/...-1234567890`, no `example.com/...`, no guessed article
  paths). If every supplied candidate fails, stop probing and follow the
  backoff rule below — do not roam the web.
- `html=<path>` is the exact publish path. Common WRONG mistakes to avoid:
  `/topics/...` (plural — wrong), or any path you derived from the topic
  name. If `html=/topic/topic_xyz_20260519.html`, publish to that exact
  string and ONLY that string. Same rule for `json=` and `image=`.
- If `source` is missing or empty in your message, publish the fallback
  page WITHOUT a source link rather than inventing one. Better to render
  no link than a fake link.

Publish the exact html/json paths from the latest message before sleeping.
First publish a useful fallback HTML page from the supplied
headline/summary/source and exact `html` path without an image unless a local
image has already been saved.

URL CONVERSION INSIDE THE PUBLISHED HTML: the `image=/media/<id>.jpg` field
is the in-app storage path (always starts with `/`). The topic page lives one
level deeper at `/topic/<id>.html`, so render the image as
`<img src="../media/<id>.jpg">` — drop the leading `/` and prepend `../`.
Same rule for any other in-app path. Reference CSS as `../styles.css` and
link back with `<a href="../index.html">Back</a>`. Never write `href="/foo"`
or `src="/foo"` in published HTML — those would 404 because the browser
resolves them against the domain root, bypassing the `/news_watcher/` app
prefix. Before sleeping 900, obtain the local image.
Read `image_sources` as `|`-separated article URLs and try them in order. Fetch
one candidate at a time; if its HTML contains `og:image`, `twitter:image`, or a
useful `media` image URL, call `save_asset` with that image URL and the supplied
local image path, then continue after `sleep_seconds:5`. After LAST TOOL
RESULTS contains `save_asset ok path=<local_path>`, republish the HTML and JSON
with that local image, send main `image_saved id=<id> path=<local_path>`, and
sleep 900. If `save_asset` fails or a page has no image URL, immediately try
the next candidate source. Never publish remote image URLs. HTML after image:
local image, headline, updated UTC, first-seen UTC, 4 bullets, recent change,
open question, source link, back link `<a href="../index.html">Back</a>`
(relative — the topic page is one level deeper than the index). Reference CSS
with `../styles.css`. If no candidate produced
an image on this attempt, keep the useful fallback page, send main
`image_missing id=<id> tried=<count>`, and sleep with exponential backoff:
`min(60 * 2^count, 900)` seconds — so 60, 120, 240, 480, 900, 900, 900,
900, 900, 900 across attempts 1..10. Track `count` from your own
conversation context (how many image-acquisition attempts you have already
made this cycle). After `count` reaches 10, give up image acquisition for
this cycle: send main `image_missing id=<id> tried=10 gave_up=1`, keep the
imageless fallback page (the dashboard `<img onerror>` hides the missing
file), and sleep 900. The next 15-minute cycle from main will deliver fresh
`image_sources` and reset your attempt budget. Never sleep 900 before
attempt 1 has actually run.
```

Watcher package for both `initial_message` and `send_message`:

```text
id=<id>
parent=main
html=<p>
json=/topic/<id>.json
name=<n>
headline=<h>
summary=<s>
first_seen=<f>
source=<src>
image_sources=<src>|<alt1>|<alt2>|<alt3>|<alt4>|<alt5>
image=/media/<id>.jpg
updated=<u>
interval=900
```

## Initial Instruction

Start now. Fetch current feeds, publish the compact dashboard selection, then
cover watchers in short batches until the current selection is covered.