@volter/supercode-interchange 0.1.4 → 0.1.6

package/README.md

@@ -110,6 +110,30 @@ cover recorded posture/policies through npm and operator streams, including
 unknown posture for malformed records. The manifest's other branches,
 corpus/scale, concurrent reads and independent source review remain open.
 
+`sessions.launch_agent` reads `<harness home>/supercode/launches/<session id>.json`
+in the same caller-owned load lane. Claude `projects` and Codex `sessions`
+ancestors select the transcript's recorded home, independent of current vendor
+defaults; no transcript must exist. Unsupported locators, unsafe ids, absent,
+invalid UTF-8 or malformed records, and nonobject environments return null.
+The environment is recorded metadata, never caller authority. The new
+`launch_agent` capability marker refuses older read services explicitly.
+Native runtime launch-record writers remain for their separate replacement.
+[Private Mac/Windows conversations](../../docs/evidence/session-launch-metadata-2026-10-08.md)
+record selected-home answers and null malformed metadata through npm and
+operator streams; concurrent path/record replacement and runtime writing remain
+unqualified.
+
+`sessions.usage` reads a complete lossless session in the load worker and groups
+recorded tokens by the native day prefix and model. Claude keeps the last usage
+record for each response id; Codex separates successive cumulative totals and
+cached prompt deltas. Unknown models retain `cost_unrecorded` rather than a zero
+price. Costs use the pinned 2026-10-03 native rate snapshot, including cache TTL,
+fast-mode and inference-geo factors; this is not a live pricing feed. Exact u64
+wire counts are retained independently of JavaScript number rounding. A separate
+`usage` marker refuses older read services without closing their catalog lane.
+Machine-wide spend and runtime budgets retain their separate native consumers.
+This source checkpoint has no runtime or Windows qualification yet.
+
 `resolveHarnessHomes` follows native HOME-first defaults and preserves explicitly empty harness-specific
 home values. `projectMetadata` applies workspace scope, native lineage, repository-family, profile, time and
 metadata-search filters with stable newest-first ordering. It clones raw rows before descendant roll-up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-interchange",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Read-only harness metadata, transcript codecs and session projections for Supercode",
   "license": "MIT OR Apache-2.0",

package/session-launch-agent.mjs

@@ -0,0 +1,30 @@
+// Recorded launch metadata is a reading, never caller authority. The native
+// runtime writer remains until its own replacement boundary.
+import { readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, sep } from 'node:path';
+import { parseNativeJson } from './native-json.mjs';
+
+export function recordedLaunchAgent(locator, { cwd = process.cwd() } = {}) {
+  if (locator.storage.kind !== 'file' || !locator.session_id.length
+    || /[^A-Za-z0-9_-]/.test(locator.session_id)) return null;
+  const store = locator.harness === 'codex' ? 'sessions' : locator.harness === 'claude-code' ? 'projects' : null;
+  if (store == null) return null;
+  // Walk the lexical path, starting with the path itself as Path::ancestors
+  // does. Resolving '..' first could choose a different recorded harness home.
+  let at = locator.storage.path, home = null;
+  for (;;) {
+    if (basename(at) === store) { home = dirname(at); break; }
+    const parent = dirname(at);
+    if (parent === at || at === '.') break;
+    at = parent;
+  }
+  if (home == null) return null;
+  // Leave '..' for the filesystem, including its symlink semantics.
+  const path = `${isAbsolute(home) ? '' : `${cwd}${sep}`}${home}${sep}supercode${sep}launches${sep}${locator.session_id}.json`;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(readFileSync(path));
+    const record = parseNativeJson(text);
+    const environment = record && !Array.isArray(record) && typeof record === 'object' ? record.environment : null;
+    return environment && !Array.isArray(environment) && typeof environment === 'object' ? environment : null;
+  } catch { return null; }
+}

package/session-read.d.ts

@@ -3,7 +3,7 @@ import { SessionFollower } from './session-codecs.js';
 import type { ProjectedSessionResult, NormalizedSession, RecordedSessionProfile, RecordedSessionProfileChange } from './session-model.js';
 export const SESSION_READ_METHODS: readonly string[];
 export const SESSION_READ_EVENT: 'harness.v1.sessions.event';
-export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true }>;
+export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true; usage: true }>;
 export interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
@@ -12,3 +12,14 @@ export function loadSessionRead(params: unknown, context?: SessionReadContext):
 export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;
 /** Recorded values only; malformed complete Claude runtime state leaves mode unknown. */
 export function loadRecordedSessionConfiguration(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; cwd: unknown; model: unknown; approval_policy: unknown; sandbox_policy: unknown; permission_mode: string | null }>;
+/** Best-effort recorded environment only, independent of transcript existence or caller authority. */
+export function loadSessionLaunchAgent(params: unknown, context?: SessionReadContext): Promise<{ environment: Record<string, unknown> | null }>;
+export interface SessionTokenUsage {
+  at: string; model: string; input_tokens: number; output_tokens: number;
+  cache_read_tokens: number; cache_write_tokens: number;
+  cache_write_5m_tokens: number; cache_write_1h_tokens: number;
+  cost?: { amount: number | null; currency: 'USD'; source: 'rate_table' };
+  cost_unrecorded?: true;
+}
+/** Recorded tokens and the pinned rate snapshot; exact native integers survive wire serialization. */
+export function loadSessionUsage(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; since?: string; usage: SessionTokenUsage[] }>;

package/session-read.mjs

@@ -9,10 +9,13 @@ import { SessionFollower } from './session-follower.mjs';
 import { normalizedSessionJson } from './session-model.mjs';
 import { boundSessionView, projectedMessageWindow, projectedSessionJson, projectedSessionResult, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
 import { recordedSessionConfiguration } from './session-recorded-config.mjs';
+import { recordedLaunchAgent } from './session-launch-agent.mjs';
+import { recordedSessionUsage } from './session-usage.mjs';
+import { parseUsageSince, usageMoment } from './session-usage-time.mjs';
 
-export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow', 'harness.v1.sessions.recorded_config']);
+export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow', 'harness.v1.sessions.recorded_config', 'harness.v1.sessions.launch_agent', 'harness.v1.sessions.usage']);
 export const SESSION_READ_EVENT = 'harness.v1.sessions.event';
-export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true });
+export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true, usage: true });
 export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
 const invalid = (message) => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
 const object = (value, name) => {
@@ -111,3 +114,24 @@ export async function loadRecordedSessionConfiguration(params, context = {}) {
   const { locator } = parseSessionReadParams({ locator: params.locator }, context);
   return recordedSessionConfiguration(await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true }), locator.harness);
 }
+
+export async function loadSessionLaunchAgent(params, context = {}) {
+  object(params, 'launch metadata params');
+  const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  // This door needs no transcript or parser. Preserve the original lexical
+  // path for the harness-home lookup, rather than the normalized load path.
+  locator.storage.path = params.locator.storage.path;
+  return { environment: recordedLaunchAgent(locator, context) };
+}
+
+export async function loadSessionUsage(params, context = {}) {
+  object(params, 'session usage params');
+  const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  const since = params.since == null ? null : parseUsageSince(string(params.since, 'since'));
+  // This door reads the complete lossless session, including child records,
+  // and ignores unrelated load/view options rather than applying a window.
+  const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
+  const answer = { harness: locator.harness, session_id: session.meta.session_id, usage: recordedSessionUsage(session, since) };
+  if (since != null) answer.since = usageMoment(since);
+  return answer;
+}

package/session-usage-time.mjs

@@ -0,0 +1,65 @@
+// Preserve the retained sidecar's UTC/i64 interpretation for recorded usage.
+// In particular this is not Date.parse: native records accept signed time
+// components, truncate fractions, and do not normalize day buckets to UTC.
+import { nativeTrim } from './text.mjs';
+
+const min = -(1n << 63n), max = (1n << 63n) - 1n;
+const wrap = (n) => BigInt.asIntN(64, n);
+const checked = (n) => n >= min && n <= max ? n : null;
+const floor = (n, d) => n / d - (n % d < 0n ? 1n : 0n);
+function integer(text) {
+  if (!/^[+-]?[0-9]+$/.test(text)) return null;
+  return checked(BigInt(text));
+}
+function split(text, delimiter) {
+  const a = text.indexOf(delimiter), b = text.indexOf(delimiter, a + 1);
+  return a < 0 || b < 0 ? null : [text.slice(0, a), text.slice(a + 1, b), text.slice(b + 1)];
+}
+
+export function usageTimestamp(text) {
+  if (typeof text !== 'string') return null;
+  text = nativeTrim(text); if (text.endsWith('Z')) text = text.slice(0, -1);
+  const t = text.indexOf('T'); if (t < 0) return null;
+  const date = split(text.slice(0, t), '-'); let time = text.slice(t + 1), millis = 0n;
+  const dot = time.indexOf('.');
+  if (dot >= 0) {
+    const digits = /^[0-9]+/.exec(time.slice(dot + 1))?.[0]; if (!digits) return null;
+    millis = BigInt(digits.slice(0, 3).padEnd(3, '0')); time = time.slice(0, dot);
+  }
+  const clock = split(time, ':'); if (!date || !clock) return null;
+  let [year, month, day, hour, minute, second] = [...date, ...clock].map(integer);
+  if ([year, month, day, hour, minute, second].some((n) => n == null) || month < 1n || month > 12n || day < 1n || day > 31n) return null;
+  year = month <= 2n ? wrap(year - 1n) : year;
+  const era = floor(year >= 0n ? year : wrap(year - 399n), 400n);
+  const yoe = wrap(year - wrap(era * 400n)), mp = month > 2n ? month - 3n : month + 9n;
+  const doy = (153n * mp + 2n) / 5n + day - 1n;
+  const doe = wrap(wrap(wrap(yoe * 365n) + yoe / 4n) - yoe / 100n + doy);
+  const days = wrap(wrap(era * 146097n) + doe - 719468n), daySeconds = checked(days * 86400n);
+  if (daySeconds == null) return null;
+  const seconds = checked(daySeconds + wrap(wrap(hour * 3600n + wrap(minute * 60n)) + second));
+  if (seconds == null) return null;
+  const whole = checked(seconds * 1000n); return whole == null ? null : checked(whole + millis);
+}
+
+export function parseUsageSince(text, now = BigInt(Date.now())) {
+  text = nativeTrim(text); const at = usageTimestamp(text); if (at != null) return at;
+  const digits = /^[0-9]+/.exec(text)?.[0];
+  const amount = digits == null ? null : integer(digits);
+  if (amount == null) throw new Error(`\`${text}\` is neither a duration (10m, 1h, 2d) nor an RFC 3339 moment`);
+  const units = new Map([['s', 1000n], ['m', 60000n], ['h', 3600000n], ['d', 86400000n]]), unit = units.get(text.slice(digits.length));
+  if (unit == null) throw new Error(`\`${text}\`: a duration's unit is s, m, h or d (10m, 1h, 2d)`);
+  return wrap(now - wrap(amount * unit));
+}
+
+export function usageMoment(ms) {
+  let seconds = floor(ms, 1000n); const millis = ms - seconds * 1000n;
+  if (seconds < 0n) seconds = 0n; // Retained sidecar clamps pre-epoch seconds.
+  const z = seconds / 86400n + 719468n, era = z / 146097n, doe = z - era * 146097n;
+  const yoe = (doe - doe / 1460n + doe / 36524n - doe / 146096n) / 365n;
+  let year = yoe + era * 400n;
+  const doy = doe - (365n * yoe + yoe / 4n - yoe / 100n), mp = (5n * doy + 2n) / 153n;
+  const day = doy - (153n * mp + 2n) / 5n + 1n, month = mp + (mp < 10n ? 3n : -9n);
+  year += month <= 2n ? 1n : 0n;
+  const tod = seconds % 86400n, pad = (n, width = 2) => String(n).padStart(width, '0');
+  return `${pad(year, 4)}-${pad(month)}-${pad(day)}T${pad(tod / 3600n)}:${pad(tod % 3600n / 60n)}:${pad(tod % 60n)}.${pad(millis, 3)}Z`;
+}

package/session-usage.mjs

@@ -0,0 +1,110 @@
+// The public session reader's accounting, ported from token_spend.rs and the
+// 2026-10-03 pricing.rs snapshot. These are parity rates, not a live price feed.
+// Machine-wide accounting and native runtime budgets retain their consumers.
+import { nativeInteger, parseNativeJson, setNativeFloat, setNativeInteger } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { usageTimestamp } from './session-usage-time.mjs';
+
+const rates = [
+  ['claude-fable-5-1', [10, 50, .25, 12.5, 20, 1, 1.1]],
+  ['claude-mythos-5-1', [10, 50, .25, 12.5, 20, 1, 1.1]],
+  ['claude-fable-5', [10, 50, 1, 12.5, 20, 1, 1.1]],
+  ['claude-mythos-5', [10, 50, 1, 12.5, 20, 1, 1.1]],
+  ['claude-opus-5-5', [4, 20, .2, 5, 8, 2, 1.1]],
+  ['claude-opus-5', [5, 25, .5, 6.25, 10, 2, 1.1]],
+  ['claude-opus-4-8', [5, 25, .5, 6.25, 10, 2, 1.1]],
+  ['claude-opus-4-7', [5, 25, .5, 6.25, 10, 1, 1.1]],
+  ['claude-opus-4-6', [5, 25, .5, 6.25, 10, 1, 1.1]],
+  ['claude-opus-4-5', [5, 25, .5, 6.25, 10, 1, 1]],
+  ['claude-opus-4-1', [15, 75, 1.5, 18.75, 30, 1, 1]],
+  ['claude-opus-4-0', [15, 75, 1.5, 18.75, 30, 1, 1]],
+  ['claude-opus-4', [15, 75, 1.5, 18.75, 30, 1, 1]],
+  ['claude-sonnet-5-5', [2, 10, .2, 2.5, 4, 1, 1.1]],
+  ['claude-sonnet-5', [2, 10, .2, 2.5, 4, 1, 1.1]],
+  ['claude-sonnet-4-6', [3, 15, .3, 3.75, 6, 1, 1.1]],
+  ['claude-sonnet-4-5', [3, 15, .3, 3.75, 6, 1, 1]],
+  ['claude-sonnet-4-0', [3, 15, .3, 3.75, 6, 1, 1]],
+  ['claude-sonnet-4', [3, 15, .3, 3.75, 6, 1, 1]],
+  ['claude-haiku-4-5', [1, 5, .1, 1.25, 2, 1, 1]],
+  ['claude-3-5-haiku', [.8, 4, .08, 1, 1.6, 1, 1]],
+];
+const wrap = (n) => BigInt.asUintN(64, n), sub = (a, b) => a > b ? a - b : 0n;
+const tokens = (value, key) => nativeInteger(value, key) ?? 0n;
+const sorted = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+function price(model) {
+  model = model.replaceAll('.', '-');
+  for (const [pattern, rate] of rates) {
+    for (let from = 0, at; (at = model.indexOf(pattern, from)) >= 0; from = at + pattern.length) {
+      const rest = model.slice(at + pattern.length);
+      const digits = rest.startsWith('-') ? /^[0-9]*/.exec(rest.slice(1))[0].length : 0;
+      if (digits < 1 || digits > 2) return rate;
+    }
+  }
+  return null;
+}
+function recorded(record, model, counts, fast = false, usOnly = false) {
+  const at = stringField(record, 'timestamp');
+  return { at, atMs: usageTimestamp(at), model, counts, fast, usOnly };
+}
+function claudeUse(record) {
+  const message = field(record, 'message'), id = stringField(message, 'id'), usage = field(message, 'usage');
+  if (id == null || usage === undefined) return null;
+  const model = stringField(message, 'model') ?? 'unknown'; if (model === '<synthetic>') return null;
+  const written = tokens(usage, 'cache_creation_input_tokens'), split = field(usage, 'cache_creation');
+  const write1h = tokens(split, 'ephemeral_1h_input_tokens'), write5m = tokens(split, 'ephemeral_5m_input_tokens');
+  return [id, recorded(record, model, [tokens(usage, 'input_tokens'), tokens(usage, 'output_tokens'), tokens(usage, 'cache_read_input_tokens'),
+    split === undefined ? written : wrap(write5m + sub(written, wrap(write5m + write1h))), write1h],
+  stringField(usage, 'speed') === 'fast', stringField(usage, 'inference_geo') === 'us')];
+}
+function dayPrefix(at) {
+  if (at == null) return 'unknown';
+  let bytes = 0, result = '';
+  for (const scalar of at) { bytes += Buffer.byteLength(scalar); if (bytes > 10) break; result += scalar; if (bytes === 10) return result; }
+  return 'unknown';
+}
+function* records(raw) {
+  for (const line of raw) { let record; try { record = parseNativeJson(line); } catch { continue; } yield record; }
+}
+
+export function recordedSessionUsage(session, since = null) {
+  const days = new Map();
+  const count = (record) => {
+    if (since != null && (record.atMs == null || record.atMs < since)) return;
+    const day = dayPrefix(record.at), key = JSON.stringify([day, record.model]);
+    let sum = days.get(key);
+    if (!sum) { sum = { day, model: record.model, counts: [0n, 0n, 0n, 0n, 0n], cost: 0, priced: false, unpriced: false }; days.set(key, sum); }
+    for (let i = 0; i < 5; i++) sum.counts[i] = wrap(sum.counts[i] + record.counts[i]);
+    const rate = price(record.model);
+    if (rate == null) sum.unpriced = true;
+    else {
+      let cost = Number(record.counts[0]) / 1e6 * rate[0];
+      for (let i = 1; i < 5; i++) cost += Number(record.counts[i]) / 1e6 * rate[i];
+      sum.cost += cost * (record.fast ? rate[5] : 1) * (record.usOnly ? rate[6] : 1); sum.priced = true;
+    }
+  };
+  if (session.meta.source === 'claude_code') {
+    const responses = new Map();
+    for (const record of records(session.raw)) { const response = claudeUse(record); if (response) responses.set(...response); }
+    for (const id of [...responses.keys()].sort(sorted)) count(responses.get(id));
+  } else if (session.meta.source === 'codex') {
+    let model = session.meta.model ?? 'unknown', previous = [0n, 0n, 0n];
+    for (const record of records(session.raw)) {
+      const payload = field(record, 'payload');
+      if (stringField(record, 'type') === 'turn_context') { model = stringField(payload, 'model') ?? model; continue; }
+      if (stringField(payload, 'type') !== 'token_count') continue;
+      const total = field(field(payload, 'info'), 'total_token_usage'); if (total === undefined) continue;
+      const now = ['input_tokens', 'output_tokens', 'cached_input_tokens'].map((key) => tokens(total, key));
+      if (now.every((n, i) => n === previous[i])) continue;
+      const [input, output, cached] = now.map((n, i) => sub(n, previous[i])); previous = now;
+      count(recorded(record, model, [sub(input, cached), output, cached, 0n, 0n]));
+    }
+  }
+  return [...days.values()].sort((a, b) => sorted(a.day, b.day) || sorted(a.model, b.model)).map((sum) => {
+    const row = { at: `${sum.day}T00:00:00Z`, model: sum.model };
+    for (const [key, count] of [['input_tokens', sum.counts[0]], ['output_tokens', sum.counts[1]], ['cache_read_tokens', sum.counts[2]],
+      ['cache_write_tokens', wrap(sum.counts[3] + sum.counts[4])], ['cache_write_5m_tokens', sum.counts[3]], ['cache_write_1h_tokens', sum.counts[4]]]) setNativeInteger(row, key, count);
+    if (sum.priced) { row.cost = { currency: 'USD', source: 'rate_table' }; setNativeFloat(row.cost, 'amount', Math.round(sum.cost * 1e6) / 1e6); }
+    if (sum.unpriced) row.cost_unrecorded = true;
+    return row;
+  });
+}