@agentshouse/session-content 0.0.0-stage → 0.1.0-c27fa9c4d6971

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton (trof3039)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# `@agentshouse/session-content`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Session content is one model of what an agent CLI's session reports of its work, the same for
+every CLI: a turn's parts and the session's state. It has no dependencies and runs in Node and
+in the browser.
+
+- A turn is an ordered list of parts: text, reasoning, calls by kind (`command`, `edit`,
+  `read`, `search`, `fetch`, `tool`, `other`), sub-agents, messages between agents, images, a
+  plan, notices and background work. A part's `parent` is the index of the sub-agent whose own
+  work it is, or `null`, so sub-agents nest at any depth.
+- A running turn changes by operations: `start` a part at the end, or at `0` to begin the turn
+  again, `append` text to a text or reasoning part, and `set` a part to a new version of itself.
+  `applied` folds one operation into the parts and answers `null` for one that does not fit.
+- The session's state holds its title, context, limits, cost, tokens, the last turn's duration,
+  the files changed, git branch, worktree and pull request, model, effort, mode, the suggested
+  next prompt and the work that still runs.
+- Bulk is bounded: a command keeps its last `OUTPUT_LINES` lines of at most
+  `OUTPUT_CHARACTERS`, an edit's diff of a file at most `DIFF_CHARACTERS` and beyond that only its
+  line counts, a fetched page's, a tool's or another call's result its first
+  `FIRST_PART_CHARACTERS`. `lastLines`, `keptDiff` and `firstPart` cut to those bounds.
+
+```ts
+import { applied, isOperation, isTurn, type Part } from '@agentshouse/session-content';
+
+let parts: readonly Part[] = [];
+for (const operation of received) {
+  if (!isOperation(operation)) throw new Error('not Session content');
+  parts = applied(parts, operation) ?? parts;
+}
+isTurn({ parts, tokens: null, state });
+```
+
+`isPart`, `isOperation`, `isState` and `isTurn` check a value and narrow its type.

package/dist/bounds.d.ts

@@ -0,0 +1,7 @@
+export declare const OUTPUT_LINES = 20;
+export declare const OUTPUT_CHARACTERS = 4000;
+export declare const DIFF_CHARACTERS = 10000;
+export declare const FIRST_PART_CHARACTERS = 2000;
+export declare function lastLines(output: string): string;
+export declare function firstPart(result: string): string;
+export declare function keptDiff(diff: string): string | null;

package/dist/bounds.js

@@ -0,0 +1,20 @@
+export const OUTPUT_LINES = 20;
+export const OUTPUT_CHARACTERS = 4000;
+export const DIFF_CHARACTERS = 10_000;
+export const FIRST_PART_CHARACTERS = 2000;
+const LOW_SURROGATE = /^[\uDC00-\uDFFF]/u;
+const HIGH_SURROGATE = /[\uD800-\uDBFF]$/u;
+export function lastLines(output) {
+    const lines = output.split('\n').slice(-OUTPUT_LINES).join('\n');
+    if (lines.length <= OUTPUT_CHARACTERS)
+        return lines;
+    return lines.slice(-OUTPUT_CHARACTERS).replace(LOW_SURROGATE, '');
+}
+export function firstPart(result) {
+    if (result.length <= FIRST_PART_CHARACTERS)
+        return result;
+    return result.slice(0, FIRST_PART_CHARACTERS).replace(HIGH_SURROGATE, '');
+}
+export function keptDiff(diff) {
+    return diff.length <= DIFF_CHARACTERS ? diff : null;
+}

package/dist/check.d.ts

@@ -0,0 +1,18 @@
+export type Check<T> = (value: unknown) => value is T;
+export type Checked<C> = C extends Check<infer T> ? T : never;
+type Shape = Readonly<Record<string, Check<unknown>>>;
+export type Shaped<S extends Shape> = {
+    readonly [K in keyof S]: Checked<S[K]>;
+};
+export declare const text: Check<string>;
+export declare const integer: Check<number>;
+export declare const count: Check<number>;
+export declare const figure: Check<number>;
+export declare const instant: Check<string>;
+export declare function oneOf<const V extends readonly string[]>(...values: V): Check<V[number]>;
+export declare function where<T>(check: Check<T>, holds: (value: T) => boolean): Check<T>;
+export declare function nullable<T>(check: Check<T>): Check<T | null>;
+export declare function list<T>(check: Check<T>): Check<readonly T[]>;
+export declare function exact<const S extends Shape>(shape: S): Check<Shaped<S>>;
+export declare function anyOf<const C extends readonly Check<unknown>[]>(...checks: C): Check<Checked<C[number]>>;
+export {};

package/dist/check.js

@@ -0,0 +1,31 @@
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u;
+export const text = (value) => typeof value === 'string';
+export const integer = (value) => Number.isSafeInteger(value);
+export const count = (value) => integer(value) && value >= 0;
+export const figure = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+export const instant = (value) => text(value) && INSTANT.test(value) && !Number.isNaN(Date.parse(value));
+export function oneOf(...values) {
+    return (value) => values.includes(value);
+}
+export function where(check, holds) {
+    return (value) => check(value) && holds(value);
+}
+export function nullable(check) {
+    return (value) => value === null || check(value);
+}
+export function list(check) {
+    return (value) => Array.isArray(value) && value.every(check);
+}
+export function exact(shape) {
+    const keys = Object.keys(shape);
+    return (value) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return false;
+        const held = value;
+        return (Object.keys(held).length === keys.length &&
+            keys.every((key) => Object.hasOwn(held, key) && shape[key](held[key])));
+    };
+}
+export function anyOf(...checks) {
+    return (value) => checks.some((check) => check(value));
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DIFF_CHARACTERS, FIRST_PART_CHARACTERS, firstPart, keptDiff, lastLines, OUTPUT_CHARACTERS, OUTPUT_LINES, } from './bounds.js';
+export { isPart } from './parts.js';
+export type { Call, FileChange, Part, Status } from './parts.js';
+export { isState } from './state.js';
+export type { SessionState, Tokens } from './state.js';
+export { applied, isOperation, isTurn } from './turn.js';
+export type { Operation, Turn } from './turn.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { DIFF_CHARACTERS, FIRST_PART_CHARACTERS, firstPart, keptDiff, lastLines, OUTPUT_CHARACTERS, OUTPUT_LINES, } from './bounds.js';
+export { isPart } from './parts.js';
+export { isState } from './state.js';
+export { applied, isOperation, isTurn } from './turn.js';

package/dist/parts.d.ts

@@ -0,0 +1,101 @@
+import { type Check, type Checked } from './check.js';
+declare const STATUS: Check<"done" | "failed" | "running" | "stopped">;
+export type Status = Checked<typeof STATUS>;
+declare const FILE_CHANGE: Check<import("./check.js").Shaped<{
+    readonly path: Check<string>;
+    readonly added: Check<number>;
+    readonly removed: Check<number>;
+    readonly diff: Check<string | null>;
+}>>;
+export type FileChange = Checked<typeof FILE_CHANGE>;
+export declare const BACKGROUND_KINDS: readonly ['shell', 'task', 'monitor', 'schedule'];
+declare const PART: Check<import("./check.js").Shaped<{
+    readonly type: Check<"call">;
+    readonly parent: Check<number | null>;
+    readonly line: Check<string>;
+    readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    readonly duration: Check<number | null>;
+    readonly kind: Check<"command">;
+    readonly exit: Check<number | null>;
+    readonly output: Check<string>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"call">;
+    readonly parent: Check<number | null>;
+    readonly line: Check<string>;
+    readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    readonly duration: Check<number | null>;
+    readonly kind: Check<"edit">;
+    readonly files: Check<readonly import("./check.js").Shaped<{
+        readonly path: Check<string>;
+        readonly added: Check<number>;
+        readonly removed: Check<number>;
+        readonly diff: Check<string | null>;
+    }>[]>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"call">;
+    readonly parent: Check<number | null>;
+    readonly line: Check<string>;
+    readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    readonly duration: Check<number | null>;
+    readonly kind: Check<"read" | "search">;
+    readonly returned: Check<number | null>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"call">;
+    readonly parent: Check<number | null>;
+    readonly line: Check<string>;
+    readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    readonly duration: Check<number | null>;
+    readonly kind: Check<"fetch" | "other" | "tool">;
+    readonly output: Check<string>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"subagent">;
+    readonly parent: Check<number | null>;
+    readonly kind: Check<"agent" | "fork" | "workflow">;
+    readonly name: Check<string | null>;
+    readonly task: Check<string>;
+    readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    readonly step: Check<string | null>;
+    readonly report: Check<string | null>;
+    readonly tokens: Check<number | null>;
+    readonly calls: Check<number | null>;
+    readonly duration: Check<number | null>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"reasoning" | "text">;
+    readonly parent: Check<number | null>;
+    readonly text: Check<string>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"message">;
+    readonly parent: Check<number | null>;
+    readonly command: Check<string>;
+    readonly target: Check<string | null>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"image">;
+    readonly parent: Check<number | null>;
+    readonly file: Check<string>;
+    readonly name: Check<string>;
+    readonly media_type: Check<string>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"plan">;
+    readonly parent: Check<number | null>;
+    readonly entries: Check<readonly import("./check.js").Shaped<{
+        readonly content: Check<string>;
+        readonly status: Check<"done" | "pending" | "running">;
+    }>[]>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"notice">;
+    readonly parent: Check<number | null>;
+    readonly kind: Check<"compaction" | "error" | "info" | "mode" | "model" | "retry" | "warning">;
+    readonly text: Check<string>;
+}> | import("./check.js").Shaped<{
+    readonly type: Check<"background">;
+    readonly parent: Check<number | null>;
+    readonly kind: Check<"monitor" | "schedule" | "shell" | "task">;
+    readonly label: Check<string>;
+    readonly status: Check<"done" | "failed" | "running" | "stopped">;
+}>>;
+export type Part = Checked<typeof PART>;
+export type Call = Extract<Part, {
+    readonly type: 'call';
+}>;
+export declare const isPart: Check<Part>;
+export {};

package/dist/parts.js

@@ -0,0 +1,65 @@
+import { DIFF_CHARACTERS, firstPart, lastLines } from './bounds.js';
+import { anyOf, count, exact, integer, list, nullable, oneOf, text, where, } from './check.js';
+const STATUS = oneOf('running', 'done', 'failed', 'stopped');
+const PARENT = nullable(count);
+const CALL = {
+    type: oneOf('call'),
+    parent: PARENT,
+    line: text,
+    status: STATUS,
+    duration: nullable(count),
+};
+const LAST_LINES = where(text, (output) => lastLines(output) === output);
+const FIRST_PART = where(text, (output) => firstPart(output) === output);
+const FILE_CHANGE = exact({
+    path: text,
+    added: count,
+    removed: count,
+    diff: nullable(where(text, (diff) => diff.length <= DIFF_CHARACTERS)),
+});
+const COMMAND = exact({
+    ...CALL,
+    kind: oneOf('command'),
+    exit: nullable(integer),
+    output: LAST_LINES,
+});
+const EDIT = exact({ ...CALL, kind: oneOf('edit'), files: list(FILE_CHANGE) });
+const READ = exact({ ...CALL, kind: oneOf('read', 'search'), returned: nullable(count) });
+const RESULT = exact({ ...CALL, kind: oneOf('fetch', 'tool', 'other'), output: FIRST_PART });
+const SUBAGENT = exact({
+    type: oneOf('subagent'),
+    parent: PARENT,
+    kind: oneOf('agent', 'fork', 'workflow'),
+    name: nullable(text),
+    task: text,
+    status: STATUS,
+    step: nullable(text),
+    report: nullable(text),
+    tokens: nullable(count),
+    calls: nullable(count),
+    duration: nullable(count),
+});
+export const BACKGROUND_KINDS = ['shell', 'task', 'monitor', 'schedule'];
+const PART = anyOf(exact({ type: oneOf('text', 'reasoning'), parent: PARENT, text }), COMMAND, EDIT, READ, RESULT, SUBAGENT, exact({ type: oneOf('message'), parent: PARENT, command: text, target: nullable(text) }), exact({
+    type: oneOf('image'),
+    parent: PARENT,
+    file: where(text, (file) => file !== ''),
+    name: text,
+    media_type: text,
+}), exact({
+    type: oneOf('plan'),
+    parent: PARENT,
+    entries: list(exact({ content: text, status: oneOf('pending', 'running', 'done') })),
+}), exact({
+    type: oneOf('notice'),
+    parent: PARENT,
+    kind: oneOf('mode', 'model', 'compaction', 'retry', 'info', 'warning', 'error'),
+    text,
+}), exact({
+    type: oneOf('background'),
+    parent: PARENT,
+    kind: oneOf(...BACKGROUND_KINDS),
+    label: text,
+    status: STATUS,
+}));
+export const isPart = PART;

package/dist/state.d.ts

@@ -0,0 +1,60 @@
+import { type Check, type Checked } from './check.js';
+export declare const TOKENS: Check<import("./check.js").Shaped<{
+    readonly input: Check<number>;
+    readonly output: Check<number>;
+    readonly cache_read: Check<number>;
+    readonly cache_write: Check<number>;
+}>>;
+export type Tokens = Checked<typeof TOKENS>;
+declare const STATE: Check<import("./check.js").Shaped<{
+    readonly title: Check<string | null>;
+    readonly context: Check<import("./check.js").Shaped<{
+        readonly used: Check<number>;
+        readonly window: Check<number>;
+        readonly breakdown: Check<readonly import("./check.js").Shaped<{
+            readonly name: Check<string>;
+            readonly tokens: Check<number>;
+        }>[]>;
+    }> | null>;
+    readonly limits: Check<readonly import("./check.js").Shaped<{
+        readonly name: Check<string | null>;
+        readonly minutes: Check<number>;
+        readonly percent: Check<number>;
+        readonly resets: Check<string | null>;
+    }>[]>;
+    readonly cost: Check<import("./check.js").Shaped<{
+        readonly amount: Check<number>;
+        readonly currency: Check<string>;
+    }> | null>;
+    readonly tokens: Check<import("./check.js").Shaped<{
+        readonly input: Check<number>;
+        readonly output: Check<number>;
+        readonly cache_read: Check<number>;
+        readonly cache_write: Check<number>;
+    }> | null>;
+    readonly duration: Check<number | null>;
+    readonly files: Check<readonly import("./check.js").Shaped<{
+        readonly path: Check<string>;
+        readonly added: Check<number>;
+        readonly removed: Check<number>;
+    }>[]>;
+    readonly branch: Check<string | null>;
+    readonly worktree: Check<string | null>;
+    readonly pull: Check<import("./check.js").Shaped<{
+        readonly number: Check<number>;
+        readonly url: Check<string>;
+    }> | null>;
+    readonly model: Check<string | null>;
+    readonly effort: Check<string | null>;
+    readonly mode: Check<string | null>;
+    readonly suggestion: Check<string | null>;
+    readonly running: Check<readonly import("./check.js").Shaped<{
+        readonly kind: Check<"monitor" | "schedule" | "shell" | "subagent" | "task">;
+        readonly label: Check<string>;
+        readonly progress: Check<string | null>;
+        readonly next: Check<string | null>;
+    }>[]>;
+}>>;
+export type SessionState = Checked<typeof STATE>;
+export declare const isState: Check<SessionState>;
+export {};

package/dist/state.js

@@ -0,0 +1,30 @@
+import { count, exact, figure, instant, list, nullable, oneOf, text, } from './check.js';
+import { BACKGROUND_KINDS } from './parts.js';
+export const TOKENS = exact({ input: count, output: count, cache_read: count, cache_write: count });
+const STATE = exact({
+    title: nullable(text),
+    context: nullable(exact({
+        used: count,
+        window: count,
+        breakdown: list(exact({ name: text, tokens: count })),
+    })),
+    limits: list(exact({ name: nullable(text), minutes: count, percent: figure, resets: nullable(instant) })),
+    cost: nullable(exact({ amount: figure, currency: text })),
+    tokens: nullable(TOKENS),
+    duration: nullable(count),
+    files: list(exact({ path: text, added: count, removed: count })),
+    branch: nullable(text),
+    worktree: nullable(text),
+    pull: nullable(exact({ number: count, url: text })),
+    model: nullable(text),
+    effort: nullable(text),
+    mode: nullable(text),
+    suggestion: nullable(text),
+    running: list(exact({
+        kind: oneOf('subagent', ...BACKGROUND_KINDS),
+        label: text,
+        progress: nullable(text),
+        next: nullable(instant),
+    })),
+});
+export const isState = STATE;

package/dist/turn.d.ts

@@ -0,0 +1,328 @@
+import { type Check, type Checked } from './check.js';
+import { type Part } from './parts.js';
+declare const OPERATION: Check<import("./check.js").Shaped<{
+    readonly op: Check<"start">;
+    readonly index: Check<number>;
+    readonly part: Check<import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"command">;
+        readonly exit: Check<number | null>;
+        readonly output: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"edit">;
+        readonly files: Check<readonly import("./check.js").Shaped<{
+            readonly path: Check<string>;
+            readonly added: Check<number>;
+            readonly removed: Check<number>;
+            readonly diff: Check<string | null>;
+        }>[]>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"read" | "search">;
+        readonly returned: Check<number | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"fetch" | "other" | "tool">;
+        readonly output: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"subagent">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"agent" | "fork" | "workflow">;
+        readonly name: Check<string | null>;
+        readonly task: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly step: Check<string | null>;
+        readonly report: Check<string | null>;
+        readonly tokens: Check<number | null>;
+        readonly calls: Check<number | null>;
+        readonly duration: Check<number | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"reasoning" | "text">;
+        readonly parent: Check<number | null>;
+        readonly text: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"message">;
+        readonly parent: Check<number | null>;
+        readonly command: Check<string>;
+        readonly target: Check<string | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"image">;
+        readonly parent: Check<number | null>;
+        readonly file: Check<string>;
+        readonly name: Check<string>;
+        readonly media_type: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"plan">;
+        readonly parent: Check<number | null>;
+        readonly entries: Check<readonly import("./check.js").Shaped<{
+            readonly content: Check<string>;
+            readonly status: Check<"done" | "pending" | "running">;
+        }>[]>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"notice">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"compaction" | "error" | "info" | "mode" | "model" | "retry" | "warning">;
+        readonly text: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"background">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"monitor" | "schedule" | "shell" | "task">;
+        readonly label: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    }>>;
+}> | import("./check.js").Shaped<{
+    readonly op: Check<"append">;
+    readonly index: Check<number>;
+    readonly text: Check<string>;
+}> | import("./check.js").Shaped<{
+    readonly op: Check<"set">;
+    readonly index: Check<number>;
+    readonly part: Check<import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"command">;
+        readonly exit: Check<number | null>;
+        readonly output: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"edit">;
+        readonly files: Check<readonly import("./check.js").Shaped<{
+            readonly path: Check<string>;
+            readonly added: Check<number>;
+            readonly removed: Check<number>;
+            readonly diff: Check<string | null>;
+        }>[]>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"read" | "search">;
+        readonly returned: Check<number | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"fetch" | "other" | "tool">;
+        readonly output: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"subagent">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"agent" | "fork" | "workflow">;
+        readonly name: Check<string | null>;
+        readonly task: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly step: Check<string | null>;
+        readonly report: Check<string | null>;
+        readonly tokens: Check<number | null>;
+        readonly calls: Check<number | null>;
+        readonly duration: Check<number | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"reasoning" | "text">;
+        readonly parent: Check<number | null>;
+        readonly text: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"message">;
+        readonly parent: Check<number | null>;
+        readonly command: Check<string>;
+        readonly target: Check<string | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"image">;
+        readonly parent: Check<number | null>;
+        readonly file: Check<string>;
+        readonly name: Check<string>;
+        readonly media_type: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"plan">;
+        readonly parent: Check<number | null>;
+        readonly entries: Check<readonly import("./check.js").Shaped<{
+            readonly content: Check<string>;
+            readonly status: Check<"done" | "pending" | "running">;
+        }>[]>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"notice">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"compaction" | "error" | "info" | "mode" | "model" | "retry" | "warning">;
+        readonly text: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"background">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"monitor" | "schedule" | "shell" | "task">;
+        readonly label: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    }>>;
+}>>;
+export type Operation = Checked<typeof OPERATION>;
+export declare const isOperation: Check<Operation>;
+declare const TURN: Check<import("./check.js").Shaped<{
+    readonly parts: Check<readonly (import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"command">;
+        readonly exit: Check<number | null>;
+        readonly output: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"edit">;
+        readonly files: Check<readonly import("./check.js").Shaped<{
+            readonly path: Check<string>;
+            readonly added: Check<number>;
+            readonly removed: Check<number>;
+            readonly diff: Check<string | null>;
+        }>[]>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"read" | "search">;
+        readonly returned: Check<number | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"call">;
+        readonly parent: Check<number | null>;
+        readonly line: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly duration: Check<number | null>;
+        readonly kind: Check<"fetch" | "other" | "tool">;
+        readonly output: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"subagent">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"agent" | "fork" | "workflow">;
+        readonly name: Check<string | null>;
+        readonly task: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+        readonly step: Check<string | null>;
+        readonly report: Check<string | null>;
+        readonly tokens: Check<number | null>;
+        readonly calls: Check<number | null>;
+        readonly duration: Check<number | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"reasoning" | "text">;
+        readonly parent: Check<number | null>;
+        readonly text: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"message">;
+        readonly parent: Check<number | null>;
+        readonly command: Check<string>;
+        readonly target: Check<string | null>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"image">;
+        readonly parent: Check<number | null>;
+        readonly file: Check<string>;
+        readonly name: Check<string>;
+        readonly media_type: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"plan">;
+        readonly parent: Check<number | null>;
+        readonly entries: Check<readonly import("./check.js").Shaped<{
+            readonly content: Check<string>;
+            readonly status: Check<"done" | "pending" | "running">;
+        }>[]>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"notice">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"compaction" | "error" | "info" | "mode" | "model" | "retry" | "warning">;
+        readonly text: Check<string>;
+    }> | import("./check.js").Shaped<{
+        readonly type: Check<"background">;
+        readonly parent: Check<number | null>;
+        readonly kind: Check<"monitor" | "schedule" | "shell" | "task">;
+        readonly label: Check<string>;
+        readonly status: Check<"done" | "failed" | "running" | "stopped">;
+    }>)[]>;
+    readonly tokens: Check<import("./check.js").Shaped<{
+        readonly input: Check<number>;
+        readonly output: Check<number>;
+        readonly cache_read: Check<number>;
+        readonly cache_write: Check<number>;
+    }> | null>;
+    readonly state: Check<import("./check.js").Shaped<{
+        readonly title: Check<string | null>;
+        readonly context: Check<import("./check.js").Shaped<{
+            readonly used: Check<number>;
+            readonly window: Check<number>;
+            readonly breakdown: Check<readonly import("./check.js").Shaped<{
+                readonly name: Check<string>;
+                readonly tokens: Check<number>;
+            }>[]>;
+        }> | null>;
+        readonly limits: Check<readonly import("./check.js").Shaped<{
+            readonly name: Check<string | null>;
+            readonly minutes: Check<number>;
+            readonly percent: Check<number>;
+            readonly resets: Check<string | null>;
+        }>[]>;
+        readonly cost: Check<import("./check.js").Shaped<{
+            readonly amount: Check<number>;
+            readonly currency: Check<string>;
+        }> | null>;
+        readonly tokens: Check<import("./check.js").Shaped<{
+            readonly input: Check<number>;
+            readonly output: Check<number>;
+            readonly cache_read: Check<number>;
+            readonly cache_write: Check<number>;
+        }> | null>;
+        readonly duration: Check<number | null>;
+        readonly files: Check<readonly import("./check.js").Shaped<{
+            readonly path: Check<string>;
+            readonly added: Check<number>;
+            readonly removed: Check<number>;
+        }>[]>;
+        readonly branch: Check<string | null>;
+        readonly worktree: Check<string | null>;
+        readonly pull: Check<import("./check.js").Shaped<{
+            readonly number: Check<number>;
+            readonly url: Check<string>;
+        }> | null>;
+        readonly model: Check<string | null>;
+        readonly effort: Check<string | null>;
+        readonly mode: Check<string | null>;
+        readonly suggestion: Check<string | null>;
+        readonly running: Check<readonly import("./check.js").Shaped<{
+            readonly kind: Check<"monitor" | "schedule" | "shell" | "subagent" | "task">;
+            readonly label: Check<string>;
+            readonly progress: Check<string | null>;
+            readonly next: Check<string | null>;
+        }>[]>;
+    }>>;
+}>>;
+export type Turn = Checked<typeof TURN>;
+export declare const isTurn: Check<Turn>;
+export declare function applied(parts: readonly Part[], operation: Operation): readonly Part[] | null;
+export {};

package/dist/turn.js

@@ -0,0 +1,33 @@
+import { anyOf, count, exact, list, nullable, oneOf, text, where, } from './check.js';
+import { isPart } from './parts.js';
+import { isState, TOKENS } from './state.js';
+const OPERATION = anyOf(exact({ op: oneOf('start'), index: count, part: isPart }), exact({ op: oneOf('append'), index: count, text }), exact({ op: oneOf('set'), index: count, part: isPart }));
+export const isOperation = OPERATION;
+function nested(parts, part, index) {
+    return part.parent === null || (part.parent < index && parts[part.parent]?.type === 'subagent');
+}
+const TURN = where(exact({ parts: list(isPart), tokens: nullable(TOKENS), state: isState }), (turn) => turn.parts.every((part, index) => nested(turn.parts, part, index)));
+export const isTurn = TURN;
+function changed(held, operation) {
+    if (operation.op === 'append') {
+        return held.type === 'text' || held.type === 'reasoning'
+            ? { ...held, text: held.text + operation.text }
+            : null;
+    }
+    return operation.part.type === held.type && operation.part.parent === held.parent
+        ? operation.part
+        : null;
+}
+export function applied(parts, operation) {
+    if (operation.op === 'start') {
+        if (operation.index !== 0 && operation.index !== parts.length)
+            return null;
+        const kept = parts.slice(0, operation.index);
+        return nested(kept, operation.part, operation.index) ? [...kept, operation.part] : null;
+    }
+    const held = parts[operation.index];
+    const part = held === undefined ? null : changed(held, operation);
+    if (part === null)
+        return null;
+    return parts.map((one, index) => (index === operation.index ? part : one));
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@agentshouse/session-content",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-c27fa9c4d6971",
+  "description": "Session content: one model of what an agent CLI's session reports, the same for every CLI, with its parser, its fold of a running turn and its bounds on bulk",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.22.1"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentshouse/core.git",
+    "directory": "session-content"
+  }
+}