@north-light/crouter-api 0.3.263 → 0.3.270

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/broker.d.ts

@@ -26,6 +26,10 @@ export interface BrokerWelcomeSnapshot<M = unknown> {
     messages: M[];
     /** Stable session-entry ids aligned 1:1 with `messages`. */
     messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
+    /** Presentation visibility of the run currently owned by the engine. */
+    turnVisibility: 'visible' | 'internal';
     state?: {
         isStreaming?: boolean;
     };
@@ -42,6 +46,11 @@ export interface BrokerWelcomeFrame<M = unknown> {
     type: 'welcome';
     snapshot?: BrokerWelcomeSnapshot<M>;
 }
+/** The presentation classification of the run whose native events follow. */
+export interface BrokerTurnVisibilityFrame {
+    type: 'turn_visibility';
+    visibility: 'visible' | 'internal';
+}
 /**
  * The crtrd broker `node_named` control frame — the node's generated name at the
  * instant crtrd committed it.
@@ -68,11 +77,11 @@ export interface BrokerNodeNamedFrame {
 }
 /**
  * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot),
- * `error`, and `node_named`. The broker interleaves others (display_*, ack, …)
+ * `turn_visibility`, `error`, and `node_named`. The broker interleaves others (display_*, ack, …)
  * under non-colliding `type` discriminants; a relay mapper drops those through its
  * `default` arm untyped, so they are not enumerated here.
  */
-export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerErrorFrame | BrokerNodeNamedFrame;
+export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerTurnVisibilityFrame | BrokerErrorFrame | BrokerNodeNamedFrame;
 /**
  * What the crtrd broker attach delivers to a relay consumer: the live engine
  * event stream (`E` — pi's `AgentSessionEvent`, relayed verbatim) unioned with the

package/dist/api/dto/broker.js

@@ -1,8 +1,8 @@
 // Broker attach-protocol envelope DTOs — the crtrd-specific control frames the
 // broker interleaves around pi's native agent-session event stream over a node's
 // `view.sock` (and its WS bridge, spec §5). This module owns ONLY that envelope
-// vocabulary: the two broker-control frames a relay consumer reads (`welcome` +
-// `error`), the welcome snapshot they carry, and the relay union that folds them
+// vocabulary: the broker-control frames a relay consumer reads, the welcome
+// snapshot they carry, and the relay union that folds them
 // together with the live engine event stream.
 //
 // PURITY (spec §3.1): like every file under `src/api/`, this imports NOTHING —

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/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). */
@@ -240,6 +244,8 @@ export interface NodeSnapshotDTO {
     snapshot: {
         messages: unknown[];
         messageIds?: string[];
+        messageVisibility: Array<'visible' | 'internal'>;
+        turnVisibility: 'visible' | 'internal';
         stats: unknown;
         state: Record<string, unknown>;
         display: {
@@ -278,6 +284,8 @@ export interface NodeMessagesPageDTO {
     messages: unknown[];
     /** Stable session-entry ids aligned 1:1 with `messages`. */
     message_ids?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    message_visibility: Array<'visible' | 'internal'>;
     /** Opaque cursor toward older messages; null at the start of the session. */
     next_cursor: Cursor | null;
     captured_at: IsoTime;

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/dist/shared/generated-context.d.ts

@@ -11,8 +11,7 @@ export declare const STALL_REPROMPT: string;
 /** The daemon's parking mandate: the last turn of a conversation the unattended
  *  clock is concluding. Delivered live, wrapped in a `park` runtime card. It
  *  governs both the node's durable inheritance and reader-facing output:
- *  one update for subscribers and history, then a silent stop with no assistant
- *  prose for an external channel to relay.
+ *  one update for subscribers and history, then a brief completion reply.
  *
  *  The durable inheritance shares a CONTRACT with `node yield`'s pre-invocation
  *  guide (roadmap current, short and shrinking; context dir for in-progress

package/dist/shared/generated-context.js

@@ -16,8 +16,7 @@ export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone a
 /** The daemon's parking mandate: the last turn of a conversation the unattended
  *  clock is concluding. Delivered live, wrapped in a `park` runtime card. It
  *  governs both the node's durable inheritance and reader-facing output:
- *  one update for subscribers and history, then a silent stop with no assistant
- *  prose for an external channel to relay.
+ *  one update for subscribers and history, then a brief completion reply.
  *
  *  The durable inheritance shares a CONTRACT with `node yield`'s pre-invocation
  *  guide (roadmap current, short and shrinking; context dir for in-progress
@@ -28,8 +27,8 @@ export const PARK_SUMMARY_PROMPT = 'This conversation has been idle with nothing
     + '2. Rewrite `$CRTR_CONTEXT_DIR/roadmap.md` for a fresh context window. This is the only handoff document a later fresh cycle receives in full. Preserve the current goal and exit criteria when they still apply, then state the present outcome; what remains or is blocked; decisions or questions still open; exact recovery handles for in-flight state; and the first safe move on return. Keep strategy and present state, not a transcript recap. Delete stale and completed steps instead of marking them done; the roadmap should stay short and shrink. Write a minimal one now if none exists.\n\n'
     + '3. Put supporting material in your context directory only when the roadmap would become bulky without it. Rewrite existing living documents rather than leave superseded versions. Name every supporting file the next cycle must read from the roadmap and say what it is for—the revive shows filenames but does not inject their contents. Task state, identifiers, and recovery detail belong here, not in memory.\n\n'
     + '4. Use memory only for a non-obvious, reusable lesson that should survive this task and is not already recorded. Read `crtr memory write -h`, find before writing, and choose the narrowest scope that will reach the next agent who needs it. Do not put a conversation recap, task status, recovery handles, or facts already captured in code or docs into memory.\n\n'
-    + '5. Push exactly one regular update with `crtr push update --tier deferred`, never `crtr push final`. Write it for subscribers and history, not as a second roadmap. Its first line must stand alone as the current outcome, blocker, or decision that matters; then include only unfinished work, a needed decision, and concrete handles a subscriber may need. This concludes the conversation; it does not finish the mandate.\n\n'
-    + '6. Keep this entire turn silent in the conversation: produce no assistant prose before, between, or after tool calls, and do not narrate the work. Once every required tool call has finished, end the response immediately without emitting any text, sign-off, summary, acknowledgement, or other visible content by emitting the `stop` token with no text. The deferred update from step 5 is the only reader-facing conclusion. A later message reopens you on a fresh context window grounded in your goal and roadmap, so the inheritance you leave now is what you get back.';
+    + '5. Push exactly one regular update with `crtr push update --tier deferred`, never `crtr push final`. Write for someone who has not seen this conversation: name the work in plain terms, say where it stands, and say what remains or is blocked. Put the current outcome in the first line; include only needed decisions and recovery handles. This concludes the conversation, not the mandate.\n\n'
+    + '6. When finished, reply with exactly `done`.';
 /** Static recovery prompts shared by the broker producer and display classifier. */
 export const AUTH_FAULT_RECOVERY_BODY = 'Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.';
 export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.263",
+  "version": "0.3.270",
   "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",