@zgeoff/atc 2.14.0 → 2.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.14.0",
+  "version": "2.15.1",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -24,6 +24,7 @@
     "build:atc-bridge": "bun scripts/build-atc-bridge.ts && oxfmt src/agents/atc-bridge-files.ts && format-codemod --quiet src/agents/atc-bridge-files.ts",
     "build:binaries": "bash scripts/build-binaries.sh",
     "audit": "bun audit",
+    "check:imports": "bun scripts/check-imports.ts",
     "deadcode": "knip",
     "lint": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error",
     "lint:fix": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error --fix",

package/src/agents/agent-adapter.ts

@@ -1,24 +1,9 @@
-import type { HookEvent } from '../daemon/hooks';
+import type { AdapterEvent } from '../protocol/adapter-event';
+import type { HookEvent } from '../protocol/hook-event';
+import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import type { SessionID } from '../shared/session-id';
 
-/**
- * Which agent a session runs under: the key the adapter registry is looked
- * up by. Every agent CLI supplies one, and so does every configured backend
- * that drives a CLI it does not own, so two ids can share one kind.
- */
-export type AgentID = string;
-
-/**
- * Missing and empty values become Claude so a fleet written before the agent
- * column still restores as Claude. Any other string is returned as it stands,
- * registered or not: an id whose adapter is gone must reach the caller intact
- * so the session can be shown and refused, never quietly run as Claude.
- */
-export function toAgentID(raw: unknown): AgentID {
-  return typeof raw === 'string' && raw !== '' ? raw : 'claude';
-}
-
 export interface SpawnOptions {
   readonly prompt: string;
 
@@ -64,26 +49,6 @@ export interface GuestSpawnPlan extends SpawnPlan {
   readonly files: Readonly<Record<string, string>>;
 }
 
-export interface AdapterEvent {
-  kind: 'started' | 'needs-input' | 'turn-done' | 'prompt-submitted' | 'ended' | 'heartbeat';
-  agentSessionID?: AgentSessionID;
-  message?: string;
-
-  // Fuller activity text than message: what the agent last said or was
-  // asked, for briefing. Bounded by the adapter.
-  detail?: string;
-
-  // Opaque handle the adapter can later pull a session name from.
-  nameSource?: string;
-
-  // Claude resume-existence path. Distinct from nameSource: a naming
-  // handle is not a resume gate.
-  transcriptSource?: string;
-
-  // The agent's whole final message for a finished turn; detail holds a bounded preview of it.
-  result?: string;
-}
-
 export interface TranscriptToolUse {
   readonly name: string;
   readonly input: string;

package/src/agents/build-hook-settings.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { AgentID } from './agent-adapter';
+import type { AgentID } from '../shared/agent-id';
 import { buildCLICommand } from './build-cli-command';
 
 /**

package/src/agents/claude-adapter.ts

@@ -1,14 +1,15 @@
 import { existsSync } from 'node:fs';
 import { z } from 'zod';
-import type { HookEvent } from '../daemon/hooks';
+import type { AdapterEvent } from '../protocol/adapter-event';
+import type { HookEvent } from '../protocol/hook-event';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalString } from '../shared/build-optional-string';
 import type { Config } from '../shared/config';
 import { isRecord } from '../shared/report';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 import { toShellArg } from '../shared/to-shell-arg';
+import { truncateDetail } from '../shared/truncate-detail';
 import type {
-  AdapterEvent,
   AgentAdapter,
   AgentProfile,
   GuestPaths,
@@ -31,7 +32,6 @@ import type { ClaudeHeadlessRun } from './make-claude-headless-runner';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { planTypedLineInput } from './plan-typed-line-input';
 import { resolveClaudePermissionMode } from './resolve-claude-permission-mode';
-import { truncateDetail } from './truncate-detail';
 import { writeATCBridge } from './write-atc-bridge';
 import { writeHookSettings } from './write-hook-settings';
 

package/src/agents/codex-adapter.ts

@@ -1,15 +1,16 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
-import type { HookEvent } from '../daemon/hooks';
+import type { AdapterEvent } from '../protocol/adapter-event';
+import type { HookEvent } from '../protocol/hook-event';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalString } from '../shared/build-optional-string';
 import type { Config } from '../shared/config';
 import { isRecord } from '../shared/report';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 import { toShellArg } from '../shared/to-shell-arg';
+import { truncateDetail } from '../shared/truncate-detail';
 import type {
-  AdapterEvent,
   AgentAdapter,
   AgentProfile,
   NameUpdate,
@@ -22,7 +23,6 @@ import { buildArgsWithoutFlags } from './build-args-without-flags';
 import { findFlagValue } from './find-flag-value';
 import { planPastedLineInput } from './plan-pasted-line-input';
 import { resolveAgentHome } from './resolve-agent-home';
-import { truncateDetail } from './truncate-detail';
 
 // Codex's hook payload keys, snake_case. An absent or wrong-typed field
 // parses to undefined rather than failing the payload, so a broken reporter

package/src/agents/gateway-adapter.ts

@@ -1,12 +1,12 @@
-import type { HookEvent } from '../daemon/hooks';
+import type { AdapterEvent } from '../protocol/adapter-event';
+import type { HookEvent } from '../protocol/hook-event';
+import type { AgentID } from '../shared/agent-id';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import type { GatewayConfig } from '../shared/collect-gateways';
 import type { Config } from '../shared/config';
 import { toShellArg } from '../shared/to-shell-arg';
 import type {
-  AdapterEvent,
   AgentAdapter,
-  AgentID,
   AgentProfile,
   HeadlessRunner,
   NameUpdate,

package/src/agents/grok-adapter.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
-import type { HookEvent } from '../daemon/hooks';
+import type { AdapterEvent } from '../protocol/adapter-event';
+import type { HookEvent } from '../protocol/hook-event';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalString } from '../shared/build-optional-string';
 import type { Config } from '../shared/config';
@@ -9,8 +10,8 @@ import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 import { toShellArg } from '../shared/to-shell-arg';
+import { truncateDetail } from '../shared/truncate-detail';
 import type {
-  AdapterEvent,
   AgentAdapter,
   AgentProfile,
   NameUpdate,
@@ -22,7 +23,6 @@ import type {
 import { normalizeHookEventName } from './normalize-hook-event';
 import { planPastedLineInput } from './plan-pasted-line-input';
 import { resolveAgentHome } from './resolve-agent-home';
-import { truncateDetail } from './truncate-detail';
 
 interface GrokSessionHookState {
   latestPromptID?: string;

package/src/agents/start-claude-headless-run.ts

@@ -1,6 +1,6 @@
-import { truncateSummary } from '../daemon/truncate-summary';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
 import { isRecord } from '../shared/report';
+import { truncateSummary } from '../shared/truncate-summary';
 import { buildClaudeQueryOptions } from './build-claude-query-options';
 import type { ClaudeHeadlessRunRequest } from './build-claude-query-options';
 

package/src/client/boot-daemon.ts

@@ -2,17 +2,17 @@ import { spawn as spawnChild } from 'node:child_process';
 import type { ChildProcess } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { toAgentID } from '../agents/agent-adapter';
-import type { AgentID } from '../agents/agent-adapter';
 import { DaemonError } from '../protocol/daemon-error';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { parseDaemonFeatures } from '../protocol/parse-daemon-features';
 import { PROTOCOL_V } from '../protocol/protocol';
+import type { AgentID } from '../shared/agent-id';
 import { daemonPidFile, daemonRecordFile, daemonSocketPath } from '../shared/config';
 import { findDaemonRecord } from '../shared/find-daemon-record';
 import { getBuild } from '../shared/get-build';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
 import { makeSingleFlight } from '../shared/make-single-flight';
+import { toAgentID } from '../shared/to-agent-id';
 import { DaemonClient } from './daemon-client';
 import { formatProtocolMismatch } from './format-protocol-mismatch';
 import type { ProtocolMismatch } from './format-protocol-mismatch';

package/src/client/collect-agent-picks.ts

@@ -1,4 +1,4 @@
-import type { AgentID } from '../agents/agent-adapter';
+import type { AgentID } from '../shared/agent-id';
 import type { Config } from '../shared/config';
 
 export interface AgentPick {

package/src/client/daemon-client.ts

@@ -1,4 +1,6 @@
+import type { DaemonChannel } from '../protocol/daemon-channel';
 import { DaemonError } from '../protocol/daemon-error';
+import { LineDecoder } from '../protocol/line-decoder';
 import { OutboundQueue } from '../protocol/outbound-queue';
 import { PROTOCOL_V, decodeMessage, encodeMessage } from '../protocol/protocol';
 import type { EventMsg, ResponseMsg } from '../protocol/protocol';
@@ -13,16 +15,14 @@ interface Pending {
  * event callback. `open` connects the socket; `sendHello` completes the
  * handshake and must come first.
  */
-export class DaemonClient {
+export class DaemonClient implements DaemonChannel {
   onEvent: (event: EventMsg) => void = () => {};
 
   onClose: () => void = () => {};
 
   private queue: OutboundQueue | null = null;
 
-  private buffer = '';
-
-  private readonly decoder = new TextDecoder();
+  private readonly lines = new LineDecoder();
 
   private nextID = 1;
 
@@ -41,7 +41,7 @@ export class DaemonClient {
       unix: socketPath,
       socket: {
         data(_s, buf) {
-          client.applyChunk(client.decodeChunk(buf));
+          client.applyChunk(buf);
         },
         drain() {
           client.queue?.drain();
@@ -99,25 +99,9 @@ export class DaemonClient {
     this.drainPending('client closed');
   }
 
-  // Decodes with state kept across reads, so a multi-byte character split
-  // between two reads decodes whole.
   // oxlint-disable-next-line prefer-readonly-parameter-types -- a socket read buffer has no readonly form
-  private decodeChunk(buf: Uint8Array): string {
-    return this.decoder.decode(buf, { stream: true });
-  }
-
-  private applyChunk(chunk: string): void {
-    this.buffer += chunk;
-
-    const lines = this.buffer.split('\n');
-
-    this.buffer = lines.pop() ?? '';
-
-    for (const line of lines) {
-      if (line.trim() === '') {
-        continue;
-      }
-
+  private applyChunk(buf: Uint8Array): void {
+    for (const line of this.lines.splitChunk(buf)) {
       this.applyLine(line);
     }
   }

package/src/client/format-overlay-agent-mark.ts

@@ -1,4 +1,4 @@
-import type { AgentID } from '../agents/agent-adapter';
+import type { AgentID } from '../shared/agent-id';
 
 const BUILT_IN_MARKS: Readonly<Record<AgentID, string>> = { grok: 'g', codex: 'x' };
 

package/src/client/index.ts

@@ -1,9 +1,11 @@
 import { match } from 'ts-pattern';
 import { createActor } from 'xstate';
-import type { AgentID } from '../agents/agent-adapter';
-import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from '../daemon/sessions';
+import { countSessionStates } from '../protocol/count-session-states';
 import { DaemonError } from '../protocol/daemon-error';
 import type { EventMsg } from '../protocol/protocol';
+import { sortGroupedSessionViews } from '../protocol/sort-grouped-session-views';
+import { sortSessionViews } from '../protocol/sort-session-views';
+import type { AgentID } from '../shared/agent-id';
 import { loadConfig } from '../shared/config';
 import { makeSingleFlight } from '../shared/make-single-flight';
 import { bootDaemonClient } from './boot-daemon';

package/src/client/pick-tab-target.ts

@@ -1,5 +1,5 @@
-import type { SessionState } from '../daemon/sessions';
-import { sortSessionViews } from '../daemon/sessions';
+import type { SessionState } from '../protocol/session-state';
+import { sortSessionViews } from '../protocol/sort-session-views';
 
 interface TabCandidate {
   readonly id: string;

package/src/client/spawn-picker.ts

@@ -1,6 +1,6 @@
 import { homedir } from 'node:os';
-import type { AgentID } from '../agents/agent-adapter';
 import { DaemonError } from '../protocol/daemon-error';
+import type { AgentID } from '../shared/agent-id';
 import { loadConfig } from '../shared/config';
 import { collectAgentPicks } from './collect-agent-picks';
 import type { AgentPick } from './collect-agent-picks';

package/src/client/to-mirror-session.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { toAgentID } from '../agents/agent-adapter';
-import type { AgentID } from '../agents/agent-adapter';
-import type { SessionState } from '../daemon/sessions';
+import type { SessionState } from '../protocol/session-state';
+import type { AgentID } from '../shared/agent-id';
+import { toAgentID } from '../shared/to-agent-id';
 
 export interface MirrorSession {
   id: string;

package/src/client/ui.ts

@@ -1,6 +1,6 @@
-import type { AgentID } from '../agents/agent-adapter';
-import { PINNED_GROUP_KEY } from '../daemon/sessions';
-import type { SessionState } from '../daemon/sessions';
+import { PINNED_GROUP_KEY } from '../protocol/pinned-group-key';
+import type { SessionState } from '../protocol/session-state';
+import type { AgentID } from '../shared/agent-id';
 import { RESET_INPUT_MODES } from '../shared/reset-input-modes';
 import { formatDir } from './dirs';
 import { formatOverlayAgentMark } from './format-overlay-agent-mark';

package/src/daemon/build-imp-provider.ts

@@ -1,9 +1,10 @@
 import { ImpClientPort } from './imp-client-port';
 import { ImpProvider } from './imp-provider';
+import { readImpToken } from './read-imp-token';
 
 /**
  * The provider of an `imp` target, or the problem that keeps it from one.
- * A problem never includes the token or any other environment value.
+ * A problem never includes a token or any other environment value.
  */
 export interface ImpProviderBuild {
   readonly provider: ImpProvider | null;
@@ -12,13 +13,16 @@ export interface ImpProviderBuild {
 
 /**
  * The provider of target `id` from its `imp` options: `url` is where impd
- * listens, and `tokenEnv` holds the name of the daemon's environment
- * variable that carries the token, so no credential sits in the config.
- * `image`, `memoryMib`, `guestDir`, and `guestATC` pass through. No
- * provider when `url` is missing, so the target lists and refuses every
- * spawn. A `tokenEnv` that is not a non-empty string, or whose variable is
- * unset or empty in `env`, is a problem and leaves no provider; a target
- * without `tokenEnv` calls impd with no token.
+ * listens, and at most one of `tokenEnv` and `tokenFile` gives the token,
+ * so no credential sits in the config. `tokenEnv` holds the name of the
+ * daemon's environment variable that carries the token, read once here.
+ * `tokenFile` holds the path of a file that carries it, read here and again
+ * before each impd call and connection. `image`, `memoryMib`, `guestDir`,
+ * and `guestATC` pass through. No provider when `url` is missing, so the
+ * target lists and refuses every spawn. Both token options, either one not
+ * a non-empty string, an unset or empty variable, or an empty or unreadable
+ * file is a problem and leaves no provider; a target without either calls
+ * impd with no token.
  */
 export function buildImpProvider(
   id: string,
@@ -26,29 +30,18 @@ export function buildImpProvider(
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): ImpProviderBuild {
   const url = options['url'];
-  const tokenEnv = options['tokenEnv'];
 
   if (typeof url !== 'string' || url === '') {
     return { provider: null, problem: null };
   }
 
-  if (tokenEnv !== undefined && (typeof tokenEnv !== 'string' || tokenEnv === '')) {
-    return {
-      provider: null,
-      problem: `target ${JSON.stringify(id)} must give tokenEnv as a non-empty string`,
-    };
-  }
-
-  const token = tokenEnv === undefined ? null : env[tokenEnv];
+  const source = loadTokenSource(id, options, env);
 
-  if (token === undefined || token === '') {
-    return {
-      provider: null,
-      problem: `target ${JSON.stringify(id)} reads its impd token from ${String(tokenEnv)}, which is unset or empty in the daemon's environment`,
-    };
+  if (typeof source === 'string') {
+    return { provider: null, problem: source };
   }
 
-  const provider = new ImpProvider(new ImpClientPort({ url, token }), {
+  const provider = new ImpProvider(new ImpClientPort({ url, readToken: source.readToken }), {
     ...pickString(options, 'image'),
     ...pickString(options, 'guestDir'),
     ...pickString(options, 'guestATC'),
@@ -58,6 +51,60 @@ export function buildImpProvider(
   return { provider, problem: null };
 }
 
+// How the port reads the token: a function, so a file token rereads.
+interface TokenSource {
+  readonly readToken: () => string | null;
+}
+
+// The token source the options give, or the problem that keeps the target
+// from one. A problem holds a variable's name or a file's path, never a
+// token.
+function loadTokenSource(
+  id: string,
+  options: Readonly<Record<string, unknown>>,
+  env: Readonly<Record<string, string | undefined>>,
+): TokenSource | string {
+  const tokenEnv = options['tokenEnv'];
+  const tokenFile = options['tokenFile'];
+  const target = JSON.stringify(id);
+
+  if (tokenEnv !== undefined && tokenFile !== undefined) {
+    return `target ${target} must give its impd token through tokenEnv or tokenFile, not both`;
+  }
+
+  if (tokenFile !== undefined) {
+    if (typeof tokenFile !== 'string' || tokenFile === '') {
+      return `target ${target} must give tokenFile as a non-empty string`;
+    }
+
+    try {
+      readImpToken(tokenFile);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+
+      return `target ${target} reads its impd token from a file it cannot use: ${detail}`;
+    }
+
+    return { readToken: () => readImpToken(tokenFile) };
+  }
+
+  if (tokenEnv === undefined) {
+    return { readToken: () => null };
+  }
+
+  if (typeof tokenEnv !== 'string' || tokenEnv === '') {
+    return `target ${target} must give tokenEnv as a non-empty string`;
+  }
+
+  const token = env[tokenEnv];
+
+  if (token === undefined || token === '') {
+    return `target ${target} reads its impd token from ${tokenEnv}, which is unset or empty in the daemon's environment`;
+  }
+
+  return { readToken: () => token };
+}
+
 function pickString(
   options: Readonly<Record<string, unknown>>,
   key: 'image' | 'guestDir' | 'guestATC',

package/src/daemon/build-message-trail-entry.ts

@@ -1,6 +1,6 @@
-import { truncateDetail } from '../agents/truncate-detail';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import type { SessionID } from '../shared/session-id';
+import { truncateDetail } from '../shared/truncate-detail';
 import type { MessageRecord, MessageStatus } from '../store/message-record';
 import type { TrailEntry } from '../store/trail-entry';
 

package/src/daemon/build-report-trail-entry.ts

@@ -1,6 +1,6 @@
-import { truncateDetail } from '../agents/truncate-detail';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import type { SessionID } from '../shared/session-id';
+import { truncateDetail } from '../shared/truncate-detail';
 import type { TrailEntry } from '../store/trail-entry';
 import type { NoteReport } from './parse-report';
 

package/src/daemon/build-scoped-context.ts

@@ -3,7 +3,7 @@ import type { SessionID } from '../shared/session-id';
 import { toSessionID } from '../shared/to-session-id';
 import { buildTargetForbiddenError } from './build-target-forbidden-error';
 import { buildTargetIdentity } from './build-target-identity';
-import type { DaemonContext } from './daemon-connection';
+import type { DaemonContext } from './daemon-context';
 import type { KeyedRequest } from './idempotency-ledger';
 import type { TargetAccess, TargetGrant } from './target-access';
 

package/src/daemon/build-session-message-event.ts

@@ -1,7 +1,7 @@
-import { truncateDetail } from '../agents/truncate-detail';
 import { PROTOCOL_V } from '../protocol/protocol';
 import type { EventMsg } from '../protocol/protocol';
 import type { SessionID } from '../shared/session-id';
+import { truncateDetail } from '../shared/truncate-detail';
 import type { MessageRecord } from '../store/message-record';
 
 /**