@gobing-ai/knowledge-kit 0.0.35 → 0.0.37

package/plugins/ingestions/web-search/package.json

@@ -12,6 +12,6 @@
         "@gobing-ai/ts-utils": "catalog:"
     },
     "devDependencies": {
-        "@types/bun": "1.3.14"
+        "@types/bun": "1.4.3"
     }
 }

package/plugins/kk/README.md

@@ -30,11 +30,22 @@ keeps its existing name — that is a workflow stem, not an installable agent ca
 
 ## Schedule
 
-`spur` **has no scheduler**, so kk ships templates and `kk schedule render` prints the artifact for
-the platform — **installing it is an operator action** (kk never writes a crontab or a
+`spur serve` **hosts the scheduler**: the `.spur/config.yaml` `bootstrap.scheduler` jobs (the daily
+`kk-daily-ai-voice` tick) are enqueued by the job worker that lives inside the server, so the server
+itself is what must be kept alive. kk ships the templates and `kk schedule render` prints the
+artifact for the platform — **installing it is an operator action** (kk never writes a crontab or a
 `LaunchAgents` plist):
 
 ```bash
+# kk-serve: keep the spur server — and therefore the scheduler that fires the daily pipeline —
+# running whenever you are logged in. kk-serve is launchd-only (cron cannot restart a dead
+# server): `--platform cron` exits 1 instead of printing a line that cannot do the job.
+mkdir -p "$PWD/.works/spur-serve"
+kk schedule render kk-serve --platform launchd --repo "$PWD" \
+  > ~/Library/LaunchAgents/ai.gobing.spur-serve.plist
+launchctl bootout gui/$(id -u)/ai.gobing.spur-serve 2>/dev/null || :
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.gobing.spur-serve.plist
+
 # launchd (macOS): every 6 h at 04:00/10:00/16:00/22:00 local (StartCalendarInterval), one shared log
 # 1. the log directory must exist — launchd opens StandardOutPath but never creates its parent
 mkdir -p "$PWD/.works/kk-collect"
@@ -59,8 +70,24 @@ also carries an absolute `Program` (`{{home}}/.bun/bin/spur`) while keeping `Pro
 frozen argv. Set both to wherever `spur`/`bun` actually live, and `mkdir -p` the log directory first
 (cron's `>>` aborts before the command runs when its directory is missing).
 
+Both artifacts **also bind `TYPESAFE_API_KEY` from the environment `kk schedule render` runs in**, so
+render from a shell that has it. `kk store label` consults the `typesafe` decision maker for
+`kk-item-china-politics`/`-sensitivity`/`-audience`, spur keeps that credential env-only, and a
+scheduled job inherits nothing from your shell: without the key those labels degrade to their
+fail-closed defaults (`china-politics` = 3), the `ai-news` extract profile's `lte: 1` gate drops the
+whole day, and the daily run closes as no-content. A render without the key is still valid — the
+value is simply empty, which spur reads as "not set". The rendered artifact carries a live
+credential: keep it in `~/Library/LaunchAgents` (or your crontab), never in a committed file.
+
 `kk-collect` collects every ingestion source into the kk store and never publishes. Two ticks that
 overlap are **one** collection: the first state takes `kk store lock acquire --name collect` and a
 tick that finds the claim inside its TTL exits 0 (`skipped`) without collecting. Before relying on
 the schedule, check the store is reachable from the scheduled checkout (`kk store migrate`), and
 `tail -f "$PWD/.works/kk-collect/launchd.log"` after the first launch.
+
+The `kk-serve` plist keeps the same `Label` (`ai.gobing.spur-serve`) as the hand-installed one, so
+re-rendering replaces it in place instead of starting a second server on port 3003. It carries the
+same PATH + `TYPESAFE_API_KEY` block, plus `RunAtLoad`, `KeepAlive` and `ThrottleInterval` 10 — its
+`spur serve --cwd <repo> --host 127.0.0.1 --port 3003 --no-open` stdout/stderr goes to
+`$PWD/.works/spur-serve/serve.log`, and the scheduler's registration line lands in
+`$PWD/.spur/logs/spur.log` (never in `serve.log`).

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.0.35",
+    "version": "0.0.37",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }

package/plugins/kk/schedules/cron.tmpl

@@ -12,4 +12,12 @@
 # `mkdir -p` + an explicit PATH are load-bearing, not decoration: cron runs with a minimal PATH (no
 # `spur`/`kk`/`jq`/`bun`) and its `>>` redirect fails on a missing directory BEFORE the command runs,
 # so a bare line would produce no log and no tick. The README install steps mirror this.
-0 4,10,16,22 * * * cd {{repo}} && mkdir -p .works/kk-collect && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" spur workflow run plugins/kk/workflows/kk-collect.yaml >> {{repo}}/.works/kk-collect/launchd.log 2>&1
+#
+# TYPESAFE_API_KEY is bound by `kk schedule render` from the environment it runs in, for the same
+# reason PATH is: `kk store label` consults the `typesafe` decision maker, spur keeps that credential
+# env-only, and cron inherits nothing from the operator's shell — without it every typesafe label
+# degrades to its fail-closed default and the daily pool comes back empty (2026-10-12).
+#
+# shortcut: the value is single-quoted verbatim, so it must not contain a literal `'` — true of the
+# apikey_<hex>_<hex> form; escape it here (or move to a wrapper script) if a credential ever can.
+0 4,10,16,22 * * * cd {{repo}} && mkdir -p .works/kk-collect && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" TYPESAFE_API_KEY='{{typesafe_api_key}}' spur workflow run plugins/kk/workflows/kk-collect.yaml >> {{repo}}/.works/kk-collect/launchd.log 2>&1

package/plugins/kk/schedules/kk-serve.launchd.plist.tmpl

@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- kk-serve — keeps the knowledge-kit Spur server alive whenever this user is logged in.
+
+     WHY the keepalive is not optional: the daily job `kk-daily-ai-voice` (cron `30 4 * * *`) is
+     enqueued by the job worker that lives INSIDE `spur serve` (`.spur/config.yaml`
+     `bootstrap.scheduler`). On 2026-10-12 that process was SIGTERM'd at 00:17 local and not
+     restarted until 10:00, so the 04:30 tick never fired and the day produced no episode at all —
+     no workspace, no ledger row, no run record. `crontab -l` is empty and nothing else supervises
+     it, so an unsupervised server is a silently missed day. RunAtLoad brings it up at login;
+     KeepAlive restarts it on crash; ThrottleInterval bounds the restart rate.
+
+     Rendered by `kk schedule render kk-serve --platform launchd --repo <checkout>`; kk never
+     installs it. Operator action (plugins/kk/README.md §Schedule):
+
+         mkdir -p "$PWD/.works/spur-serve"
+         kk schedule render kk-serve --platform launchd --repo "$PWD" \
+           > ~/Library/LaunchAgents/ai.gobing.spur-serve.plist
+         launchctl bootout gui/$(id -u)/ai.gobing.spur-serve 2>/dev/null || :
+         launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.gobing.spur-serve.plist
+
+     launchd only, deliberately: cron has no keepalive semantics, so a cron render is refused
+     rather than rendered half-useful. -->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.gobing.spur-serve</string>
+    <!-- Absolute `Program` for the same reason as ai.gobing.kk-collect: launchd resolves a RELATIVE
+         ProgramArguments[0] with its own _PATH_STDPATH (/usr/bin:/bin:/usr/sbin:/sbin) before the
+         job environment exists, so a bare `spur` fails with posix_spawn error 0x2 no matter what
+         PATH this plist sets (man launchd.plist: ProgramArguments). -->
+    <key>Program</key>
+    <string>{{home}}/.bun/bin/spur</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>spur</string>
+        <string>serve</string>
+        <string>--cwd</string>
+        <string>{{repo}}</string>
+        <string>--host</string>
+        <string>127.0.0.1</string>
+        <string>--port</string>
+        <string>3003</string>
+        <string>--no-open</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>{{repo}}</string>
+    <!-- The environment block is load-bearing twice over:
+           - PATH — launchd starts with /usr/bin:/bin:/usr/sbin:/sbin and the scheduler's job worker
+             runs its commands through /bin/sh -c, so bare `spur`, `kk`, `jq` and `bun` must resolve.
+           - TYPESAFE_API_KEY — spur keeps the decision-maker credential env-only, and a server
+             started from launchd inherits nothing from the operator's shell; without the key every
+             `typesafe`-routed decision (kk-item-china-politics, -sensitivity, -audience) falls back
+             fail-closed (china-politics = 3), which empties the ai-news extract pool and makes the
+             daily run close as no-content. `kk schedule render` binds it from the environment it
+             runs in, so render from a shell that has the key.
+
+         The hand-installed plist also bound TYPESAFE_BASE_URL; it is deliberately not part of the
+         shipped template (task 0265 decision D2) — no placeholder exists and no artifact needs it. -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>TYPESAFE_API_KEY</key>
+        <string>{{typesafe_api_key}}</string>
+    </dict>
+    <!-- launchd opens these itself, but never creates the parent: `mkdir -p .works/spur-serve` first. -->
+    <key>StandardOutPath</key>
+    <string>{{repo}}/.works/spur-serve/serve.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{repo}}/.works/spur-serve/serve.log</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>

package/plugins/kk/schedules/launchd.plist.tmpl

@@ -61,11 +61,21 @@
     </array>
     <!-- The job environment applies only AFTER exec, so it is not what resolves `spur` above —
          it is what the workflow's own children need (`kk`, `jq`, `bun` are all `#!/usr/bin/env bun`
-         or PATH-resolved). -->
+         or PATH-resolved).
+
+         TYPESAFE_API_KEY is the same kind of dependency one step further: `kk store label` consults the
+         `typesafe` decision maker for kk-item-china-politics / -sensitivity / -audience, spur keeps that
+         credential env-only, and launchd inherits nothing from the operator's shell. Without it every one
+         of those labels degrades to its fail-closed default (china-politics = 3), the `ai-news` extract
+         profile's `lte: 1` gate then excludes the whole day, and the next `kk-daily-ai-voice` tick finds
+         an empty pool. `kk schedule render` binds it from the environment it runs in, so render from a
+         shell that has the key (2026-10-12). -->
     <key>EnvironmentVariables</key>
     <dict>
         <key>PATH</key>
         <string>{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>TYPESAFE_API_KEY</key>
+        <string>{{typesafe_api_key}}</string>
     </dict>
     <key>StandardOutPath</key>
     <string>{{repo}}/.works/kk-collect/launchd.log</string>