@north-light/crouter-api 0.3.262 → 0.3.269

package/dist/api/client.d.ts

@@ -19,7 +19,7 @@ import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, Review
 import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
 import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
 import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest } from './dto/human-requests.js';
-import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
+import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryStatsQuery, HistoryStatsResultDTO, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { AbandonWorktreeRequest, AbandonWorktreeResultDTO, CloseWorktreeResultDTO, QuarantinedWorktreeDTO } from './dto/worktree.js';
 import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
 export interface CrtrClientOptions {
@@ -279,6 +279,10 @@ export declare class CrtrClient {
     /** Resolve one `<node-id>:<relpath>` history ref to its full body
      *  (`crtr canvas history read`). */
     historyRead(q: HistoryReadQuery): Promise<HistoryReadResultDTO>;
+    /** Grouped-count projection over the per-cwd episodic corpus
+     *  (`crtr canvas history stats`). Same filters as search/grep, aggregate
+     *  result instead of a hit page — POST-bodied for the same reasons. */
+    historyStats(q: HistoryStatsQuery): Promise<HistoryStatsResultDTO>;
     /** The machine-readable browser canvas roster (`crtr canvas snapshot`) —
      *  distinct from the per-node `getSnapshot`. */
     canvasSnapshot(): Promise<SnapshotDTO>;

package/dist/api/client.js

@@ -519,6 +519,12 @@ export class CrtrClient {
     historyRead(q) {
         return this.request('GET', withQuery(routes.canvasHistoryRead(), q));
     }
+    /** Grouped-count projection over the per-cwd episodic corpus
+     *  (`crtr canvas history stats`). Same filters as search/grep, aggregate
+     *  result instead of a hit page — POST-bodied for the same reasons. */
+    historyStats(q) {
+        return this.request('POST', routes.canvasHistoryStats(), q);
+    }
     /** The machine-readable browser canvas roster (`crtr canvas snapshot`) —
      *  distinct from the per-node `getSnapshot`. */
     canvasSnapshot() {

package/dist/api/dto/canvas.d.ts

@@ -52,7 +52,7 @@ export interface HistorySearchQuery {
     under?: string;
     /** Restrict to specific node ids. */
     nodes?: string[];
-    /** Corpus types: report | doc | roadmap | meta | inbox. */
+    /** Corpus types: report | doc | roadmap | meta | inbox | transcript. */
     types?: string[];
     report_kind?: string;
     kinds?: string[];
@@ -61,6 +61,12 @@ export interface HistorySearchQuery {
     since_ms?: number;
     /** Upper bound on artifact timestamp (epoch ms), parsed CLI-side. */
     until_ms?: number;
+    /** Inbound-message narrowing (transcript + inbox): what drove arrival. */
+    origins?: string[];
+    /** Transcript-message roles: user | assistant | toolResult. */
+    roles?: string[];
+    /** Case-insensitive substring against sender attribution. */
+    from?: string;
     /** Weigh full body text in ranking (`--body`). */
     weigh_body?: boolean;
     /** relevance | recency | oldest — already resolved to the effective sort. */
@@ -93,7 +99,7 @@ export interface HistoryGrepQuery {
     under?: string;
     /** Restrict to specific node ids. */
     nodes?: string[];
-    /** Corpus types: report | doc | roadmap | meta | inbox. */
+    /** Corpus types: report | doc | roadmap | meta | inbox | transcript. */
     types?: string[];
     report_kind?: string;
     kinds?: string[];
@@ -102,9 +108,50 @@ export interface HistoryGrepQuery {
     since_ms?: number;
     /** Upper bound on artifact timestamp (epoch ms), parsed CLI-side. */
     until_ms?: number;
+    /** Inbound-message narrowing (transcript + inbox): what drove arrival. */
+    origins?: string[];
+    /** Transcript-message roles: user | assistant | toolResult. */
+    roles?: string[];
+    /** Case-insensitive substring against sender attribution. */
+    from?: string;
     limit?: number;
     cursor?: Cursor;
 }
+/** `POST /v1/canvas/history/stats` body — the grouped-count projection over
+ *  the same corpus search and grep scan, backing `crtr canvas history stats`.
+ *  Shares every scope/corpus/message filter; carries no query, pattern, or
+ *  pagination because the result is an aggregate, not a hit list. */
+export interface HistoryStatsQuery {
+    /** origin | node | kind | day | type | role. Defaults to type. */
+    group_by?: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    nodes?: string[];
+    types?: string[];
+    report_kind?: string;
+    kinds?: string[];
+    statuses?: string[];
+    since_ms?: number;
+    until_ms?: number;
+    origins?: string[];
+    roles?: string[];
+    from?: string;
+}
+/** `POST /v1/canvas/history/stats` result — counts by the grouped dimension,
+ *  descending. `total` counts the artifacts that carried the dimension, so it
+ *  can be lower than the corpus size when grouping by one not every artifact
+ *  has (origin, role). */
+export interface HistoryStatsResultDTO {
+    group_by: string;
+    groups: Array<{
+        key: string;
+        count: number;
+    }>;
+    total: number;
+    /** Artifacts scanned before the grouping dimension was applied. */
+    scanned: number;
+}
 /** One matching body line from `crtr canvas history grep`. */
 export interface HistoryGrepHitDTO {
     ref: string;
@@ -126,6 +173,10 @@ export interface HistoryReadQuery {
     ref: string;
     /** Keep the artifact's YAML frontmatter (stripped by default). */
     frontmatter?: boolean;
+    /** `rendered` (default) or `raw` — the verbatim bytes behind the ref: the
+     *  session file for a bare `session` ref, the one jsonl line for a message,
+     *  the unparsed file for a report or doc. */
+    format?: string;
 }
 /** `GET /v1/canvas/history/read` result — one hit's full body. */
 export interface HistoryReadResultDTO {

package/dist/api/dto/health.d.ts

@@ -15,6 +15,8 @@ export interface StatusDTO {
     tick_interval_ms: number;
     /** Node counts keyed by status. */
     node_counts: Partial<Record<NodeStatusDTO, number>>;
+    /** Nodes genuinely mid-turn: their busy marker exists and their recorded pid is alive. Unlike `node_counts.active`, this excludes live-but-waiting, parked, or blocked engines. */
+    busy_node_count: number;
     /** Bound listener addresses. `tcp` is null when the TCP listener is off. */
     listeners: {
         socket_path: string;

package/dist/api/dto/nodes.d.ts

@@ -67,6 +67,12 @@ export interface CreateNodeRequest {
 export interface NodeSummaryDTO {
     node_id: NodeIdDTO;
     name: string;
+    /** Generated first-task description, absent when the node is not yet named.
+     *  Paired with `name` it forms the full display label, so a roster consumer
+     *  builds it without a per-node metadata fetch. */
+    description?: string;
+    /** How many times the node has been (re)launched; absent on a pre-v38 row. */
+    cycles?: number;
     kind: string;
     mode: ModeDTO;
     lifecycle: LifecycleDTO;
@@ -169,7 +175,6 @@ export interface NodeFaultDTO {
 export interface NodeDetailDTO extends NodeSummaryDTO {
     /** Node that created this node, or null when an external process did. */
     creator: NodeIdDTO | null;
-    description?: string;
     /** The namer's prose form of `description` — sentence case, punctuation intact
      *  (`NodeMeta.title`). What a surface showing this node to a person reads;
      *  absent on a node named before titles existed. */
@@ -177,7 +182,6 @@ export interface NodeDetailDTO extends NodeSummaryDTO {
     /** The Nerd Font glyph the namer chose for this node's work, when it has one
      *  (`NodeMeta.icon`). Rendered ahead of the label by surfaces that want it. */
     icon?: string;
-    cycles?: number;
     /** Approximate context-window token load of the node's live/last session,
      *  used by the orchestrator yield-nudge (`childFollowUp`). Null when unknown
      *  (never launched, or no token accounting yet). */

package/dist/api/routes.d.ts

@@ -59,6 +59,7 @@ export declare const routes: {
     readonly canvasHistorySearch: () => string;
     readonly canvasHistoryGrep: () => string;
     readonly canvasHistoryRead: () => string;
+    readonly canvasHistoryStats: () => string;
     readonly canvasSnapshot: () => string;
     readonly canvasRoster: () => string;
     readonly canvasPrune: () => string;

package/dist/api/routes.js

@@ -81,6 +81,7 @@ export const routes = {
     canvasHistorySearch: () => `${V}/canvas/history/search`,
     canvasHistoryGrep: () => `${V}/canvas/history/grep`,
     canvasHistoryRead: () => `${V}/canvas/history/read`,
+    canvasHistoryStats: () => `${V}/canvas/history/stats`,
     canvasSnapshot: () => `${V}/canvas/snapshot`,
     canvasRoster: () => `${V}/canvas/roster`,
     canvasPrune: () => `${V}/canvas/prune`,

package/dist/shared/env.d.ts

@@ -8,6 +8,8 @@ export declare function envNodeCwd(): string | undefined;
  *  undefined. Cleared (not read) via `delete process.env['CRTR_MODEL_INTENT']`
  *  in `runtime/broker.ts` — a mutation, not a read, so it stays there. */
 export declare function envModelIntent(): string | undefined;
+/** Whether the launch recipe requires this broker to keep its exact provider/model. */
+export declare function envModelExact(): boolean;
 /** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
  *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
  *  only when a caller needs the override itself — to check whether one is
@@ -67,6 +69,14 @@ export declare function envWarnLiveBrokers(): number | undefined;
 /** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
  *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
 export declare function envTestUnattendedParkMs(): number | undefined;
+/** Production unattended-park interval override (`CRTR_UNATTENDED_PARK_MS`), in
+ *  milliseconds; wins over the user-scope config value
+ *  (`readConfig('user').lifecycle.unattendedParkMs`, itself defaulting to 15
+ *  min) whenever set, autostart or not. Unlike `CRTR_TEST_UNATTENDED_PARK_MS`
+ *  this is not gated on `envNoDaemonAutostart()`: it is the env escape hatch
+ *  above the configured knob a deployment sets to tune how long an eligible
+ *  resident idles before its parking turn. */
+export declare function envUnattendedParkMs(): number | undefined;
 /** Test-only park-summary grace-period override
  *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
 export declare function envTestParkSummaryGraceMs(): number | undefined;

package/dist/shared/env.js

@@ -40,6 +40,10 @@ export function envNodeCwd() {
 export function envModelIntent() {
     return process.env['CRTR_MODEL_INTENT'];
 }
+/** Whether the launch recipe requires this broker to keep its exact provider/model. */
+export function envModelExact() {
+    return process.env['CRTR_MODEL_EXACT'] === '1';
+}
 /** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
  *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
  *  only when a caller needs the override itself — to check whether one is
@@ -140,10 +144,11 @@ export function envDebug() {
     return process.env['CRTR_DEBUG'] === '1';
 }
 // Precedence — broker-supervision.ts's threshold/interval overrides. Each
-// returns the raw parsed value with NO default: the caller (config for the
-// thresholds, a hardcoded production constant for the intervals) supplies
-// the default, and env wins over it when set. Undefined, unparseable, or
-// non-positive all mean "no override" — the caller's own default applies.
+// returns the raw parsed value with NO default: the caller supplies the
+// default (user config for the broker thresholds and the unattended-park
+// interval, a hardcoded constant for the test-only park-summary grace), and
+// env wins over it when set. Undefined, unparseable, or non-positive all mean
+// "no override" — the caller's own default applies.
 function parsePositiveInteger(raw) {
     if (raw === undefined || raw === '')
         return undefined;
@@ -171,6 +176,16 @@ function parsePositiveMsNoDefault(raw) {
 export function envTestUnattendedParkMs() {
     return parsePositiveMsNoDefault(process.env['CRTR_TEST_UNATTENDED_PARK_MS']);
 }
+/** Production unattended-park interval override (`CRTR_UNATTENDED_PARK_MS`), in
+ *  milliseconds; wins over the user-scope config value
+ *  (`readConfig('user').lifecycle.unattendedParkMs`, itself defaulting to 15
+ *  min) whenever set, autostart or not. Unlike `CRTR_TEST_UNATTENDED_PARK_MS`
+ *  this is not gated on `envNoDaemonAutostart()`: it is the env escape hatch
+ *  above the configured knob a deployment sets to tune how long an eligible
+ *  resident idles before its parking turn. */
+export function envUnattendedParkMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_UNATTENDED_PARK_MS']);
+}
 /** Test-only park-summary grace-period override
  *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
 export function envTestParkSummaryGraceMs() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.262",
+  "version": "0.3.269",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",