jackherd 0.0.1 → 1.0.1

package/src/config/schema.ts

@@ -0,0 +1,302 @@
+import { z } from 'zod'
+import { checkConfigSchema } from '../check/schema'
+import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
+import { PLAN_LANGUAGE } from '../vocabulary'
+import { SOURCE_FIELD } from '../watch/source-fields'
+import { isSourcePath } from '../watch/source-path'
+import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
+import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
+
+export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
+
+export type TerminalAdapter = (typeof TERMINAL_ADAPTER)[keyof typeof TERMINAL_ADAPTER]
+
+// TODO: draft role list taken from the agents the kit ships; confirm it before more kit files render model
+// IDs per role.
+export const MODEL_ROLE = {
+  plan: 'plan',
+  implement: 'implement',
+  review: 'review',
+  explore: 'explore',
+  orchestrate: 'orchestrate',
+} as const
+
+export type ModelRole = (typeof MODEL_ROLE)[keyof typeof MODEL_ROLE]
+
+export const isTerminalAdapter = (value: string): value is TerminalAdapter =>
+  (Object.values(TERMINAL_ADAPTER) as string[]).includes(value)
+
+export const isModelRole = (value: string): value is ModelRole =>
+  (Object.values(MODEL_ROLE) as string[]).includes(value)
+
+/** Lower-case letters and digits ending in a dash, so a prefixed name stays one plain path segment. */
+export const SKILL_PREFIX = /^[a-z0-9]+-$/
+
+const FULL_MODEL_ID = /^claude-[a-z0-9][a-z0-9.-]*$/
+
+const language = z.enum(Object.values(PLAN_LANGUAGE))
+
+const modelId = z
+  .string()
+  .regex(FULL_MODEL_ID, 'Use a full model ID such as claude-opus-5-5, not an alias like opus or sonnet')
+
+const command = z.string().min(1)
+
+const share = z.number().gt(0).lt(1)
+
+/** A file below the main checkout, written into shell commands: relative, never leaving it, never an option, no quote or control character. */
+const laneCopyPath = z.string().regex(
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: the class exists to refuse control characters
+  /^(?![/-])(?!(?:.*\/)?\.\.(?:\/|$))[^'\x00-\x1f\x7f]+$/,
+  'a relative path inside the checkout: no leading / or -, no .. segment, no quote or control character',
+)
+
+const warnBelowAlert = ({ warnAt, alertAt }: { warnAt: number; alertAt: number }): boolean => warnAt < alertAt
+
+const WARN_BELOW_ALERT = { message: 'warnAt must be below alertAt', path: ['warnAt'] }
+
+/** The lock file, written unquoted into git commands: a plain relative path, never an option. */
+const lockFilePath = z
+  .string()
+  .regex(/^(?![/-])(?!(?:.*\/)?\.\.(?:\/|$))[A-Za-z0-9._/-]+$/, 'a plain relative file name such as yarn.lock')
+
+/**
+ * A branch name as git arguments and rendered commands take it: never an option, no whitespace, no `..`, in the
+ * shape `git check-ref-format --branch` allows.
+ */
+const branchName = z
+  .string()
+  .regex(
+    /^(?![-/.])(?!.*(?:\.\.|\/\/|@\{|\.lock(?:\/|$)))[A-Za-z0-9._/-]+(?<![./])$/,
+    'a branch name such as main: no leading - / or ., no .. and no spaces',
+  )
+
+/** A workflow file name as `gh run list --workflow` takes it: no path, no option, a YAML file. */
+const workflowFile = z.string().regex(/^(?![-.])[A-Za-z0-9._-]+\.ya?ml$/, 'a workflow file name such as deploy.yml')
+
+/** One directory name, glob characters allowed: never a path, an option or a hidden directory. */
+const boardPattern = z
+  .string()
+  .regex(/^(?![-.])[A-Za-z0-9._*?-]+$/, 'one directory name such as board-*: no / and no leading - or .')
+
+/** One markdown file name inside a board's directory. */
+const boardFile = z
+  .string()
+  .regex(/^(?![-.])[A-Za-z0-9._-]+\.md$/, 'one markdown file name such as board.md: no / and no leading - or .')
+
+const boardSchema = z.strictObject({
+  /** The directories under `planDirectory` that hold a board; the newest board is the default of `plans` and `watch`. */
+  pattern: boardPattern.default('board-*'),
+  /** The board document inside each of those directories. */
+  file: boardFile.default('board.md'),
+  /** What the project calls a board: the plans view, its page and the watcher print it as written. */
+  term: z.string().min(1).default('board'),
+})
+
+const deploySchema = z.strictObject({
+  /** The workflow whose runs on the base branch the watcher reports as `deploy`. */
+  workflow: workflowFile,
+  /** The deployment environments the watcher names as a run's target; any other reads `unknown`. */
+  environments: z.array(z.string().min(1)).min(1),
+})
+
+const feedbackSchema = z.strictObject({
+  /** GitHub logins whose feedback does not wake the coordinator, such as a status bot; case is ignored. */
+  ignore: z.array(z.string().min(1)).default([]),
+})
+
+const previewsSchema = z.strictObject({
+  /** Reads the GitHub deployments of each head commit; a successful one outside production and `deploy.environments` names its `environment_url`. */
+  deployments: z.boolean().default(false),
+  /**
+   * GitHub logins whose pull request comments link a preview; nothing they write counts as feedback, so name a bot that
+   * only posts previews, not one that also reviews. Case is ignored.
+   */
+  authors: z.array(z.string().min(1)).default([]),
+  /** Finds the URL in such a comment: its first group, else its match; without it the first https link. */
+  urlPattern: z.string().min(1).refine(isRegularExpression, 'not a valid regular expression').optional(),
+})
+
+const sourcePath = z.string().refine(isSourcePath, 'not a source path: `.`, or `.key`, `[n]` and `[-n]` in a chain')
+
+const SOURCE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
+
+/** The six known fields, and any further field (`status`, `priority`, …) whose name is a plain name, for `reportOn`. */
+const sourceMapSchema = z
+  .object({
+    [SOURCE_FIELD.id]: sourcePath,
+    /** Changes whenever the entry changes; compared as text, so any stable form of a time or version works. */
+    [SOURCE_FIELD.updatedAt]: sourcePath,
+    [SOURCE_FIELD.title]: sourcePath.optional(),
+    /** Shown only as an `https:` URL without user name or password. */
+    [SOURCE_FIELD.url]: sourcePath.optional(),
+    /** The first line with text is shown. */
+    [SOURCE_FIELD.body]: sourcePath.optional(),
+    [SOURCE_FIELD.author]: sourcePath.optional(),
+  })
+  .catchall(sourcePath)
+  .refine((map) => Object.keys(map).every((field) => SOURCE_FIELD_NAME.test(field)), {
+    message: 'a map field is a letter, then letters, digits and `_`',
+  })
+
+const sourceSchema = z
+  .strictObject({
+    /** Printed in every report of the source and the key of its saved state. */
+    name: z.string().regex(/^[A-Za-z0-9][\w.-]*$/, 'letters, digits, `_`, `.` and `-`'),
+    /** Program and arguments, run without a shell in the main checkout; it prints JSON on stdout and only reads. */
+    command: z.array(z.string().min(1)).min(1),
+    /** Minutes between two runs, at least 1. */
+    every: z.number().int().min(1).default(5),
+    /** The path of the list in the output; without it the output is the list. */
+    items: sourcePath.optional(),
+    map: sourceMapSchema,
+    /** Values of `map.author` whose changes wake nobody, such as the account the command runs as; case is ignored. */
+    ignoreAuthors: z.array(z.string().min(1)).default([]),
+    /** The most new or changed entries one report shows of this source; the rest is one line `+<n> more`. */
+    reportLimit: z.number().int().min(1).default(5),
+    /** The lane the source's reports name. */
+    lane: z.string().min(1).optional(),
+    /**
+     * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
+     * `author`, `body` and `url`; without it a change of that content reports.
+     */
+    reportOn: z.array(z.string().min(1)).min(1).max(10).optional(),
+  })
+  .refine((source) => source.ignoreAuthors.length === 0 || source.map.author !== undefined, {
+    message: 'ignoreAuthors needs map.author',
+    path: ['ignoreAuthors'],
+  })
+  .refine((source) => !source.reportOn?.includes(SOURCE_FIELD.id), {
+    message: 'reportOn cannot name id',
+    path: ['reportOn'],
+  })
+  .refine((source) => (source.reportOn ?? []).every((field) => Object.hasOwn(source.map, field)), {
+    message: 'reportOn names a field map does not have',
+    path: ['reportOn'],
+  })
+
+const hasUniqueNames = (sources: readonly { name: string }[]): boolean =>
+  new Set(sources.map(({ name }) => name)).size === sources.length
+
+const coordinatorSchema = z
+  .strictObject({
+    /** Share of the coordinator's context window from which the watcher reports `coordinator warn`. */
+    warnAt: share.default(0.5),
+    /** Share of the coordinator's context window from which the watcher reports `coordinator alert`. */
+    alertAt: share.default(0.7),
+  })
+  .refine(warnBelowAlert, WARN_BELOW_ALERT)
+
+const contextSchema = z
+  .strictObject({
+    /** Share of the context window from which a lane's fill shows yellow and `/implement` offers a new chat. */
+    warnAt: share.default(0.6),
+    /** Share of the context window from which a lane's fill shows red. */
+    alertAt: share.default(0.8),
+    /** Context window in tokens by full model ID; the log does not say which window a session ran with. */
+    windows: z.record(modelId, z.number().int().positive()).default({}),
+    /** The window assumed for a model not listed in `windows`. */
+    defaultWindow: z.number().int().positive().default(200_000),
+    /** The coordinator's own thresholds, used by `jh context --coordinator`; the lanes keep `warnAt` and `alertAt`. */
+    coordinator: coordinatorSchema.prefault({}),
+  })
+  .refine(warnBelowAlert, WARN_BELOW_ALERT)
+
+export const jackherdConfigSchema = z.strictObject({
+  $schema: z.string().optional(),
+  responseLanguage: language.default(PLAN_LANGUAGE.en),
+  planLanguage: language.default(PLAN_LANGUAGE.en),
+  planDirectory: z.string().min(1).default('docs/plans'),
+  /** Where the boards live and what the project calls them. */
+  board: boardSchema.prefault({}),
+  /** Replaced by `board.pattern` in 0.13.0; named here only so an old config is refused with that hint. */
+  sprintPattern: z
+    .never({ error: 'sprintPattern was replaced by board.pattern (with board.file and board.term)' })
+    .optional(),
+  worktreeDirectory: z.string().min(1).default(claudePath(WORKTREES_DIRECTORY)),
+  baseBranch: branchName.default(DEFAULT_BASE_BRANCH),
+  /**
+   * Put before every skill and agent name. `jh sync --global` refuses to run without one: a personal skill
+   * shadows a project skill of the same name. In a project it is optional and keeps the project's own skills of a
+   * kit name (`implement`, `plan`, …) apart from the kit's.
+   */
+  skillPrefix: z
+    .union([z.literal(''), z.string().regex(SKILL_PREFIX, 'lower-case letters and digits ending in a dash, e.g. kit-')])
+    .default(''),
+  commands: z
+    .strictObject({
+      test: command.default(BUN_COMMANDS.test),
+      typecheck: command.default(BUN_COMMANDS.typecheck),
+      lint: command.default(BUN_COMMANDS.lint),
+      format: command.default(BUN_COMMANDS.format),
+      /** Installs a new lane's dependencies. */
+      install: command.default(BUN_COMMANDS.install),
+      /** Starts a lane's dev server, run as `PORT=<port> <dev>`; a project supplement may name another. */
+      dev: command.default(BUN_COMMANDS.dev),
+    })
+    .prefault({}),
+  /** How `/orchestrate` sets up a lane's worktree. */
+  lanes: z
+    .strictObject({
+      /** Untracked files copied into every new worktree; empty means the files `.worktreeinclude` lists. */
+      copy: z.array(laneCopyPath).default([]),
+      /** The dependency lock file a rebase takes from the base branch and regenerates, never merges by hand. */
+      lockFile: lockFilePath.default('bun.lock'),
+    })
+    .prefault({}),
+  models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId),
+  terminal: z
+    .strictObject({ adapter: z.enum(Object.values(TERMINAL_ADAPTER)).default(TERMINAL_ADAPTER.none) })
+    .prefault({}),
+  plans: z
+    .strictObject({
+      /** Minutes between background fetches of the base branch while `jh plans` runs; 0 turns them off. */
+      fetchIntervalMinutes: z.number().min(0).default(5),
+      /** Links in a plan that the sprint page shows as chips; the list replaces the built-in kinds. */
+      linkKinds: z
+        .array(
+          z.strictObject({
+            pattern: z.string().min(1).refine(isRegularExpression, 'not a valid regular expression'),
+            label: z.string().min(1),
+            icon: z.string().min(1),
+          }),
+        )
+        .default(DEFAULT_LINK_KINDS.map((kind) => ({ ...kind }))),
+      context: contextSchema.prefault({}),
+    })
+    .prefault({}),
+  /**
+   * Read by `jh watch`; without `deploy` it reports no deploy runs. `feedback` is on unless set to `false`:
+   * it reports new feedback on the lanes' pull requests except from the account the watcher runs as and `ignore`.
+   * Without `previews` it reads no deploy preview; with it, one `preview` per new head commit. Each of `sources` is a
+   * command whose JSON output reports `source` for a new or changed entry.
+   */
+  watch: z
+    .strictObject({
+      deploy: deploySchema.optional(),
+      feedback: z.union([z.literal(false), feedbackSchema]).default({ ignore: [] }),
+      previews: previewsSchema.optional(),
+      sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
+    })
+    .prefault({}),
+  /** Read by `jh check`; validated here too, so a typo fails every command alike. */
+  check: checkConfigSchema.optional(),
+})
+
+export type JackherdConfig = z.infer<typeof jackherdConfigSchema>
+
+export const parseJackherdConfig = (raw: unknown): JackherdConfig => jackherdConfigSchema.parse(raw)
+
+const parseLabelled = <T extends z.ZodType>(schema: T, raw: unknown, label: string): z.infer<T> => {
+  const parsed = schema.safeParse(raw)
+  if (!parsed.success) throw new Error(`${label} is invalid:\n${z.prettifyError(parsed.error)}`)
+  return parsed.data
+}
+
+/** `parseJackherdConfig` for a file: an invalid one throws with `label` (its path) and the issues in words. */
+export const parseConfigFile = (raw: unknown, label: string): JackherdConfig =>
+  parseLabelled(jackherdConfigSchema, raw, label)
+
+/** One `watch.sources` entry outside the config, such as a draft to try; invalid throws with `label` and the issues. */
+export const parseSourceDraft = (raw: unknown, label: string): z.infer<typeof sourceSchema> =>
+  parseLabelled(sourceSchema, raw, label)

package/src/context/command.ts

@@ -0,0 +1,39 @@
+import { basename } from 'node:path'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { laneStatusSourceFor } from '../terminal'
+import { defaultCoordinatorName } from './coordinator-name'
+import { coordinatorSettings, parseContextOptions } from './options'
+import { contextReport, noValueNote, unnamedPaneNote } from './report'
+import { agentLog } from './session-log'
+
+/**
+ * `jh context [<name>] [--coordinator]`: prints how full the context of an agent is as one line of JSON
+ * (`tokens`, `window`, `share`, `model`, `level`), or `null` when there is no value. The name defaults to the
+ * worktree the command runs in, with `--coordinator` to `orchestrator-<repository>`. `--coordinator` also takes
+ * the level from the coordinator's thresholds (`plans.context.coordinator`). Reads the session log, never writes it.
+ */
+export const run = async (args: string[]): Promise<number> => {
+  try {
+    const options = parseContextOptions(args)
+    const root = mainCheckout(process.cwd())
+    const worktree = worktreeRoot(process.cwd())
+    const settings = readSettings([worktree, root])
+    const lane = options.lane ?? (options.coordinator ? defaultCoordinatorName(basename(root)) : basename(worktree))
+    const context = options.coordinator ? coordinatorSettings(settings.context) : settings.context
+    const source = laneStatusSourceFor(settings.adapter)
+    const named = source.listAgents()
+    const pane = process.env.HERDR_PANE_ID
+    const adopt =
+      options.coordinator && pane && !named.some((agent) => agent.name === lane) ? { pane, name: lane } : undefined
+    const agents = adopt ? source.listAgents(adopt) : named
+    const report = contextReport(agents, lane, agentLog, context)
+    console.log(JSON.stringify(report))
+    if (agents.length > named.length) console.error(unnamedPaneNote(lane))
+    if (report === null) console.error(noValueNote(agents, lane))
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/context/coordinator-name.ts

@@ -0,0 +1,16 @@
+const PREFIX = 'orchestrator'
+const MAX_LENGTH = 32
+
+/**
+ * The herdr name a coordinator takes when none is given: `orchestrator-<repository>`. herdr names are unique
+ * across all workspaces, so two repositories cannot both run a coordinator called `orchestrator`. The name
+ * fits `[a-z][a-z0-9_-]{0,31}`; a repository name that leaves nothing usable gives plain `orchestrator`.
+ */
+export const defaultCoordinatorName = (repository: string): string => {
+  const slug = repository
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  if (!slug) return PREFIX
+  return `${PREFIX}-${slug}`.slice(0, MAX_LENGTH).replace(/-+$/, '')
+}

package/src/context/fill.ts

@@ -0,0 +1,69 @@
+/** How the context window of a model is assumed: by model ID, with a default for the models not listed. */
+export type ContextWindows = { windows: Readonly<Record<string, number>>; defaultWindow: number }
+
+export type ContextFill = {
+  /** Input tokens of the last main-chain answer: what the next request carries. */
+  tokens: number
+  window: number
+  /** `tokens / window`, at most 1. */
+  share: number
+  model: string
+}
+
+type Answer = { tokens: number; model: string }
+
+/** Window sizes that exist whatever the config lists, so a fill past the assumed window still lands on a real one. */
+const COMMON_WINDOWS = [200_000, 1_000_000]
+
+const SYNTHETIC_MODEL = '<synthetic>'
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null
+
+const count = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
+
+const parseLine = (line: string): unknown => {
+  try {
+    return JSON.parse(line)
+  } catch {
+    return null
+  }
+}
+
+/** The answer of a main-chain `assistant` line; null for every other line, a sub-agent's answer and a synthetic one. */
+const answerOf = (line: string): Answer | null => {
+  const entry = parseLine(line)
+  if (!isRecord(entry) || entry.type !== 'assistant' || entry.isSidechain === true) return null
+  const { message } = entry
+  if (!isRecord(message) || typeof message.model !== 'string' || message.model === SYNTHETIC_MODEL) return null
+  const { usage } = message
+  if (!isRecord(usage)) return null
+  const tokens =
+    count(usage.input_tokens) + count(usage.cache_creation_input_tokens) + count(usage.cache_read_input_tokens)
+  return tokens > 0 ? { tokens, model: message.model } : null
+}
+
+/**
+ * The window the fill fits in: the one configured for the model, or if the highest fill of the session already
+ * passed it, the next larger known window, the configured ones and the common sizes (the log never says which window a
+ * session ran with). Beyond every known window the highest fill itself is the window.
+ */
+const windowFor = (model: string, highest: number, { windows, defaultWindow }: ContextWindows): number => {
+  const assumed = windows[model] ?? defaultWindow
+  if (highest <= assumed) return assumed
+  const larger = [...Object.values(windows), defaultWindow, ...COMMON_WINDOWS].filter((size) => size >= highest)
+  return larger.length > 0 ? Math.min(...larger) : highest
+}
+
+/**
+ * How full the context of a session is, read from the lines of its log. Null when no line is a usable answer,
+ * so a missing or empty log is no error; lines that do not parse (the last one while it is being written) are
+ * skipped. `lines` may be a tail of the log: the highest fill is then the highest within it.
+ */
+export const contextFill = (lines: readonly string[], windows: ContextWindows): ContextFill | null => {
+  const answers = lines.flatMap((line) => answerOf(line) ?? [])
+  const last = answers.at(-1)
+  if (!last) return null
+  const highest = Math.max(...answers.map(({ tokens }) => tokens))
+  const window = windowFor(last.model, highest, windows)
+  return { tokens: last.tokens, window, share: Math.min(last.tokens / window, 1), model: last.model }
+}

package/src/context/index.ts

@@ -0,0 +1,10 @@
+export { type ContextFill, type ContextWindows, contextFill } from './fill'
+export {
+  CONTEXT_LEVEL,
+  type ContextLevel,
+  type ContextReading,
+  type ContextThresholds,
+  contextLabel,
+  contextLevel,
+  contextReading,
+} from './level'

package/src/context/level.ts

@@ -0,0 +1,22 @@
+export const CONTEXT_LEVEL = { ok: 'ok', warn: 'warn', alert: 'alert' } as const
+
+export type ContextLevel = (typeof CONTEXT_LEVEL)[keyof typeof CONTEXT_LEVEL]
+
+export type ContextThresholds = { warnAt: number; alertAt: number }
+
+/** A fill as a view shows it: the share of the window and which threshold it has passed. */
+export type ContextReading = { share: number; level: ContextLevel }
+
+/** `ok` below `warnAt`, `warn` from there, `alert` from `alertAt` on. */
+export const contextLevel = (share: number, { warnAt, alertAt }: ContextThresholds): ContextLevel => {
+  if (share >= alertAt) return CONTEXT_LEVEL.alert
+  return share >= warnAt ? CONTEXT_LEVEL.warn : CONTEXT_LEVEL.ok
+}
+
+export const contextReading = (share: number, thresholds: ContextThresholds): ContextReading => ({
+  share,
+  level: contextLevel(share, thresholds),
+})
+
+/** `62 %` */
+export const contextLabel = (share: number): string => `${Math.round(share * 100)} %`

package/src/context/options.ts

@@ -0,0 +1,29 @@
+import { CLI_NAME } from '../version/release'
+import type { ContextWindows } from './fill'
+import type { ContextThresholds } from './level'
+
+/** `lane` is null when the command names none; it then measures the agent of the worktree it runs in. */
+export type ContextOptions = { lane: string | null; coordinator: boolean }
+
+export type ContextSettings = ContextWindows & ContextThresholds & { coordinator: ContextThresholds }
+
+const COORDINATOR_OPTION = '--coordinator'
+
+const KNOWN_OPTIONS = [COORDINATOR_OPTION]
+
+const USAGE = `usage: ${CLI_NAME} context [<name>] [${COORDINATOR_OPTION}]`
+
+/** Reads `[<name>] [--coordinator]` in any order; throws with the usage on an unknown option or a second name. */
+export const parseContextOptions = (args: readonly string[]): ContextOptions => {
+  const unknown = args.find((arg) => arg.startsWith('--') && !KNOWN_OPTIONS.includes(arg))
+  if (unknown) throw new Error(`unknown option ${unknown}\n${USAGE}`)
+  const names = args.filter((arg) => !arg.startsWith('--'))
+  if (names.length > 1) throw new Error(`one name at most, got ${names.join(' ')}\n${USAGE}`)
+  return { lane: names[0] ?? null, coordinator: args.includes(COORDINATOR_OPTION) }
+}
+
+/** The settings with the coordinator's thresholds in place of a lane's; the windows stay the same. */
+export const coordinatorSettings = (settings: ContextSettings): ContextSettings => ({
+  ...settings,
+  ...settings.coordinator,
+})

package/src/context/report.ts

@@ -0,0 +1,42 @@
+import type { LaneAgent } from '../terminal'
+import { type ContextFill, type ContextWindows, contextFill } from './fill'
+import { type ContextLevel, type ContextThresholds, contextLevel } from './level'
+
+export type ContextReport = ContextFill & { level: ContextLevel }
+
+export type AgentLogReader = (agent: Pick<LaneAgent, 'session' | 'cwd'>) => string[] | null
+
+/** The fill of one agent with its level; null without an agent, a log or an answer in it. */
+export const contextOfAgent = (
+  agent: Pick<LaneAgent, 'session' | 'cwd'> | undefined,
+  readLog: AgentLogReader,
+  settings: ContextWindows & ContextThresholds,
+): ContextReport | null => {
+  const lines = agent ? readLog(agent) : null
+  const fill = lines && contextFill(lines, settings)
+  return fill ? { ...fill, level: contextLevel(fill.share, settings) } : null
+}
+
+/**
+ * How full the context of the agent named `lane` is, with the level it reached. Null when no such agent is
+ * listed or its log is missing or holds no answer: no value, and no error.
+ */
+export const contextReport = (
+  agents: readonly LaneAgent[],
+  lane: string,
+  readLog: AgentLogReader,
+  settings: ContextWindows & ContextThresholds,
+): ContextReport | null =>
+  contextOfAgent(
+    agents.find((agent) => agent.name === lane),
+    readLog,
+    settings,
+  )
+
+/** Why `contextReport` gave no value. */
+export const noValueNote = (agents: readonly LaneAgent[], lane: string): string =>
+  agents.some((agent) => agent.name === lane) ? `${lane} has no answer in its session log` : `no agent named ${lane}`
+
+/** What to run so the agent of an unnamed pane is found by its name next time. */
+export const unnamedPaneNote = (lane: string): string =>
+  `pane without a name, herdr agent rename "$HERDR_PANE_ID" ${lane}`

package/src/context/session-log.ts

@@ -0,0 +1,91 @@
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, readSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY } from '../claude/paths'
+
+/** How much of the end of a log is read: logs grow to hundreds of megabytes, and the last answers are at the end. */
+export const TAIL_BYTES = 2 * 1024 * 1024
+
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export const defaultProjectsDirectory = (): string => join(homedir(), CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY)
+
+const foundPaths = new Map<string, string>()
+
+/** The log of a session, in whichever project directory holds it (found once, then remembered, since the view asks every few seconds); null for an id that is not a UUID or has no log. */
+export const sessionLogPath = (sessionId: string, projectsDirectory: string): string | null => {
+  if (!SESSION_ID.test(sessionId) || !existsSync(projectsDirectory)) return null
+  const cacheKey = `${projectsDirectory}\0${sessionId}`
+  const cached = foundPaths.get(cacheKey)
+  if (cached && existsSync(cached)) return cached
+  const match = readdirSync(projectsDirectory)
+    .map((directory) => join(projectsDirectory, directory, `${sessionId}.jsonl`))
+    .find((path) => existsSync(path))
+  if (match) foundPaths.set(cacheKey, match)
+  return match ?? null
+}
+
+/** The last `bytes` of a file as complete lines: a cut-off first line is dropped, the last one is kept as it is. */
+export const readTailLines = (path: string, bytes: number): string[] => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const { size } = fstatSync(descriptor)
+    const start = Math.max(0, size - bytes)
+    const buffer = Buffer.alloc(size - start)
+    readSync(descriptor, buffer, 0, buffer.length, start)
+    const lines = buffer.toString('utf8').split('\n')
+    return start > 0 ? lines.slice(1) : lines
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+/** The tail of a session's log, read only; null when the session has no log or it cannot be read. */
+export const sessionLog = (
+  sessionId: string,
+  projectsDirectory: string = defaultProjectsDirectory(),
+  bytes: number = TAIL_BYTES,
+): string[] | null => {
+  try {
+    const path = sessionLogPath(sessionId, projectsDirectory)
+    return path ? readTailLines(path, bytes) : null
+  } catch {
+    return null
+  }
+}
+
+export type AgentSession = { session: string | null; cwd: string | null }
+
+const hasAnswer = (lines: readonly string[]): boolean => lines.some((line) => line.includes('"type":"assistant"'))
+
+/** Claude Code names a project directory after the working directory, `/` and `.` turned into `-`. */
+const projectDirectoryOf = (cwd: string): string => cwd.replace(/[/.]/g, '-')
+
+const newestLogOf = (cwd: string, projectsDirectory: string): string | null => {
+  const directory = join(projectsDirectory, projectDirectoryOf(cwd))
+  if (!existsSync(directory)) return null
+  const newest = readdirSync(directory)
+    .filter((name) => name.endsWith('.jsonl'))
+    .map((name) => ({ path: join(directory, name), modified: statSync(join(directory, name)).mtimeMs }))
+    .sort((a, b) => b.modified - a.modified)[0]
+  return newest?.path ?? null
+}
+
+/**
+ * The log lines that show how full an agent's context is. The session id the terminal reports can be stale
+ * (a chat that was resumed or cleared keeps writing to another file), so a reported log without any answer
+ * gives way to the newest log of the agent's working directory. Null when neither exists.
+ */
+export const agentLog = (
+  { session, cwd }: AgentSession,
+  projectsDirectory: string = defaultProjectsDirectory(),
+): string[] | null => {
+  const reported = session ? sessionLog(session, projectsDirectory) : null
+  if (reported && hasAnswer(reported)) return reported
+  try {
+    const path = cwd ? newestLogOf(cwd, projectsDirectory) : null
+    return path ? readTailLines(path, TAIL_BYTES) : reported
+  } catch {
+    return reported
+  }
+}