@dosu/seshi-model 0.0.0-stage → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@dosu/seshi-model",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.10.0",
4
+ "license": "MIT",
5
+ "homepage": "https://github.com/dosu-ai/sessiondb#readme",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/dosu-ai/sessiondb.git"
9
+ },
10
+ "bugs": {
11
+ "url": "https://github.com/dosu-ai/sessiondb/issues"
12
+ },
13
+ "description": "seshi's shared types: the canonical trace, stored objects and the session API; canonical text and hashing.",
14
+ "type": "module",
15
+ "main": "./dist/index.js",
16
+ "types": "./types/index.d.ts",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./types/index.d.ts",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "files": [
25
+ "dist/",
26
+ "types/"
27
+ ],
28
+ "sideEffects": false,
29
+ "engines": {
30
+ "node": ">=20"
31
+ },
32
+ "dependencies": {
33
+ "@letta-ai/trajectory": "^0.3.0"
34
+ }
35
+ }
package/types/api.d.ts ADDED
@@ -0,0 +1,219 @@
1
+ import type { ShippedPrefix } from "./generated/envelope.js";
2
+ import type { RenderedTrace, RenderFormat } from "./schemas/renders.js";
3
+ import type { CallerKind, ChangeEntry, Claims, OwnerBasis, RawFormat, SessionMetadata, Visibility } from "./schemas/store.js";
4
+ export type { ShippedPrefix };
5
+ /** The shape of `fetch` the HTTP client and the S3 driver need: a URL string and an init to a
6
+ * `Response`. */
7
+ export type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
8
+ /** Where a store is, as a reader would need to know it: never a secret. */
9
+ export interface StorageView {
10
+ url: string;
11
+ region?: string;
12
+ account_id?: string;
13
+ endpoint?: string;
14
+ }
15
+ /** A session to store, as the pipeline takes it. */
16
+ export interface SessionUpload {
17
+ owner: string;
18
+ /** The transcript's format name (`claude-code`, `codex`, …): one the deployment's format
19
+ * registry knows. */
20
+ agent: string;
21
+ session_id: string;
22
+ transcript: string;
23
+ format: RawFormat;
24
+ /** The byte offset of `transcript` in the session's log: 0 (the default) when it is the whole
25
+ * log, else where the last upload ended, the `bytes_total` it answered. */
26
+ offset?: number;
27
+ project?: string;
28
+ branch?: string;
29
+ parent_session_id?: string;
30
+ fork_of?: string;
31
+ /** What the client stored from the last answer for this session, if it was stored before.
32
+ * The server's own state decides whether a whole upload extends the session; this is read
33
+ * only for a session that has none. */
34
+ shipped?: ShippedPrefix;
35
+ /** A whole upload that does not extend the session rewrites it instead of being refused
36
+ * (`SessionConflict`, X4.6). Only the session's original writer or an admin may. */
37
+ replace?: boolean;
38
+ /** Rebuild the session from this whole log and review it again, even when the log only
39
+ * extends what is stored (X4.9): a replace, which needs the same permission. Never a chunk.
40
+ * Without an `idempotency_key` each rebuild gets a fresh one. */
41
+ rebuild?: boolean;
42
+ /** Identifies this upload across resends (X4.7); derived from the session, the offset and
43
+ * the text when omitted. A resend with the same key gets the same answer. */
44
+ idempotency_key?: string;
45
+ /** Who may read a new session (X5.10); the deployment's default when omitted. */
46
+ visibility?: Visibility;
47
+ /** Identity the data asserts (X5.5): git email and name, account ids. Kept from a fixed
48
+ * allowlist; never decides ownership (X5.4). */
49
+ claims?: Claims;
50
+ /** The sha256 (hex) of the uploading machine's retraction secret for this session (F9.7).
51
+ * Kept on the session the first time one is sent; the machine that holds the secret can
52
+ * then retract the session with its normal upload credential. */
53
+ retract_hash?: string;
54
+ }
55
+ /** A session to store: `SessionUpload` without the owner, which the backend knows. `format`
56
+ * defaults to `jsonl`. */
57
+ export type Upload = Omit<SessionUpload, "owner" | "format"> & {
58
+ format?: SessionUpload["format"];
59
+ };
60
+ /** How an upload is sent, beside what it stores. */
61
+ export interface IngestOptions {
62
+ /** The session's retraction secret (F9.7), sent with a `replace`: an org-key caller (X5.12)
63
+ * replaces a session only with the secret whose hash it was first uploaded with, since anyone
64
+ * holding the key can state the username. Over HTTP it goes in `X-Seshi-Retract`, never the
65
+ * body; it is never stored. */
66
+ retractSecret?: string;
67
+ }
68
+ export interface IngestResult {
69
+ status: "stored" | "duplicate";
70
+ archive_id: string;
71
+ content_hash: string;
72
+ session_id: string;
73
+ records: number;
74
+ events: number;
75
+ }
76
+ /** What the client keeps after the call, whatever was written: its shipped prefix, and where
77
+ * the next chunk starts. A session the server holds nothing of (`filtered`, or `dropped` before
78
+ * it had a trace) answers zeros: the next upload is the whole log again (X6.3). */
79
+ export interface ShippedState {
80
+ records_total: number;
81
+ prefix_sha256: string;
82
+ /** Bytes of the log normalized so far: where the next chunk starts. */
83
+ bytes_total: number;
84
+ }
85
+ /** The longest idempotency key an envelope may carry (X4.7), in characters. A session keeps its
86
+ * last keys in `metadata.json`, which every write reads, so a key is bounded; an S3 poller's
87
+ * bucket, object key (up to 1024 bytes) and ETag fit. */
88
+ export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 2048;
89
+ /** `prefix_sha256` of no records: what a session the server holds nothing of answers. */
90
+ export declare const EMPTY_PREFIX_SHA256: "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945";
91
+ /** Whether a session's pointer is a stub (F3.4, revised 15 Nov 2026): model review dropped the
92
+ * session's first envelope, so the pointer holds where its log ends and who wrote it, and no
93
+ * trace. A stub has no `head` and is `stored`: readers neither list nor serve it (a tombstoned
94
+ * session has no `head` either, but is `redacted`). */
95
+ export declare function isStub(metadata: Pick<SessionMetadata, "head" | "status">): boolean;
96
+ /** What storing a session answered.
97
+ *
98
+ * - `stored`: a new trace is the session's head. `duplicate`: that trace was already stored.
99
+ * - `unchanged`: the session has a trace (or a stub) and the upload added nothing to it (lines
100
+ * the adapter drops, or a whole log with nothing past what is stored); the log position moved
101
+ * on.
102
+ * - `filtered`: the session filter judged the session's first trace not worth storing (X4.10).
103
+ * Nothing is stored; send the whole log again once it has grown.
104
+ * - `dropped`: model review dropped it (F3). Nothing of it is stored; the log position moves
105
+ * past it. A session with no trace yet keeps only a stub that says where its log ends
106
+ * (`isStub`, F3.4), so the next upload is a chunk from there. */
107
+ export type StoreSessionResult = ({
108
+ status: "unchanged" | "filtered" | "dropped";
109
+ } & ShippedState) | (IngestResult & ShippedState);
110
+ /** A stored trace as it was asked for: the canonical trace, or a rendering of it. */
111
+ export type StoredTrace = RenderedTrace;
112
+ export interface ChangesPage {
113
+ entries: {
114
+ key: string;
115
+ entry: ChangeEntry;
116
+ }[];
117
+ /** Pass as `after` to continue. */
118
+ cursor: string | undefined;
119
+ truncated: boolean;
120
+ }
121
+ /** A page of the cross-owner change feed (`GET /v1/changes/all`): every owner's entries, by
122
+ * stamp, then owner, then key. */
123
+ export interface AllChangesPage {
124
+ entries: {
125
+ owner: string;
126
+ key: string;
127
+ entry: ChangeEntry;
128
+ }[];
129
+ /** Opaque. Pass as `after` to continue; absent when the page is empty. */
130
+ cursor?: string;
131
+ truncated: boolean;
132
+ /** Every owner's feed had been read up to this time when the page was served: entries
133
+ * stamped later wait until it moves past them. */
134
+ through: string;
135
+ }
136
+ export interface ReadChangesOptions {
137
+ /** The last key already processed (the cross-owner feed: the last page's `cursor`); omit
138
+ * to start from the beginning. */
139
+ after?: string;
140
+ /** Alternative to `after`: start from this time (ISO 8601). Ignored when `after` is given. */
141
+ since?: string;
142
+ limit?: number;
143
+ }
144
+ export interface ListSessionsOptions {
145
+ /** The cursor from the last page. */
146
+ after?: string;
147
+ limit?: number;
148
+ /** Whose sessions: the caller's own when omitted. Another owner's sessions are listed as
149
+ * far as visibility allows (X5.10). Only the HTTP backend reads it. */
150
+ owner?: string;
151
+ }
152
+ export interface SessionsPage {
153
+ sessions: SessionMetadata[];
154
+ cursor: string | undefined;
155
+ truncated: boolean;
156
+ }
157
+ /** A session of the caller's that an older normalizer built (X4.9): its format's adapter has
158
+ * changed since, so the session should be sent again whole with `rebuild`. */
159
+ export interface StaleSession {
160
+ /** The format it is filed under. */
161
+ agent: string;
162
+ session_id: string;
163
+ /** The format version that built it (`normalizer.format_version`); absent when not recorded. */
164
+ built_with?: string;
165
+ /** The format's current normalizer version. */
166
+ current: string;
167
+ }
168
+ export interface StaleSessionsPage {
169
+ sessions: StaleSession[];
170
+ /** Pass as `after` to continue. */
171
+ cursor: string | undefined;
172
+ /** More sessions to look through: a page can be empty and still be truncated. */
173
+ truncated: boolean;
174
+ }
175
+ export interface Identity {
176
+ owner: string;
177
+ /** Where the sessions go, as a reader would need to know it. */
178
+ storage: StorageView;
179
+ /** Which kind of credential the caller holds (X5.1); the server says, local mode omits it. */
180
+ kind?: CallerKind;
181
+ /** `member`, `admin` or `service` (X5.3). */
182
+ role?: "member" | "admin" | "service";
183
+ /** What the credential may do (X5.3). */
184
+ scopes?: string[];
185
+ owner_basis?: OwnerBasis;
186
+ /** The id of the token used, when it has one; never the secret. */
187
+ credential_id?: string;
188
+ /** The visibility what the caller writes gets when the request sets none (X5.10). */
189
+ visibility?: Visibility;
190
+ /** When the credential stops working, if it does. */
191
+ expires_at?: string;
192
+ }
193
+ export interface SessionDB {
194
+ /** Store a session, whole or as a chunk from `offset`. Throws `SessionRejected` for a
195
+ * transcript that cannot be stored, `OffsetMismatch` for a chunk that does not start where
196
+ * the log ends, `Forbidden` for a `replace` the caller may not make, `StoreError` when the
197
+ * store fails. */
198
+ ingest(upload: Upload, options?: IngestOptions): Promise<StoreSessionResult>;
199
+ /** The session's pointer, or null for one not stored. */
200
+ getSession(agent: string, sessionId: string): Promise<SessionMetadata | null>;
201
+ /** The head trace, or the one named by `hash`, as the canonical trace (`seshi`, the default)
202
+ * or rendered as `letta`, `otlp` or `atif`; null for a session not stored, stored raw only,
203
+ * or redacted. */
204
+ getTrace(agent: string, sessionId: string, hash?: string, format?: RenderFormat): Promise<StoredTrace | null>;
205
+ listSessions(options?: ListSessionsOptions): Promise<SessionsPage>;
206
+ /** The caller's own sessions an older normalizer built (X4.9), a page at a time. */
207
+ staleSessions(options?: {
208
+ after?: string;
209
+ limit?: number;
210
+ }): Promise<StaleSessionsPage>;
211
+ /** Drop the session's objects and append a tombstone; null for one not stored. */
212
+ tombstone(agent: string, sessionId: string): Promise<{
213
+ removed: number;
214
+ } | null>;
215
+ /** The change feed after a cursor. */
216
+ changes(options?: ReadChangesOptions): Promise<ChangesPage>;
217
+ /** Who this client is and where its sessions go. */
218
+ me(): Promise<Identity>;
219
+ }
@@ -0,0 +1,18 @@
1
+ import type { Envelope } from "./generated/envelope.js";
2
+ import type { OwnerBasis, Writer } from "./schemas/store.js";
3
+ /** Who may write an envelope's session, as the authorizer resolved it. */
4
+ export interface Authorization {
5
+ /** Whose session it is (X5.4, X5.8). */
6
+ owner: string;
7
+ owner_basis: OwnerBasis;
8
+ /** Who writes (X5.5): recorded on the change entry, and as the session's original writer
9
+ * when it is new. */
10
+ writer: Writer;
11
+ /** An admin may replace any session (X4.6, X5.3). */
12
+ admin: boolean;
13
+ }
14
+ export interface Authorizer {
15
+ /** Check that the envelope's caller may write it and resolve whose session it is. Throws
16
+ * `Forbidden` (permanent) when it may not, `StoreError` when it cannot tell (transient). */
17
+ authorize(envelope: Envelope): Authorization | Promise<Authorization>;
18
+ }
@@ -0,0 +1,5 @@
1
+ /** Normalize line endings and trailing whitespace so excerpt matching is stable. */
2
+ export declare function canonicalText(text: string): string;
3
+ /** A copy of `value` with U+0000 removed from every string. Postgres text and jsonb reject NUL,
4
+ * and real transcripts (a Codex rollout, 2026-09) carry it. */
5
+ export declare function stripNul<T>(value: T): T;
@@ -0,0 +1,53 @@
1
+ /** What the write path refuses, as one vocabulary whichever backend raised it: the pipeline
2
+ * over a store throws these directly, and the HTTP backend turns the server's responses back
3
+ * into them, so a caller's `catch` reads the same either way. The server does the reverse:
4
+ * `SessionRejected` is a 422 with its `code`, `OffsetMismatch` a 409 with `expected`,
5
+ * `SessionConflict` a 409 `conflict`, `Forbidden` a 403, `Unauthorized` a 401. */
6
+ /** A transcript the pipeline refuses: nothing in it, not readable by the adapter, a chunk that
7
+ * is not whole lines, over a cap, or a session that was redacted. Final for that upload:
8
+ * resending the same bytes cannot succeed. `code` is what the server reports. */
9
+ export declare class SessionRejected extends Error {
10
+ readonly code: string;
11
+ constructor(code: string, message: string);
12
+ }
13
+ /** The store's own refusals, a subset of `SessionRejected` with a closed set of codes. */
14
+ export declare class IngestRejected extends SessionRejected {
15
+ readonly code: "too_large" | "invalid" | "redacted";
16
+ constructor(code: "too_large" | "invalid" | "redacted", message: string);
17
+ }
18
+ /** A chunk that does not start where the session's log ends: nothing is stored. The client
19
+ * resumes from `expected` (0 when the session has no chunk state: it sends the whole log). */
20
+ export declare class OffsetMismatch extends Error {
21
+ readonly offset: number;
22
+ readonly expected: number;
23
+ readonly code = "offset_mismatch";
24
+ constructor(offset: number, expected: number);
25
+ }
26
+ /** A whole upload that does not extend the stored session (X4.6): its records do not start
27
+ * with what the session already holds. Nothing is stored. The session's original writer, or an
28
+ * admin, can send it again with `replace` to rewrite the session. The server answers 409
29
+ * `conflict`. */
30
+ export declare class SessionConflict extends Error {
31
+ readonly code = "conflict";
32
+ constructor(message: string);
33
+ }
34
+ /** The caller may not do this to the session: replace one another writer wrote (X4.6), or
35
+ * write for an owner its credential does not cover. Nothing is stored. The server answers 403
36
+ * `forbidden`. */
37
+ export declare class Forbidden extends Error {
38
+ readonly code = "forbidden";
39
+ constructor(message: string);
40
+ }
41
+ /** No credential, or one the server does not accept: missing, unknown, expired or revoked, or
42
+ * an org key without the username it needs (X5.12). The server answers 401 `unauthorized`
43
+ * and never says which. */
44
+ export declare class Unauthorized extends Error {
45
+ readonly code = "unauthorized";
46
+ constructor(message?: string);
47
+ }
48
+ /** The store, or the server in front of it, failed or could not be reached: a fault to retry,
49
+ * not a refusal. Raised by every store driver and by the HTTP client. */
50
+ export declare class StoreError extends Error {
51
+ readonly cause?: unknown | undefined;
52
+ constructor(message: string, cause?: unknown | undefined);
53
+ }
@@ -0,0 +1,66 @@
1
+ import type { LlmCall } from "./schemas/trace.js";
2
+ import type { NormalizedRecord } from "./schemas/trajectory.js";
3
+ import type { SpanAdapter } from "./spans.js";
4
+ /** Where a chunk sits in its log. */
5
+ export interface Chunk {
6
+ /** The byte offset of the chunk's first byte in the log. */
7
+ offset: number;
8
+ /** The session the log is of, for an adapter whose chunks do not say (a Codex rollout's
9
+ * `session_meta` is in its first chunk only). */
10
+ session_id: string;
11
+ }
12
+ /** A top-level key's value in a document's head: its kind, and the text of a string. */
13
+ export interface HeadValue {
14
+ kind: "string" | "object" | "array" | "scalar";
15
+ text?: string;
16
+ /** For an array whose first element is an object: that object's own head. */
17
+ first?: DocumentHead;
18
+ }
19
+ /** The top-level keys of a JSON document, read from its start (a truncated sample still has
20
+ * them). A key whose value was cut short has its kind but no text. */
21
+ export type DocumentHead = ReadonlyMap<string, HeadValue>;
22
+ export type JsonObject = Record<string, unknown>;
23
+ /** How detection recognises a format from the start of a file. A sample is a format's when it
24
+ * matches that format's rule and no other's; a guess would file a session under the wrong
25
+ * archive. */
26
+ export interface FormatDetection {
27
+ /** For a format that is one JSON document: whether these top-level keys are this format's. */
28
+ document?: (head: DocumentHead) => boolean;
29
+ /** For a JSONL format: whether this record is one only this format writes. */
30
+ record?: (row: JsonObject) => boolean;
31
+ }
32
+ /** A transcript's records with the LLM calls their `llm_call` fields name. */
33
+ export interface NormalizedTranscript {
34
+ records: NormalizedRecord[];
35
+ llm_calls?: LlmCall[];
36
+ }
37
+ /** One transcript format: native transcript text to trajectory-v1 records, before redaction.
38
+ *
39
+ * `normalize` throws for a transcript it cannot read; an error with a string `code` keeps its
40
+ * code (`missing_user_records` and `missing_assistant_records` mean the log holds no
41
+ * conversation yet, which the registry reports as empty rather than as a failure). With `chunk`,
42
+ * the transcript is the bytes of a log past a point already normalized: the result is that
43
+ * chunk's records without a meta record, and a log cut at line boundaries must normalize, chunk
44
+ * by chunk, to the records the whole log does.
45
+ *
46
+ * An adapter whose transcripts record what each model call cost returns `NormalizedTranscript`:
47
+ * the records, each assistant or reasoning record naming its call in `llm_call`, and the calls
48
+ * (model, token usage, request id). Raw transcripts are not stored (X6.3), so what the adapter
49
+ * leaves out here is gone for good (X6.2). */
50
+ export interface FormatAdapter {
51
+ /** The format's name: the `agent` a client sends and what archive ids derive from. */
52
+ readonly source: string;
53
+ /** Whether a log in this format can arrive in chunks. */
54
+ readonly chunkable: boolean;
55
+ /** The adapter's normalizer version: what the records a transcript normalizes to depend on,
56
+ * as dotted numbers compared one by one (`1+trajectory.0.3.0` is 1, 0, 3, 0). Raise it with
57
+ * any change that alters the records of a transcript already stored: sessions built by an
58
+ * older one are `stale`, and the uploader sends them again to be rebuilt (X4.9). `1` when
59
+ * omitted. */
60
+ readonly version?: string;
61
+ readonly detect?: FormatDetection;
62
+ normalize(transcript: string, chunk?: Chunk): NormalizedRecord[] | NormalizedTranscript;
63
+ /** For a format that also arrives as span sets (OTLP, Datadog): how its spans are grouped,
64
+ * normalized and assembled (X4.2). A format without it takes logs only. */
65
+ readonly spans?: SpanAdapter;
66
+ }
@@ -0,0 +1,81 @@
1
+ /** Generated from spec/schemas/change.schema.json by scripts/model-types.ts (`bun run types`). Do not edit: change the schema and regenerate. */
2
+ import type { Continuation, OwnerBasis, Sha256, Timestamp, Visibility, Writer } from "./common.js";
3
+ /** The `schema` value of every ChangeEntry object. */
4
+ export declare const SCHEMA_ID: "seshi/change/1";
5
+ /** `seshi/change/1`: one entry of an owner's change feed, `owners/<owner>/changes/<stamp>-<archive_id>-<suffix>-<content_hash|tombstone|visibility>.json` (unique: a random suffix). Append-only; written before the session pointer moves, so an entry may name a change that did not happen (readers read the current metadata). Readers tail the feed by key. Every entry records its writer (X5.5). */
6
+ export interface ChangeEntry {
7
+ schema: "seshi/change/1";
8
+ /** `published`: a new trace is the head. `tombstone`: the session's traces were removed (see `reason`). `visibility_changed`: who may read it changed (X5.10). */
9
+ kind: "published" | "tombstone" | "visibility_changed";
10
+ at: Timestamp;
11
+ owner: string;
12
+ archive_id: Sha256;
13
+ session_id: string;
14
+ /** The trace the entry is about; for a tombstone or a visibility change, the head at the time (null when there was none). */
15
+ content_hash: Sha256 | null;
16
+ continuation?: Continuation;
17
+ /** On `published`: the trace replaces the session's earlier traces instead of extending them (X4.6), and they were removed; a reader drops what it held of the session. Absent otherwise. */
18
+ replace?: true;
19
+ writer: Writer;
20
+ /** How the session's owner was established (X5.5), as metadata records it. */
21
+ owner_basis?: OwnerBasis;
22
+ /** Why a session was tombstoned: `deleted` by its owner or an admin, `retracted` by the machine that uploaded it (F9.7), or `redacted` by an operator. On a `published` entry with `replace`, `redacted` says a redaction backfill rewrote the session's traces with new rules (F2.5); absent on other publishes. */
23
+ reason?: "deleted" | "retracted" | "redacted";
24
+ /** On `visibility_changed`: the new visibility. */
25
+ visibility?: Visibility;
26
+ }
27
+ /** change.schema.json as data, without its annotations: what `schemaProblems` checks against. */
28
+ export declare const JSON_SCHEMA: {
29
+ $id: string;
30
+ type: string;
31
+ properties: {
32
+ schema: {
33
+ const: string;
34
+ };
35
+ kind: {
36
+ enum: string[];
37
+ };
38
+ at: {
39
+ $ref: string;
40
+ };
41
+ owner: {
42
+ type: string;
43
+ minLength: number;
44
+ };
45
+ archive_id: {
46
+ $ref: string;
47
+ };
48
+ session_id: {
49
+ type: string;
50
+ };
51
+ content_hash: {
52
+ oneOf: ({
53
+ $ref: string;
54
+ type?: undefined;
55
+ } | {
56
+ type: string;
57
+ $ref?: undefined;
58
+ })[];
59
+ };
60
+ continuation: {
61
+ $ref: string;
62
+ };
63
+ replace: {
64
+ const: boolean;
65
+ };
66
+ writer: {
67
+ $ref: string;
68
+ };
69
+ owner_basis: {
70
+ $ref: string;
71
+ };
72
+ reason: {
73
+ enum: string[];
74
+ };
75
+ visibility: {
76
+ $ref: string;
77
+ };
78
+ };
79
+ required: string[];
80
+ additionalProperties: boolean;
81
+ };