@hanamorilabs/tab 0.1.14 → 0.1.16

package/dist/tab-docs.js

@@ -35,11 +35,11 @@ export const TAB_COMMANDS = [
     {
         name: "use",
         group: "start",
-        usage: ["use"],
-        summary: "Pick or change the Agent this folder runs as.",
+        usage: ["use", "use claude|codex|grok|kimi"],
+        summary: "Pick or change the Agent this folder runs a harness as.",
         details: [
-            "Lists the flock's Agents (state, kind, cap) and lets you choose one or make a new one. A new Agent asks for its kind: API key or Subscription. The choice is written to a one-line .flocktab file at the git root (or this folder), and a key for that Agent is minted and kept on this machine.",
-            "Running tab claude or tab codex in a folder with no .flocktab asks the same question, so tab use is only needed to change the answer.",
+            "An Agent is one harness on one project. tab claude and tab codex in the same folder are two Agents (that is what the plan counts), each asked for once: the first run of a harness in a folder lists the flock's Agents of that harness (and untied ones it can tie), or makes a new one named after the folder (its slug is <folder>-<harness>, since a project's Claude and Codex Agents are two) and asks its kind. The choice goes into .flocktab at the git root, one entry per harness, and a key for that Agent is minted and kept on this machine.",
+            "tab use codex changes the answer for one harness; bare tab use sets the folder's default, which every other command (tab python …) runs as. An older .flocktab with a single Agent applies to every harness until one is set apart.",
             "An Agent that already holds a key on another machine can be used here too, but minting a key here replaces the one there. tab asks before doing it.",
         ],
         see: ["agent", "key", "list"],
@@ -50,18 +50,20 @@ export const TAB_COMMANDS = [
         aliases: ["codex", "grok", "kimi", "gemini", "aider", "cursor", "<command>"],
         group: "run",
         usage: ["claude [args]", "codex [args]", "grok [args]", "kimi [args]", "<any command> [args]"],
-        summary: "Run an agent on this folder's tab. Everything after the name goes to the agent untouched.",
+        summary: "Run an agent on this folder's tab. Harness arguments pass through after tab's run options.",
         details: [
             "tab sets the environment that agent reads (its base URL and key, or for Codex a home folder of its own) and starts it. It does not wrap or parse the agent's traffic; the proxy does the gating.",
             "On an API-key Agent the agent presents the tab's key, the flock's provider key pays, and every call is held, settled and charged to the cap. A call that would pass the cap is refused before the provider with 402 tab_closed.",
             "On a Subscription Agent the agent keeps its own login (Claude Max, ChatGPT, SuperGrok, Kimi). The tab key rides in the base URL, the same kill switch and policies apply before the vendor is reached, the call is recorded at list price under the account the vendor names, and nothing is charged to the cap.",
             "Any other command works too: tab points both the OpenAI and the Anthropic variables at the proxy and runs it. An agent with no consumer plan on a Subscription Agent runs metered on the flock's key, and tab says so.",
             "With logins in the pool for that vendor, a Subscription Agent runs as the login with most room. See tab pool.",
+            "Opt in with tab claude --observe or tab codex --observe to show native sessions, workers and observed messages in Observability. Review and trust the added hooks in the harness normally; collection is unavailable if hooks are skipped. Only identifiers, timestamps and tool outcomes leave the machine, never prompts, message bodies or transcripts. A successful send is not a read receipt. Collection is experimental: Claude 2.1.278+ in the 2.1 family and Codex 0.155.1+ in the 0.155 family, on macOS/Linux. Offline metadata is bounded and retried on another observed launch of the same Agent; inactive queues older than seven days are removed on the next observed launch, and overflow is counted as a coverage gap.",
         ],
         options: [
             { flag: "--as <login>", what: "run as one pool login and never move off it" },
             { flag: "--no-pool", what: "ignore the pool and use the agent's usual login" },
             { flag: "--pool", what: "require the pool; fail rather than fall back when it cannot be used" },
+            { flag: "--observe", what: "opt in to metadata-only native communication hooks for this Claude/Codex launch; put before --" },
         ],
         examples: [
             { cmd: "tab claude", what: "Claude Code on this folder's tab" },
@@ -91,18 +93,22 @@ export const TAB_COMMANDS = [
         name: "agent",
         overview: "agent create | kind",
         group: "agents",
-        usage: ["agent create <name> --subscription|--api [--cap <dollars>]", "agent kind <agent> api|subscription"],
-        summary: "Make an Agent of a given kind, or change an Agent's kind.",
+        usage: ["agent create <name> --subscription|--api [--harness claude|codex|grok|kimi] [--cap <dollars>]", "agent kind <agent> api|subscription", "agent harness <agent> claude|codex|grok|kimi|any"],
+        summary: "Make an Agent, or change its kind or harness.",
         details: [
-            "An Agent is one named worker with one tab. Its kind is the only thing anyone declares: api means the flock's provider key pays and the cap is the meter; subscription means its agents use your own plan logins and nothing is charged.",
+            "An Agent is one harness on one project, with one tab. Two things are declared: its kind (api: the flock's provider key pays and the cap is the meter; subscription: your own plan logins, nothing charged) and its harness (claude, codex, grok, kimi, or any for scripts). The proxies enforce the harness: a Claude Agent's key cannot pass a Codex login through (403 wrong_harness), so Claude and Codex on one folder are two Agents and count as two.",
+            "A subscription Agent's cap is never touched, so tab list shows none; its tab is the kill switch.",
             "Changing the kind applies to the next launch. tab claude reads it fresh every time.",
         ],
         options: [
             { flag: "--subscription | --api", what: "the kind of the new Agent (api when neither is given)" },
             { flag: "--cap <dollars>", what: "the new Agent's cap; 50 when left out" },
+            { flag: "--harness claude|codex|grok|kimi", what: "which harness this Agent is; any when left out" },
         ],
         examples: [
             { cmd: "tab agent create billing-api --api --cap 20", what: "a metered Agent with a $20 cap" },
+            { cmd: "tab agent create dash-f4f-codex --subscription --harness codex", what: "a Codex Agent for the dash folder" },
+            { cmd: "tab agent harness dash-f4f codex", what: "tie an untied Agent to Codex" },
             { cmd: "tab agent create my-laptop --subscription", what: "an Agent for your own plan logins" },
             { cmd: "tab agent kind billing-api subscription", what: "switch an existing Agent" },
         ],
@@ -216,7 +222,7 @@ export const TAB_COMMANDS = [
         summary: "Every plan login your Subscription Agents were seen on, and how used it is.",
         details: [
             "Accounts are discovered, never typed in: the vendor names the login on every reply, and FlockTab files the call under it. Each row shows the plan, the seat price taken from the plan tier, what the last 30 days would have cost at list price, the number of calls, and the usage the vendor last reported per window.",
-            "The console shows the same under Spend, Subscriptions; a label or a seat price of your own is set under Control, Accounts.",
+            "The console shows the same under Control, Subscriptions, where a label or a seat price of your own is set.",
         ],
         see: ["pool", "agent"],
     },
@@ -264,6 +270,22 @@ export const TAB_COMMANDS = [
         details: ["The first thing to run when something is off. Exit code 0 only when the machine is logged in, the folder has an Agent with a key here, and the proxy is healthy."],
         see: ["login", "use", "up"],
     },
+    {
+        name: "statusline",
+        overview: "statusline [harness]",
+        group: "watch",
+        usage: ["statusline [claude|codex|grok|kimi]", "statusline install grok|kimi"],
+        summary: "One line for a harness's status bar: the Agent and its tab, or the plan's windows.",
+        details: [
+            "Prints what this folder runs the harness as, then either spent of cap for an API-key Agent or, for a subscription, the login in use and each window's usage as the vendor last reported it (5h 36% · 7d 29%). Read from the console at most once a minute, so a status bar that refreshes every few seconds costs nothing.",
+            "Claude Code shows it on every tab claude, passed on the command line so no file of yours is touched (your own --settings wins). Grok Build and Kimi Code read a status line only from their config; a pool member gets it (that home is tab's), and tab statusline install grok|kimi adds it to your own config after asking. Codex takes no command and already shows its own limits.",
+        ],
+        examples: [
+            { cmd: "tab statusline claude", what: "the line, as Claude Code's status bar would show it" },
+            { cmd: "tab statusline install grok", what: "add it to ~/.grok/config.toml" },
+        ],
+        see: ["status", "accounts"],
+    },
     {
         name: "log",
         overview: "log [-f] | log --proxy",
@@ -300,14 +322,18 @@ export const TAB_COMMANDS = [
     {
         name: "spend",
         group: "watch",
-        usage: ["spend [agent|project|day]"],
-        summary: "What was spent through the tab, and outside it, grouped.",
-        details: ["Meter spend is what went through FlockTab. Outside spend is what the connected billing sources report (Team plan and up), so the two can be told apart."],
+        usage: ["spend [agent|project|day|model]"],
+        summary: "What was spent through the tab, and outside it, grouped: by Agent, project, day, or model and effort.",
+        details: [
+            "Meter spend is what went through FlockTab. Outside spend is what the connected billing sources report (Team plan and up), so the two can be told apart.",
+            "tab spend model lists each model with the reasoning effort the requests asked for (OpenAI's reasoning effort, Anthropic's effort or thinking budget) and the speed tier (fast, priority, flex), how many calls, what they cost and how they were paid: charged to a tab, or priced at list on a plan. The console shows the same under Spend, Models.",
+        ],
         options: [
-            { flag: "--by agent|project|day", what: "how to group" },
+            { flag: "--by agent|project|day|model", what: "how to group" },
             { flag: "--since 7d", what: "how far back" },
             { flag: "--agent <agent>", what: "only one Agent" },
         ],
+        examples: [{ cmd: "tab spend model --since 30d", what: "a month per model and effort" }],
         see: ["outside", "ledger"],
     },
     {
@@ -375,7 +401,8 @@ export const TAB_COMMANDS = [
 /** What is what. Alphabetical in the docs; grouped by subject here. */
 export const TAB_GLOSSARY = [
     { term: "Flock", meaning: "Your workspace: many Agents, one plan, one ledger. Each console login has its own." },
-    { term: "Agent", meaning: "One named worker, such as billing-api or my-laptop. It has exactly one tab, one kind, and its own keys, policies and history. Plans count Agents." },
+    { term: "Agent", meaning: "One harness on one project, such as dash-f4f-claude. It has exactly one tab, one kind, one harness, and its own keys, policies and history. Claude and Codex on the same folder are two Agents. Plans count Agents." },
+    { term: "Harness", also: ["claude", "codex", "grok", "kimi", "any"], meaning: "Which coding agent an Agent is for. Set when the Agent is made; the proxies refuse a call from another harness before the vendor (403 wrong_harness). any is a script or unknown agent: metered only, never a subscription passthrough." },
     { term: "Tab", meaning: "An Agent's spend account: a hard dollar cap, a window, and a state, open or closed. Closing the tab is the kill switch." },
     { term: "Kind", also: ["api", "subscription"], meaning: "What pays for an Agent's tokens. api: the flock's provider key, every call charged to the cap. subscription: your own plan login, gated and recorded but never charged. Chosen when the Agent is made; it can be changed." },
     { term: "Cap", meaning: "The most an Agent may spend in one window, in dollars. Hard: a call that would pass it is refused before the provider. There is no overage." },
@@ -402,12 +429,13 @@ export const TAB_GLOSSARY = [
     { term: "Pool", meaning: "Several logins of one vendor on one machine, and tab choosing between them by reported usage. Each member is a folder the agent signs in to itself." },
     { term: "Threshold", meaning: "In the pool: the share of the short window at which a login gives way to one with more room. 80% unless set, per vendor if you like." },
     { term: "Weekly guard", meaning: "In the pool: the share of the long window from which a login gives way whatever its short window says. 95% unless set. Below it the weekly window is ignored." },
-    { term: "Account switch", meaning: "An Agent's call landing on a different account of the same vendor than its previous one: a new login mid-session, another machine, or the pool moving. Shown on the Agent's page and under Accounts." },
+    { term: "Account switch", meaning: "An Agent's call landing on a different account of the same vendor than its previous one: a new login mid-session, another machine, or the pool moving. Shown on the Agent's page and under Control, Subscriptions." },
     { term: "Project", meaning: "A label grouping Agents for chargeback on FlockTab's own meter, optionally linked to a GitHub repository. Team plan and up." },
     { term: "Outside spend", meaning: "Money that did not go through a tab, read from provider admin APIs and cloud billing, so it can be told apart from metered spend. Team plan and up." },
+    { term: "Tier", also: ["service tier", "fast mode", "speed"], meaning: "A speed the request asked for, in the request's own words: OpenAI's and xAI's service_tier (fast, priority, flex), Anthropic's speed (fast). Vendors price these apart, so it is kept on every call and shown beside the model on the ledger and under Spend, Models." },
+    { term: "Effort", also: ["reasoning effort", "thinking budget"], meaning: "How hard a request asked the model to think, in the request's own words: OpenAI's reasoning effort (low, medium, high, xhigh), Anthropic's effort or a thinking budget in tokens. Kept on every call, shown on the ledger and under Spend, Models, because it is where the money goes." },
     { term: "Ledger", meaning: "Every decision, one row per call: allowed, settled, refunded, blocked and why. Money is whole cents, never a fraction. If the ledger cannot be reached, no call goes out." },
     { term: "Fail closed", meaning: "When FlockTab cannot be sure a call fits (the ledger is down, the key is unknown, the unlock is missing) the call is refused rather than let through." },
-    { term: "Harness", meaning: "The coding agent you run: Claude Code, Codex, Grok Build, Kimi Code, or any command. tab calls them agents in its output." },
     { term: ".flocktab", meaning: "A one-line file at a project's root naming the Agent that folder runs as. Safe to commit: it holds no key." },
     { term: "~/.flocktab", meaning: "This machine's tab folder: the session and Agent keys (config.json), the pool (pool.json), the self-hosted proxy's keys, log and binary, and the alias shims. Owner-only." },
 ];
@@ -419,6 +447,7 @@ export const TAB_ERRORS = [
     { status: 403, code: "model_blocked", when: "The model is not on the Agent's allowlist.", fix: "tab policy --models ..., or none to allow any." },
     { status: 403, code: "agent_frozen", when: "The Agent was frozen from the console.", fix: "Frozen by FlockTab support or an admin rule; write to support." },
     { status: 403, code: "not_subscription", when: "A passthrough (/t/...) call for an API-key Agent.", fix: "tab agent kind <agent> subscription, or run it metered." },
+    { status: 403, code: "wrong_harness", when: "A passthrough for another harness than the Agent's: a Claude Agent's key with a Codex login, or an untied Agent with any login.", fix: "Run tab <harness> in the folder and pick or make that harness's Agent; or tab agent harness <agent> <harness>." },
     { status: 429, code: "velocity", when: "More calls this minute than the policy allows.", fix: "Wait, or tab policy --velocity N." },
     { status: 401, code: "key_revoked", when: "The key is unknown, rotated or missing.", fix: "tab key rotate mints a fresh one on this machine." },
     { status: 503, code: "ledger_unavailable", when: "FlockTab could not reach its ledger. Nothing was sent to the provider.", fix: "Retry. This is fail closed on purpose." },

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Written by scripts/write-version.mjs from package.json at build; `tab version` prints it. */
-export const TAB_VERSION = "0.1.14";
+export const TAB_VERSION = "0.1.16";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamorilabs/tab",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Run any AI agent on a FlockTab tab: tab claude, tab codex, tab <command>.",
   "license": "MIT",
   "type": "module",
@@ -22,11 +22,11 @@
     "prepublishOnly": "pnpm build"
   },
   "optionalDependencies": {
-    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.9",
-    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.9",
-    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.9",
-    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.9",
-    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.9"
+    "@hanamorilabs/flocktab-proxy-darwin-arm64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-darwin-x64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-linux-x64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-linux-arm64": "0.1.12",
+    "@hanamorilabs/flocktab-proxy-win-x64": "0.1.12"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",