larkin 0.3.3 → 0.4.2

package/README.md

@@ -1,6 +1,12 @@
-# Larkin
+<p align="center">
+  <img src="./assets/readme/larkin-hero.svg" width="100%" alt="Larkin connecting Codex, Claude Code, and Pi agent runtimes to Feishu with a local dashboard and message surfaces.">
+</p>
 
-Larkin connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It provides a local runtime host, persistent sessions, reminders, interactive messages, and a local dashboard.
+<p align="center">
+  <a href="#quick-start">Quick start</a> · <a href="#requirements">Requirements</a> · <a href="#what-it-does">What it does</a> · <a href="#installation">Installation</a> · <a href="#usage">Usage</a> · <a href="#setup-and-configuration">Setup and configuration</a> · <a href="#details">Details</a> · <a href="#development">Development</a>
+</p>
+
+Larkin is a local Runtime Host that connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It keeps sessions, reminders, interactive messages, and a local dashboard close to the machine that runs them.
 
 ## Requirements
 
@@ -9,9 +15,56 @@ Larkin connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It p
 - At least one supported agent runtime and its authentication
 - Bun 1.3.14 when running the npm package or building from source (standalone binaries bundle their own runtime)
 
+## Quick start
+
+```bash
+npx larkin@latest setup
+npx larkin@latest start
+npx larkin@latest status
+```
+
+## What it does
+
+<table>
+<tr>
+<td valign="top">
+
+**Runtime host**
+
+Connect supported coding-agent runtimes to Feishu from one local process.
+
+</td>
+<td valign="top">
+
+**Persistent workflow**
+
+Keep sessions and reminders available across runs.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**Message surfaces**
+
+Work with Feishu messages, interactive cards, and related automation.
+
+</td>
+<td valign="top">
+
+**Local visibility**
+
+Inspect the host through the embedded dashboard and OpenTelemetry traces.
+
+</td>
+</tr>
+</table>
+
+The rest of this document uses the short `larkin` form; it works as-is after `npm install -g larkin`, or prefix any command with `npx larkin@latest` to run it without installing.
+
 ## Installation
 
-Larkin is published to the npm registry and also distributed as standalone binaries. Prefer npm:
+Prefer npm:
 
 ```bash
 # Run the latest version directly with npx — no install step, always the newest release
@@ -26,39 +79,24 @@ Standalone binaries for macOS, Linux, and Windows (x64) are attached to every [G
 
 ## Usage
 
-```bash
-npx larkin@latest setup
-npx larkin@latest start
-npx larkin@latest status
-```
-
-The rest of this document uses the short `larkin` form; it works as-is after `npm install -g larkin`, or prefix any command with `npx larkin@latest` to run it without installing.
-
-Run `larkin --help` or `larkin config --help` for the available commands and configuration options. Local configuration is stored under `~/.larkin` by default; set `LARKIN_CONFIG_DIR` to use another directory.
+Run `larkin --help` or `larkin config --help` for the available commands and configuration options. `larkin agents` reports event readiness, reply-scope readiness, subscription mode/status/dimension, arrivals, and read failures. Local configuration is stored under `~/.larkin` by default; set `LARKIN_CONFIG_DIR` to use another directory.
 
 ### Feishu message links
 
 Feishu clients do not reliably render Markdown links such as `[label](URL)` as clickable in text or Markdown messages. When a recipient must be able to open a link, keep the complete bare HTTPS URL visible, for example: Issue 115 — https://github.com/eddiearc/larkin/issues/115. A label may accompany it, but must not replace the bare URL. Larkin does not rewrite exact, verbatim, or user-authored message bodies to enforce this guidance.
 
-During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Pi can use an existing
-official `pi` installation or the official Pi runtime bundled in Larkin. The bundled option supports
-DeepSeek, Kimi/Moonshot, MiniMax, Zhipu/BigModel, and a custom OpenAI-compatible Base URL. Provider keys
-are stored only in the selected Agent's private provider directory, not in the ordinary Agent config. Setup
-also discovers every API-key and OAuth/subscription login exposed by the pinned official Pi registry and
-delegates those flows to Pi. Use `larkin pi-auth status` or `larkin pi-auth logout <provider>` to manage them.
-The builtin Pi runtime loads Larkin's two supported extensions inline: background subagents and the 60-second
-foreground bash timeout guard are enabled without writing extension files or arguments. A compatible external
-Pi installation keeps the existing explicit `-e` extension path.
+## Setup and configuration
+
+During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Provider keys are stored only in the selected Agent's private provider directory, not in the ordinary Agent config. Setup also discovers every API-key and OAuth/subscription login exposed by the pinned official Pi registry and delegates those flows to Pi.
+
+Use `larkin pi-auth status` or `larkin pi-auth logout <provider>` to manage Pi auth. The builtin Pi runtime loads Larkin's two supported extensions inline: background subagents and the 60-second foreground bash timeout guard are enabled without writing extension files or arguments. A compatible external Pi installation keeps the existing explicit `-e` extension path.
 
-### Windows support boundary and optional autostart
+<details>
+<summary>Windows support and optional autostart</summary>
 
-Windows 11 x64 core support covers the standalone CLI, local Runtime Host startup, builtin Pi RPC with the
-inline extensions above, and the embedded Dashboard. Provider authentication, the official `lark-cli`, and
-external Codex, Claude Code, or Pi executables remain separately installed dependencies; secret-bearing live
-channel/provider tests are intentionally outside the hosted Windows CI gate.
+Windows 11 x64 core support covers the standalone CLI, local Runtime Host startup, builtin Pi RPC with the inline extensions above, and the embedded Dashboard. Provider authentication, the official `lark-cli`, and external Codex, Claude Code, or Pi executables remain separately installed dependencies; secret-bearing live channel/provider tests are intentionally outside the hosted Windows CI gate.
 
-An Administrator account can optionally start Larkin at that account's interactive logon with Task Scheduler.
-From an elevated PowerShell prompt, adjust the executable and working-directory paths first:
+An Administrator account can optionally start Larkin at that account's interactive logon with Task Scheduler. From an elevated PowerShell prompt, adjust the executable and working-directory paths first:
 
 ```powershell
 $Exe = 'C:\Tools\Larkin\larkin.exe'
@@ -69,13 +107,13 @@ Register-ScheduledTask -TaskName 'Larkin Runtime Host' -Action $Action -Trigger
   -Description 'Start Larkin for this Administrator account at logon' -RunLevel Highest
 ```
 
-This is an optional per-user Administrator-logon task, not SYSTEM boot support or a Windows service. Keep the
-account profile available because Larkin stores its state there. Release executables are currently unsigned;
-normal Windows security policy and SmartScreen decisions still apply.
+This is an optional per-user Administrator-logon task, not SYSTEM boot support or a Windows service. Keep the account profile available because Larkin stores its state there. Release executables are currently unsigned; normal Windows security policy and SmartScreen decisions still apply.
+</details>
 
-For supported Feishu cloud-document comments (`doc`, `docx`, `sheet`, and `file`), the safe default accepts only comments or replies that @ the Bot. Document comments never reuse IM `require`/`free` settings. An explicit platform-verified application-dimension Bot subscription accepts every supported comment event that Feishu actually delivers, whether or not it mentions the Bot. Larkin stores accepted comments as `kind=document_comment` canonical Inbox events and wakes the Bot's persistent Agent. Replies are bound back to the exact comment; whole-document comments use Feishu's top-level fallback. `larkin setup --comment-subscription application` makes the broad trigger surface explicit, creates the Bot subscription through the official `lark-cli` structured API, and then verifies it with the read-only platform status API. `--comment-subscription none` explicitly removes that application subscription and verifies removal. Until positive status verification, only @Bot comments enter the Inbox. Setup requests `docs:document.comment:create` for both in-thread replies and whole-document `create_v2` fallback, while retaining `drive:drive` for event/read support. `larkin agents` reports event readiness, reply-scope readiness, subscription mode/status/dimension, arrivals, and read failures.
+## Details
 
-## OpenTelemetry traces
+<details>
+<summary>OpenTelemetry traces</summary>
 
 Larkin records a privacy-safe timing waterfall for each woken Feishu message. Tracing is always enabled, and ended spans first enter a durable local OTLP/HTTP JSON spool. Message processing therefore does not depend on an observability backend being reachable.
 
@@ -136,6 +174,7 @@ larkin.message.process
 ```
 
 The compose stack binds Grafana, Tempo, and OTLP only to `127.0.0.1` and persists `/data`. It is intended for development, demos, and testing. Do not expose its default credentials or plaintext OTLP port publicly; use a deployment-owned TLS/authenticated endpoint or private network for remote automatic upload.
+</details>
 
 ## Development
 

package/assets/readme/larkin-hero.svg

@@ -0,0 +1,111 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="400" viewBox="0 0 1200 400" role="img" aria-labelledby="title desc">
+  <title id="title">Larkin local runtime host</title>
+  <desc id="desc">A project-native hero showing Codex, Claude Code, and Pi connecting through Larkin to Feishu, reminders, interactive messages, and a local dashboard.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#07111f"/>
+      <stop offset="100%" stop-color="#0c1730"/>
+    </linearGradient>
+    <radialGradient id="glow-cyan" cx="0" cy="0" r="1">
+      <stop offset="0%" stop-color="#00b8d9" stop-opacity="0.34"/>
+      <stop offset="100%" stop-color="#00b8d9" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow-blue" cx="0" cy="0" r="1">
+      <stop offset="0%" stop-color="#1456f0" stop-opacity="0.28"/>
+      <stop offset="100%" stop-color="#1456f0" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="core" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#11284f"/>
+      <stop offset="100%" stop-color="#0e1f3f"/>
+    </linearGradient>
+    <linearGradient id="pill" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#11203f"/>
+      <stop offset="100%" stop-color="#0b1528"/>
+    </linearGradient>
+    <pattern id="grid" width="36" height="36" patternUnits="userSpaceOnUse">
+      <path d="M 36 0 L 0 0 0 36" fill="none" stroke="#ffffff" stroke-opacity="0.04" stroke-width="1"/>
+    </pattern>
+  </defs>
+
+  <rect width="1200" height="400" rx="28" fill="url(#bg)"/>
+  <rect width="1200" height="400" rx="28" fill="url(#grid)"/>
+  <circle cx="140" cy="60" r="230" fill="url(#glow-cyan)"/>
+  <circle cx="1080" cy="52" r="260" fill="url(#glow-blue)"/>
+  <circle cx="1010" cy="340" r="220" fill="url(#glow-cyan)" opacity="0.45"/>
+
+  <g id="title-block" transform="translate(56 56)" fill="#f7fbff" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif">
+    <text x="0" y="0" font-size="16" font-weight="700" letter-spacing="3.4" fill="#8fb7d8">LOCAL RUNTIME HOST</text>
+    <text x="0" y="80" font-size="76" font-weight="800" letter-spacing="-1.8">Larkin</text>
+    <text x="0" y="128" font-size="30" font-weight="600" fill="#d9e8ff">Connect Codex, Claude Code, and Pi</text>
+    <text x="0" y="166" font-size="30" font-weight="600" fill="#d9e8ff">to Feishu with one local host.</text>
+    <text x="0" y="210" font-size="20" font-weight="500" fill="#9cb4cf">Persistent sessions · reminders · interactive messages · local dashboard</text>
+
+    <g transform="translate(0 238)" font-size="18" font-weight="700" fill="#ecf4ff">
+      <rect x="0" y="0" width="138" height="38" rx="19" fill="#0f1b33" stroke="#223556"/>
+      <text x="69" y="24" text-anchor="middle">npm package</text>
+      <rect x="150" y="0" width="176" height="38" rx="19" fill="#0f1b33" stroke="#223556"/>
+      <text x="238" y="24" text-anchor="middle">standalone binaries</text>
+      <rect x="338" y="0" width="150" height="38" rx="19" fill="#0f1b33" stroke="#223556"/>
+      <text x="413" y="24" text-anchor="middle">Bun 1.3.14</text>
+    </g>
+
+    <g transform="translate(0 292)">
+      <rect x="0" y="0" width="408" height="48" rx="14" fill="#07111f" stroke="#244068"/>
+      <text x="18" y="31" font-size="18" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" fill="#8ff0ff">npx larkin@latest setup</text>
+      <text x="240" y="31" font-size="18" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" fill="#8fb7d8">→ start → status</text>
+    </g>
+  </g>
+
+  <g id="project-proof" transform="translate(706 50)" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif">
+    <rect x="0" y="0" width="444" height="300" rx="26" fill="#0b162b" fill-opacity="0.92" stroke="#2a3f63"/>
+    <text x="24" y="34" font-size="16" font-weight="700" letter-spacing="2.6" fill="#8fb7d8">RUNTIME GRAPH</text>
+
+    <g fill="#eff6ff" font-size="17" font-weight="700">
+      <rect x="24" y="74" width="120" height="44" rx="22" fill="url(#pill)" stroke="#264267"/>
+      <text x="84" y="101" text-anchor="middle">Codex</text>
+
+      <rect x="24" y="136" width="120" height="44" rx="22" fill="url(#pill)" stroke="#264267"/>
+      <text x="84" y="163" text-anchor="middle">Claude Code</text>
+
+      <rect x="24" y="198" width="120" height="44" rx="22" fill="url(#pill)" stroke="#264267"/>
+      <text x="84" y="225" text-anchor="middle">Pi</text>
+    </g>
+
+    <g stroke-linecap="round" fill="#eff6ff">
+      <path d="M144 96 C 196 96, 220 118, 252 132" stroke="#00b8d9" stroke-opacity="0.76" stroke-width="3"/>
+      <path d="M144 158 C 196 158, 220 154, 252 150" stroke="#1456f0" stroke-opacity="0.76" stroke-width="3"/>
+      <path d="M144 220 C 196 220, 220 186, 252 168" stroke="#a3402c" stroke-opacity="0.72" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 122, 328 108" stroke="#00b8d9" stroke-opacity="0.42" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 156, 328 156" stroke="#1456f0" stroke-opacity="0.42" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 192, 328 214" stroke="#a3402c" stroke-opacity="0.42" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 232, 328 266" stroke="#8fb7d8" stroke-opacity="0.42" stroke-width="3"/>
+    </g>
+
+    <g>
+      <rect x="252" y="92" width="70" height="116" rx="26" fill="url(#core)" stroke="#00b8d9" stroke-opacity="0.7"/>
+      <rect x="266" y="108" width="42" height="18" rx="9" fill="#0b162b" stroke="#27456f"/>
+      <text x="287" y="122" text-anchor="middle" font-size="10" font-weight="800" fill="#8fb7d8" letter-spacing="1.6">CORE</text>
+      <text x="287" y="158" text-anchor="middle" font-size="24" font-weight="800" fill="#f7fbff">LARKIN</text>
+      <text x="287" y="181" text-anchor="middle" font-size="12" font-weight="600" fill="#9cb4cf">local host</text>
+    </g>
+
+    <g fill="#eff6ff" font-size="15" font-weight="700">
+      <rect x="328" y="92" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="113" text-anchor="middle">Feishu</text>
+
+      <rect x="328" y="144" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="165" text-anchor="middle">Cards</text>
+
+      <rect x="328" y="196" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="217" text-anchor="middle">Reminders</text>
+
+      <rect x="328" y="248" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="269" text-anchor="middle">Dashboard</text>
+    </g>
+
+    <g>
+      <rect x="24" y="254" width="214" height="26" rx="13" fill="#07111f" stroke="#244068"/>
+      <text x="38" y="272" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" fill="#8fb7d8">sessions + traces + local config</text>
+    </g>
+  </g>
+</svg>