@manyoars/oars 0.1.1 → 0.3.0

package/dist/sessions/pool-wire.d.ts

@@ -0,0 +1,225 @@
+import { VOCAB_VERSION } from './public-vocabulary.js';
+import type { Cell } from './cells.js';
+import type { Motif } from './motif.js';
+import type { Read, ReadAsOf } from './read.js';
+import { type Frame, type FrameStack, type Harness, type LanguageShare, type PromptClass, type PromptObservation, type SessionObservation, type StepObservation, type ToolObservation, type ToolStatus, type Usage } from './schema.js';
+export declare const SKELETON_FORMAT = 2;
+export declare const BUNDLE_FORMAT = 1;
+/** One constant: the pool serves only the vocabulary version the client holds. */
+export { VOCAB_VERSION };
+/**
+ * Section 7's edges. A bucket is the count of edges a value reaches, so bucket 0 is under the first edge and the last is the first edge's doubling past the cap. `tokens`: under 1k, then
+ * doubling to 1.024M and over. `ms`: under 100 ms, then doubling to 6,553.6 s and over. `seconds`: under 1 s, then doubling to 65,536 s and over. `count`: 0, 1, 2, 3-4, 5-8, 9-16, 17-32, over 32.
+ */
+declare const EDGES: {
+    readonly tokens: number[];
+    readonly ms: number[];
+    readonly seconds: number[];
+    readonly count: readonly [1, 2, 3, 5, 9, 17, 33];
+    readonly calls: readonly [1, 2, 3, 5, 9, 17, 33, 65, 129, 257, 513, 1025, 2049, 4097];
+};
+export type BucketKind = keyof typeof EDGES;
+/** The bucket a value falls in. */
+export declare const bucketOf: (kind: BucketKind, value: number) => number;
+/** A stored `explore` count as it pools: its `calls` bucket, or null for a value no count holds (a record captured before the strata has none). The exact count never leaves. */
+export declare const projectExplore: (stored: number | undefined) => number | null;
+/** The lowest value of a bucket, which is what a derivation counts a bucketed value as: it never reads above what the sender held. */
+export declare const floorOf: (kind: BucketKind, bucket: number) => number;
+/**
+ * A step without what a server can compute or no derivation reads: `n` is its call's position, `seg` its place in the call (the array position), `frameId` hashes a frame the skeleton holds, and `edges` are read by no cell. Its cost is
+ * two buckets, never the exact counts. `parent` is the position of the spawning call in the main run's `tools` (Section 1.2's `parent` ordinal).
+ */
+export type SkeletonStep = Omit<StepObservation, 'n' | 'seg' | 'frameId' | 'cost' | 'edges'> & {
+    /** A `tokens` bucket of the step's tokens. */
+    tokens: number | null;
+    /** An `ms` bucket of the step's time. */
+    ms: number | null;
+    /** A `tokens` bucket of the tokens the run spent after this step (spec Section 1.2): the bucket of the exact sum, never a sum of buckets. */
+    remainingTokens: number;
+    /** The projected type of the subagent whose run holds the step, a built-in or `custom`; null on a main-run step. */
+    agentType: string | null;
+};
+/** A call's order is its position in `tools`, and its `prompt` is a position in the same transcript's `prompts`: ordinals inside the batch, never the session's own numbers. */
+export interface SkeletonTool {
+    side: boolean;
+    prompt: number | null;
+    status: ToolStatus;
+    /** Exact, per tool: the one exact time on the wire, which W reads on `ledger` (Section 1.2, `durationMs`). A cell never reads it. */
+    durationMs: number | null;
+    steps: SkeletonStep[];
+}
+/** A prompt's usage as `tokens` buckets: `thinking` is a token count (the thinking tokens of the output), so it takes the same edges as the rest. */
+export type SkeletonUsage = {
+    [field in keyof Usage]: number;
+};
+/** A language of the stack with its share of the touched files (spec Section 7): one of four buckets, never a count. */
+export interface LanguageShareEntry {
+    language: string;
+    languageShare: LanguageShare;
+}
+/** The frame a skeleton holds: the stored frame, with the stack's shares beside its languages. A language whose share is not known is in `languages` and has no entry here. */
+export type SkeletonFrame = Omit<Frame, 'stack'> & {
+    stack: FrameStack & {
+        languageShares: LanguageShareEntry[];
+    };
+};
+export interface SkeletonPrompt {
+    cls: PromptClass;
+    /** A `count` bucket. */
+    errors: number;
+    /** A `seconds` bucket. */
+    wallSec: number | null;
+    usage: SkeletonUsage;
+    /** A `calls` bucket of the prompt's steps that only look (`file.read`, `file.search`, `web.search`, `web.fetch`); null when the record holds no count. */
+    explore: number | null;
+    frame: SkeletonFrame;
+}
+export interface SkeletonTranscript {
+    /** The transcript's Merkle root and the count of its lines it covers (Section 2, "Subagents"): one pair for each transcript, the main's first. */
+    merkleRoot: string;
+    leaves: number;
+    harness: Harness;
+    frame: SkeletonFrame;
+    prompts: SkeletonPrompt[];
+    tools: SkeletonTool[];
+}
+/** What a delta entry may change (spec Section 4, rule 4): `permissionMode` and `effort` by name only, a `plugin` as added or removed, and a `package` as removed. */
+export type DeltaField = 'plugin' | 'package' | 'permissionMode' | 'effort';
+export type DeltaKind = 'added' | 'removed' | 'changed';
+/** The one metric an entry's change is in: `callsPerSession` (tool calls in a session, or calls naming the package) in `count` buckets, `thinking` (thinking tokens in a prompt) in `tokens` buckets. */
+export type DeltaMetric = 'callsPerSession' | 'thinking';
+/**
+ * One change between a client's own before and after windows. It holds no `sid`, root, window date, or exact value: `name` is the public package or the word `private` (a plugin has no pinned registry, so
+ * always `private`), null when the field is named alone; `registry` is the package's registry and is null for a `private` name; `change` is the signed bucket of the metric's move, never the metric.
+ */
+export interface DeltaEntry {
+    deltaKind: DeltaKind;
+    field: DeltaField;
+    name: string | null;
+    registry: string | null;
+    metric: DeltaMetric;
+    change: number;
+}
+export interface SessionSkeleton {
+    format: typeof SKELETON_FORMAT;
+    /** A hash the client computes per account, so a redeposit replaces and two accounts' sessions cannot be joined. Never the session's own id. */
+    id: string;
+    /** The main transcript first, then each subagent's. */
+    transcripts: SkeletonTranscript[];
+    /** One for the batch: a hash of the main transcript's non-null call durations in call order, only with `MIN_TIMED_CALLS` of them; a subagent's calls never join it. */
+    timingPrint: string | null;
+    /** The batch's client-built delta entries (Section 2, "Deltas"): changes between the client's own before and after windows, each carried once, by the batch of the session that filled the after window. */
+    deltas: DeltaEntry[];
+}
+/** One main session and the subagents it spawned, as the local store holds them. */
+export interface SessionRecords {
+    main: SessionObservation;
+    /** The main transcript first, then each subagent's, ordered by session so one store builds one batch. */
+    transcripts: {
+        session: SessionObservation;
+        prompts: PromptObservation[];
+        tools: ToolObservation[];
+        root: TranscriptRoot | null;
+    }[];
+}
+/** What a skeleton file holds of a transcript that may leave the machine: its root and the count of lines under it. */
+export interface TranscriptRoot {
+    merkleRoot: string;
+    leaves: number;
+}
+/** W's minimum for a timing print (deposit-weighting spec, layer 5): fewer timed calls than this say too little to tell sessions apart. */
+export declare const MIN_TIMED_CALLS = 50;
+/** A session has ended once no transcript of it has gained a line for this long (`session_idle_hours`, spec Section 7). */
+export declare const SESSION_IDLE_HOURS = 6;
+/**
+ * Whether a session's batch may be built at `now`: no transcript of it, main or subagent, has gained a line for `SESSION_IDLE_HOURS`. A transcript gains a line when capture sees it change, which
+ * stamps a new `rev` in epoch milliseconds, but a transcript can grow after the last capture, so `written` (the newest write to any raw file of the session, 0 when none is known) counts too: the
+ * session was last active at the later of the two. A subagent that died without an end marker holds its session back at most that long.
+ */
+export declare const hasEnded: (records: SessionRecords, now: number, written: number) => boolean;
+/** Every main session of a store, with its records. */
+export declare const sessionsOf: (store: {
+    sessions: readonly SessionObservation[];
+    subagents: readonly SessionObservation[];
+    prompts: readonly PromptObservation[];
+    tools: readonly ToolObservation[];
+}, roots: ReadonlyMap<string, TranscriptRoot>) => SessionRecords[];
+/** One command of a shell call as the projection reads it (`projectStoredShell`): a program, its subcommand, and its flags, each a list member or `private`. */
+export interface ShellCommand {
+    program: string;
+    subcommand: string | null;
+    flags: readonly string[];
+}
+/** Reads a stored shell call's commands in order. The client passes the projection; this file holds no vocabulary snapshot, so the Worker can bundle it. */
+export type ShellReader = (tool: ToolObservation) => readonly ShellCommand[];
+/**
+ * A stored tool's steps as the wire holds them: each shell step's identity is replaced by the projected command, and every name the server has no row for (a native name, MCP server,
+ * skill, host, or pull name) reads `private`. A `private` program holds no pull, so a stored step whose public program has since left the list carries none. The one place a deposit and a local read take it from.
+ */
+export declare const projectedSteps: (tool: ToolObservation, read: ShellReader, harness: Harness) => StepObservation[];
+/** The hash a batch's timing print is made with, over the durations in call order: the client's `contentHash` (D1's `hP`). */
+export type Print = (durations: readonly number[]) => string;
+/**
+ * The skeleton of a session; null when any record of it was captured before steps and frames, or a transcript of it has no root, which holds no closed reading to send. The batch holds the main
+ * transcript's run first, then each subagent's as its own run; its `id` is the main session's, and its one `timingPrint` is over the main transcript's calls alone.
+ */
+export declare const skeletonOf: (records: SessionRecords, id: string, read: ShellReader, print: Print, deltas?: readonly DeltaEntry[]) => SessionSkeleton | null;
+/** A harness version a bundle can be asked for: public, so the request carries nothing private. The admitted list replaces this shape rule when it ships. */
+export declare const isBundleVersion: (version: string) => boolean;
+/** Whether `name` is a harness the schema names. */
+export declare const isHarness: (name: string) => name is Harness;
+export interface Refusal {
+    ok: false;
+    field: string;
+    reason: string;
+}
+export declare const HARNESSES: readonly ["claude-code", "cursor", "codex", "copilot", "gemini", "grok", "vscode-copilot"];
+/** The registries a package comes from; a pull may also come from a skill, plugin, or MCP registry. */
+export declare const PACKAGE_REGISTRIES: readonly ["npm", "pypi", "crates", "go", "rubygems", "homebrew"];
+/** The skeleton in `value`, rebuilt from the fields read; else the first field that is not closed vocabulary, and why. */
+export declare const parseSkeleton: (value: unknown) => {
+    ok: true;
+    skeleton: SessionSkeleton;
+} | Refusal;
+/**
+ * One count of a stack stratum (spec Section 4, rule 3), across every harness version, so it is never joined to one. The two pairs hold two values each, joined by a slash:
+ * `languageShare` is `<language>/<share bucket>` and `repoFilesExplore` is `<stack size, xs to xl>/<explore calls bucket>`.
+ */
+export interface StrataCell {
+    dimension: 'language' | 'framework' | 'repoFiles' | 'languageShare' | 'repoFilesExplore';
+    value: string;
+    sessions: number;
+    clusters: number;
+}
+/** One harness version's replica, as the server signs it. It names its harness, which the signature covers, so a bundle for one harness cannot stand in for another's. Nothing in it is keyed by stack. */
+export interface Bundle {
+    format: typeof BUNDLE_FORMAT;
+    harness: Harness;
+    harnessVersion: string;
+    vocabVersion: string;
+    asOf: ReadAsOf;
+    cells: Cell[];
+    motifs: Motif[];
+    reads: Read[];
+    strata: StrataCell[];
+}
+/** The signature covers these exact bytes, so nothing has to be canonicalized on either side. */
+export interface SignedBundle {
+    payload: string;
+    /** Ed25519 over the payload's UTF-8 bytes, in base64. */
+    signature: string;
+}
+/** The public half of the pool's key, as a client pins it at login. */
+export interface PinnedKey {
+    kty: string;
+    crv: string;
+    x: string;
+}
+/** The bundle, only when the pinned key signed these bytes for the harness and version that were asked for: another harness's or version's bundle, under a good signature, is still the wrong answer. */
+export declare const verifyBundle: (signed: unknown, key: PinnedKey, harness: Harness, harnessVersion: string) => Promise<{
+    ok: true;
+    bundle: Bundle;
+} | {
+    ok: false;
+    reason: string;
+}>;