@zgeoff/atc 2.29.0 → 2.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.29.0",
+  "version": "2.30.1",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/daemon/local-pty-provider.ts

@@ -56,7 +56,7 @@ export class LocalPTYProvider implements ExecutionProvider {
       cols: spec.cols,
       rows: spec.rows,
       cwd: spec.cwd,
-      env: collectCleanEnv(spec.env, spec.withheldEnv),
+      env: buildPTYEnv(spec),
     });
 
     const subscriptions = new Set<{ readonly dispose: () => void }>();
@@ -181,6 +181,23 @@ export class LocalPTYProvider implements ExecutionProvider {
   }
 }
 
+const USABLE_TERM = 'xterm-256color';
+
+// A pseudo-terminal always has a terminal on its far side, so a harness never
+// starts with an empty or dumb TERM, which leaves an agent CLI drawing with no
+// colour. TERM is always passed: the child starts from the environment the
+// daemon itself started with, and the keys passed here only add to it or
+// override it, so leaving TERM out hands the child the daemon's own value.
+function buildPTYEnv(spec: HarnessSpec): Record<string, string> {
+  const env = collectCleanEnv(spec.env, spec.withheldEnv);
+  const term = env['TERM'];
+
+  return {
+    ...env,
+    TERM: term === undefined || term === '' || term === 'dumb' ? USABLE_TERM : term,
+  };
+}
+
 // A process another user owns still runs, so only a missing process counts
 // as gone.
 function isProcessRunning(pid: number): boolean {

package/src/mcp/mcp-tools.ts

@@ -119,6 +119,12 @@ const EVENTS_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
     waitMs: WAIT_MS.describe(
       'How long to wait for a new event when none is pending, in milliseconds; defaults to 0, capped at 30000. Keep it short.',
     ),
+    reportText: z
+      .boolean()
+      .optional()
+      .describe(
+        "true adds each report's whole text to its event, so one call reads every report of the page; defaults to false",
+      ),
   }),
   { io: 'input' },
 );
@@ -298,6 +304,10 @@ const EVENTS_OUTPUT: Readonly<Record<string, unknown>> = {
           detail: { type: ['string', 'null'] },
           message: { type: 'string' },
           label: { type: 'string' },
+          report: { type: 'string' },
+          text: { type: 'string' },
+          complete: { type: 'boolean' },
+          textError: { type: 'string' },
         },
         required: ['cursor', 'at', 'session', 'name', 'kind', 'detail'],
       },
@@ -524,10 +534,13 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended), message events (message-accepted, message-delivered, message-answered), and reports (report) since a cursor, oldest first, each with the session id and name. A message event carries the message id; read the full message with atc_message_get. A report event carries its label and a preview of its text; read the full text with atc_report_get, passing the report handle of that event when it carries one, else its cursor. Without a cursor it returns the most recent events. Pass the returned cursor next time; more is true when the page stopped before the newest event, so read again at once. session limits the read to one session. waitMs holds the call open until an event arrives; pass it instead of polling in a tight loop.',
+      'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended), message events (message-accepted, message-delivered, message-answered), and reports (report) since a cursor, oldest first, each with the session id and name. A message event carries the message id; read the full message with atc_message_get. A report event carries its label and a preview of its text; read the full text with atc_report_get, passing the report handle of that event when it carries one, else its cursor, or pass reportText: true to get the full text of every report in this call. With reportText, each report event also carries text and complete (false when atc kept only the preview), or textError when its text could not be read within 10 seconds; the page holds at most 64 KiB of report text and stops early, with more true, when the next report would not fit or 10 seconds of report reads have passed. Without a cursor it returns the most recent events. Pass the returned cursor next time; more is true when the page stopped before the newest event, so read again at once. session limits the read to one session. waitMs holds the call open until an event arrives; pass it instead of polling in a tight loop.',
     inputSchema: EVENTS_READ_INPUT,
     outputSchema: EVENTS_OUTPUT,
-    requires: { output: 'events.more', inputs: { session: 'events.session' } },
+    requires: {
+      output: 'events.more',
+      inputs: { session: 'events.session', reportText: 'report.get' },
+    },
   },
   {
     name: 'atc_report_get',

package/src/mcp/read-report-texts.ts

@@ -0,0 +1,127 @@
+import { isRecord } from '../shared/report';
+import type { FleetCaller } from './types';
+
+// The most report text one events page carries, in UTF-8 bytes: as much as
+// the daemon keeps of one report, so a page always has room for its first.
+const REPORT_TEXT_BUDGET_BYTES = 65_536;
+
+// How long the reads of one page's report texts may take in all. An events
+// read can hold a call for about 35 seconds, and the HTTP server drops a
+// call idle for 60, so the report reads finish well inside what is left.
+const REPORT_READ_DEADLINE_MS = 10_000;
+
+// What one report read gives its event: its text and whether that text is
+// whole, or the error the read failed with.
+type ReportRead = Readonly<Record<string, unknown>>;
+
+/**
+ * An events page with the whole text of each of its reports, read through
+ * `report.get` by the page's own caller, so each read rides the reach the
+ * page was read under. The reads run one at a time in page order, so one
+ * report text at most is ever in flight, under one deadline for them all.
+ * A report event gains the `text` and `complete` its read returns, or
+ * `textError` when the read fails or outlasts the deadline, and keeps its
+ * preview in `detail`. The page stops before the first report whose text
+ * would carry it past the budget, or whose read would start after the
+ * deadline: it then holds the cursor of the last event it keeps and `more`
+ * true, so the next read starts at that report. Every other field of the
+ * page, such as a gateway's `unavailable` and `truncated`, passes through
+ * unchanged.
+ */
+export async function readReportTexts(
+  caller: FleetCaller,
+  page: Readonly<Record<string, unknown>>,
+  deadlineMs: number = REPORT_READ_DEADLINE_MS,
+): Promise<Readonly<Record<string, unknown>>> {
+  const raw: unknown = page['events'];
+  const events = Array.isArray(raw) ? raw.filter((event) => isRecord(event)) : [];
+  const endsAt = Date.now() + deadlineMs;
+  const timeout = Promise.withResolvers<ReportRead>();
+
+  const timer = setTimeout(() => {
+    timeout.resolve({
+      textError: `timeout: the report text did not arrive within ${deadlineMs} ms`,
+    });
+  }, deadlineMs);
+
+  const read = await readPageReports(caller, page, events, endsAt, timeout.promise);
+
+  clearTimeout(timer);
+
+  return read;
+}
+
+// The page with its reports read, one at a time, until the budget or the
+// deadline at `endsAt` stops it. A read still out when `timeout` settles
+// gives way to the timeout it settles with.
+async function readPageReports(
+  caller: FleetCaller,
+  page: Readonly<Record<string, unknown>>,
+  events: readonly Readonly<Record<string, unknown>>[],
+  endsAt: number,
+  timeout: Readonly<Promise<ReportRead>>,
+): Promise<Readonly<Record<string, unknown>>> {
+  const kept: Readonly<Record<string, unknown>>[] = [];
+  let used = 0;
+
+  for (const event of events) {
+    if (event['kind'] !== 'report') {
+      kept.push(event);
+      continue;
+    }
+
+    const last = kept.at(-1);
+
+    if (last !== undefined && Date.now() >= endsAt) {
+      return { ...page, events: kept, cursor: last['cursor'], more: true };
+    }
+
+    const read = await Promise.race([readReportText(caller, event), timeout]);
+
+    const bytes = typeof read['text'] === 'string' ? Buffer.byteLength(read['text']) : 0;
+
+    if (last !== undefined && used + bytes > REPORT_TEXT_BUDGET_BYTES) {
+      return { ...page, events: kept, cursor: last['cursor'], more: true };
+    }
+
+    used += bytes;
+
+    kept.push({ ...event, ...read });
+  }
+
+  return { ...page, events: kept };
+}
+
+// One report event's whole text and whether it is complete, or the error
+// its read failed with. The read takes the event's report handle, which a
+// gateway adds, else the event's own cursor, which a daemon reads a report
+// by.
+async function readReportText(
+  caller: FleetCaller,
+  event: Readonly<Record<string, unknown>>,
+): Promise<ReportRead> {
+  const handle = typeof event['report'] === 'string' ? event['report'] : event['cursor'];
+
+  try {
+    const report = await caller.sendRequest('report.get', { report: handle }, ['report.get']);
+
+    return { text: report['text'], complete: report['complete'] };
+  } catch (error) {
+    return { textError: formatReadError(error) };
+  }
+}
+
+// An error with a lowercase protocol-style code reads as `<code>: <message>`,
+// as a failed tool call does.
+function formatReadError(error: unknown): string {
+  if (
+    error instanceof Error &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    /^[a-z][a-z_]*$/.test(error.code)
+  ) {
+    return `${error.code}: ${error.message}`;
+  }
+
+  return error instanceof Error ? error.message : String(error);
+}

package/src/mcp/run-tool.ts

@@ -4,6 +4,7 @@ import { DaemonError } from '../protocol/daemon-error';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { isRecord } from '../shared/report';
 import { parseIdempotencyKey } from './parse-idempotency-key';
+import { readReportTexts } from './read-report-texts';
 import type { FleetCaller, ToolContext } from './types';
 
 /**
@@ -196,6 +197,14 @@ export function runTool(
         required,
       );
 
+      // Each report's whole text rides the same call, so a reader catches
+      // up without one report read per report.
+      if (args['reportText'] === true) {
+        const withTexts = await readReportTexts(caller, ok);
+
+        return buildObjectResult(withTexts);
+      }
+
       return buildObjectResult(ok);
     })
     .with('atc_report_get', async () => {