@dosu/seshi-model 0.0.0-stage → 0.11.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.
@@ -0,0 +1,95 @@
1
+ import type { OtlpTrace } from "./otlp.js";
2
+ import type { Continuation, Trace, TraceEvent } from "./trace.js";
3
+ import type { NormalizedRecord } from "./trajectory.js";
4
+ /** `seshi` (the stored canonical trace, the default), `letta` (Letta trajectory-v1, the
5
+ * `sessionstorage/trace/1` object sessiondb stored), `otlp` (OTLP/HTTP JSON GenAI spans) or
6
+ * `atif` (an ATIF-v1.7 document). */
7
+ export type RenderFormat = "seshi" | "letta" | "otlp" | "atif";
8
+ export declare const RENDER_FORMATS: readonly RenderFormat[];
9
+ export declare function isRenderFormat(value: unknown): value is RenderFormat;
10
+ /** The schema id of the Letta rendering: what sessiondb stored before seshi, so a reader of
11
+ * those objects reads this one unchanged. */
12
+ export declare const LETTA_TRACE_SCHEMA: "sessionstorage/trace/1";
13
+ /** A trace rendered as Letta trajectory-v1: the canonical trace with plain trajectory-v1
14
+ * records (no seshi fields), without `llm_calls` and `provenance`, and the same events and
15
+ * `content_hash`. */
16
+ export interface LettaTrace {
17
+ schema: typeof LETTA_TRACE_SCHEMA;
18
+ content_hash: string;
19
+ source: string;
20
+ agent: string;
21
+ project?: string;
22
+ branch?: string;
23
+ session_id: string | null;
24
+ started_at: string | null;
25
+ ended_at: string | null;
26
+ records: NormalizedRecord[];
27
+ events: TraceEvent[];
28
+ metadata: {
29
+ cwd?: string;
30
+ git_branch?: string;
31
+ model?: string;
32
+ parent_session_id?: string;
33
+ continuation?: Continuation;
34
+ normalizer?: {
35
+ name: string;
36
+ version: string;
37
+ };
38
+ [key: string]: unknown;
39
+ };
40
+ }
41
+ /** One ATIF step (Harbor's Agent Trajectory Interchange Format). */
42
+ export interface AtifStep {
43
+ step_id: number;
44
+ timestamp?: string;
45
+ source: "system" | "user" | "agent";
46
+ message: string;
47
+ model_name?: string;
48
+ reasoning_content?: string;
49
+ tool_calls?: {
50
+ tool_call_id: string;
51
+ function_name: string;
52
+ arguments: unknown;
53
+ }[];
54
+ observation?: {
55
+ results: {
56
+ source_call_id?: string;
57
+ content: string;
58
+ extra?: Record<string, unknown>;
59
+ }[];
60
+ };
61
+ metrics?: {
62
+ prompt_tokens?: number;
63
+ completion_tokens?: number;
64
+ cached_tokens?: number;
65
+ };
66
+ extra?: Record<string, unknown>;
67
+ }
68
+ /** A trace rendered as an ATIF-v1.7 document. */
69
+ export interface AtifDocument {
70
+ schema_version: "ATIF-v1.7";
71
+ session_id?: string;
72
+ agent: {
73
+ name: string;
74
+ version: string;
75
+ model_name?: string;
76
+ extra?: Record<string, unknown>;
77
+ };
78
+ steps: AtifStep[];
79
+ final_metrics?: {
80
+ total_prompt_tokens?: number;
81
+ total_completion_tokens?: number;
82
+ total_cached_tokens?: number;
83
+ total_steps: number;
84
+ };
85
+ extra?: Record<string, unknown>;
86
+ }
87
+ /** A trace as some format renders it. */
88
+ export type RenderedTrace = Trace | LettaTrace | OtlpTrace | AtifDocument;
89
+ /** Which rendering each format gives. */
90
+ export interface RenderedTraces {
91
+ seshi: Trace;
92
+ letta: LettaTrace;
93
+ otlp: OtlpTrace;
94
+ atif: AtifDocument;
95
+ }
@@ -0,0 +1,32 @@
1
+ import type { CallerKind, LogEncoding, Writer } from "../generated/common.js";
2
+ export type { ChangeEntry } from "../generated/change.js";
3
+ export type { CallerKind, Claims, Continuation, LogEncoding, Normalizer, OwnerBasis, Provenance, RedactionSummary, Sha256, SourceId, SourceKind, SourceLocation, Timestamp, Visibility, Writer, } from "../generated/common.js";
4
+ export type { LayoutMarker } from "../generated/layout.js";
5
+ export type { AppliedEnvelope, DroppedPrefix, NormalizedState, SessionMetadata, SessionTraceRef, } from "../generated/metadata.js";
6
+ /** How a transcript is encoded (`jsonl` or `json`): the envelope's `LogEncoding`, by the name
7
+ * the raw-transcript redaction passes and the session API have always used. */
8
+ export type RawFormat = LogEncoding;
9
+ export declare const METADATA_SCHEMA: "seshi/metadata/1";
10
+ export declare const CHANGE_SCHEMA: "seshi/change/1";
11
+ /** The layout marker this seshi writes when a command sets the mode or a minimum version
12
+ * (F11.7). */
13
+ export declare const LAYOUT_SCHEMA: "seshi/layout/2";
14
+ /** The first layout marker schema: no mode, no minimum version. Still read, and still what a
15
+ * new prefix gets unless a command sets one of schema 2's fields, so older seshi keep working. */
16
+ export declare const LAYOUT_SCHEMA_V1: "seshi/layout/1";
17
+ /** Every layout marker schema this seshi reads. */
18
+ export declare const LAYOUT_SCHEMAS: readonly string[];
19
+ /** Which mode a bucket is used in (F11.8). */
20
+ export type BucketMode = "server" | "serverless";
21
+ /** The marker a sessiondb (pre-seshi) prefix holds, `sessionstorage.json`. Seshi does not read
22
+ * such a prefix: no migration is planned (X1.5). */
23
+ export declare const LEGACY_LAYOUT_SCHEMA: "sessionstorage/layout/1";
24
+ export type SessionStatus = "stored" | "redacted";
25
+ export type ChangeKind = "published" | "tombstone" | "visibility_changed";
26
+ /** Why a session was tombstoned. */
27
+ export type TombstoneReason = "deleted" | "retracted" | "redacted";
28
+ /** The source id hooks and the CLI upload under (X6.4). */
29
+ export declare const UPLOAD_SOURCE: "upload";
30
+ /** The writer of a session written in local mode, or by code that names no caller: the owner
31
+ * itself, through the upload route. */
32
+ export declare function localWriter(owner: string, kind?: CallerKind): Writer;
@@ -0,0 +1,3 @@
1
+ export type { Continuation } from "../generated/common.js";
2
+ export type { EventRole, LlmCall, TokenUsage, Trace, TraceAssistantRecord, TraceEvent, TraceMetadata, TraceMetaRecord, TraceRecord, TraceTextRecord, TraceToolCall, TraceToolResultRecord, } from "../generated/trace.js";
3
+ export declare const TRACE_SCHEMA: "seshi/trace/1";
@@ -0,0 +1,15 @@
1
+ import type { AssistantMessageRecord, AssistantToolCallRecord, MetaRecord, NormalizedRecord, ObservationRecord, ReasoningRecord, SystemRecord, ToolCall, ToolResultRecord, UserRecord } from "@letta-ai/trajectory";
2
+ import type { TraceRecord } from "../generated/trace.js";
3
+ export type { AssistantMessageRecord, AssistantToolCallRecord, MetaRecord, NormalizedRecord, ObservationRecord, ReasoningRecord, SystemRecord, ToolCall, ToolResultRecord, UserRecord, };
4
+ /** Thrown when a value is not a trajectory-v1 record set the store accepts. */
5
+ export declare class TrajectoryError extends Error {
6
+ constructor(message: string);
7
+ }
8
+ export declare function isScopeCoordinate(value: unknown): value is string;
9
+ /** The records as trajectory-v1, or a `TrajectoryError` naming the first bad one. Does not check
10
+ * the conversation-level rules (meta first, has a user record, …): `parseTrajectory` does. */
11
+ export declare function validateRecords(records: unknown): NormalizedRecord[];
12
+ /** The records as the canonical trace's records: trajectory-v1, plus the optional fields
13
+ * `seshi/trace/1` adds, kept and checked. Unknown fields are dropped, as `validateRecords`
14
+ * drops them. */
15
+ export declare function validateTraceRecords(records: unknown): TraceRecord[];
@@ -0,0 +1,5 @@
1
+ /** The schema files a stored object can be checked against. */
2
+ export type SchemaFile = "change.schema.json" | "envelope.schema.json" | "layout.schema.json" | "metadata.schema.json" | "trace.schema.json";
3
+ /** What is wrong with `value` as an object of `file` (`metadata.schema.json`): each problem as
4
+ * a JSON pointer and what it must be, at most 20; none when it is valid. */
5
+ export declare function schemaProblems(file: SchemaFile, value: unknown): string[];
@@ -0,0 +1,91 @@
1
+ import type { EventRole } from "./schemas/trace.js";
2
+ /** How results are ordered: best match first (bm25 over the matching records, the default),
3
+ * or the sessions most recently updated first. */
4
+ export type SearchSort = "relevance" | "recent";
5
+ export declare const SEARCH_SORTS: readonly SearchSort[];
6
+ /** A search (F10.1): keywords plus filters. Every filter narrows; none widens what the caller
7
+ * may read, which the server decides (F10.4). */
8
+ export interface SearchRequest {
9
+ /** The keywords, matched per record (a prompt, an answer, one tool call). Words must all
10
+ * appear in one record (in any order); `"a phrase"` must appear as written;
11
+ * `word*` matches words that start with it; `a OR b` matches either; `-word` excludes
12
+ * records with it. Case and accents are ignored. */
13
+ q: string;
14
+ /** Only this owner's sessions (`[auth.owner_aliases]` folded in). */
15
+ owner?: string;
16
+ /** Only sessions filed under this format or run by this agent (`origin_agent`). */
17
+ agent?: string;
18
+ /** Only sessions of this repository: the session's `project`, exactly or as its last path
19
+ * segments (`widget` matches `github.com/acme/widget`). */
20
+ repo?: string;
21
+ branch?: string;
22
+ /** Only sessions written through this source (`upload`, or a configured source id). */
23
+ source?: string;
24
+ /** Only records at or after this time (RFC 3339). Records without a timestamp use their
25
+ * session's last update. */
26
+ since?: string;
27
+ /** Only records at or before this time (RFC 3339). */
28
+ until?: string;
29
+ sort?: SearchSort;
30
+ /** Sessions per page: 1 to 100, 20 by default. */
31
+ limit?: number;
32
+ /** Matching records shown per session: 0 to 20, 3 by default. */
33
+ matches?: number;
34
+ /** The `cursor` of the previous page. */
35
+ cursor?: string;
36
+ }
37
+ /** One matching record of a session: which trace and which of its events (`GET
38
+ * /v1/sessions/{agent}/{session_id}/trace?hash=` holds it at `events[event_index]`), and a short
39
+ * excerpt around what matched. */
40
+ export interface SearchMatch {
41
+ content_hash: string;
42
+ event_index: number;
43
+ role: EventRole;
44
+ tool_name?: string;
45
+ timestamp?: string;
46
+ /** Up to a few dozen words of the record around the match; `…` marks text left out. */
47
+ snippet: string;
48
+ /** Where the matched words are in `snippet`: `[start, end)` offsets in UTF-16 code units, as
49
+ * JavaScript strings count them. */
50
+ highlights: [number, number][];
51
+ }
52
+ /** A session with records that match. */
53
+ export interface SearchResult {
54
+ owner: string;
55
+ agent: string;
56
+ session_id: string;
57
+ archive_id: string;
58
+ origin_agent?: string;
59
+ native_session_id?: string;
60
+ project?: string;
61
+ branch?: string;
62
+ source_id?: string;
63
+ visibility: "org" | "owner";
64
+ started_at?: string;
65
+ ended_at?: string;
66
+ updated_at: string;
67
+ /** How well the session matched: higher is better, comparable within one answer only. */
68
+ score: number;
69
+ /** How many of its records matched. */
70
+ hits: number;
71
+ matches: SearchMatch[];
72
+ }
73
+ /** The index a search was answered from. */
74
+ export interface SearchIndexState {
75
+ /** When the index first caught up with the change feed. */
76
+ ready_at: string;
77
+ /** When it last finished reading the change feed. */
78
+ caught_up_at?: string;
79
+ /** Sessions it holds. */
80
+ sessions: number;
81
+ }
82
+ export interface SearchResults {
83
+ query: string;
84
+ /** Sessions that match, as the index holds them (the page may hold fewer: a session whose
85
+ * owner or visibility changed since it was indexed is left out). */
86
+ total: number;
87
+ results: SearchResult[];
88
+ /** Pass as `cursor` for the next page; absent on the last. */
89
+ cursor?: string;
90
+ index: SearchIndexState;
91
+ }
@@ -0,0 +1,156 @@
1
+ import type { Claims } from "./generated/common.js";
2
+ import type { LlmCall } from "./schemas/trace.js";
3
+ import type { NormalizedRecord } from "./schemas/trajectory.js";
4
+ /** An OTLP `AnyValue` in its JSON mapping. `intValue` is a string when it does not fit a
5
+ * double exactly (int64); `bytesValue` is base64. */
6
+ export type SpanValue = {
7
+ stringValue: string;
8
+ } | {
9
+ boolValue: boolean;
10
+ } | {
11
+ intValue: string | number;
12
+ } | {
13
+ doubleValue: number;
14
+ } | {
15
+ bytesValue: string;
16
+ } | {
17
+ arrayValue: {
18
+ values: SpanValue[];
19
+ };
20
+ } | {
21
+ kvlistValue: {
22
+ values: SpanAttribute[];
23
+ };
24
+ };
25
+ /** An OTLP `KeyValue`. A value the sender left empty has no `value`. */
26
+ export interface SpanAttribute {
27
+ key: string;
28
+ value?: SpanValue;
29
+ }
30
+ export interface SpanEvent {
31
+ timeUnixNano?: string;
32
+ name: string;
33
+ attributes?: SpanAttribute[];
34
+ }
35
+ export interface SpanLink {
36
+ traceId: string;
37
+ spanId: string;
38
+ attributes?: SpanAttribute[];
39
+ }
40
+ /** `STATUS_CODE_UNSET` = 0, `STATUS_CODE_OK` = 1, `STATUS_CODE_ERROR` = 2. */
41
+ export interface SpanStatus {
42
+ code?: number;
43
+ message?: string;
44
+ }
45
+ /** One span as received (OTLP's JSON mapping). `kind`: 0 unspecified, 1 internal, 2 server,
46
+ * 3 client, 4 producer, 5 consumer. */
47
+ export interface ReceivedSpan {
48
+ traceId: string;
49
+ spanId: string;
50
+ parentSpanId?: string;
51
+ name: string;
52
+ kind?: number;
53
+ startTimeUnixNano: string;
54
+ endTimeUnixNano?: string;
55
+ attributes?: SpanAttribute[];
56
+ events?: SpanEvent[];
57
+ links?: SpanLink[];
58
+ status?: SpanStatus;
59
+ /** The instrumentation scope that emitted it (`com.anthropic.claude-platform`), carried from
60
+ * its `ScopeSpans` so a format can tell an SDK span from an API span. */
61
+ scope?: {
62
+ name?: string;
63
+ version?: string;
64
+ };
65
+ }
66
+ /** A tool call a span ran (an `execute_tool` span). */
67
+ export interface SpanTool {
68
+ /** The tool call id the model assigned (`gen_ai.tool.call.id`), when the span names it. */
69
+ call_id?: string;
70
+ name: string;
71
+ /** The arguments as sent (usually JSON). */
72
+ args?: string;
73
+ /** What went back to the model. */
74
+ result?: string;
75
+ /** False when the tool failed. */
76
+ ok?: boolean;
77
+ }
78
+ /** One span, normalized: its part of the session, in trajectory-v1 records and an LLM call,
79
+ * plus what the assembler orders and joins it by. This is what the span store keeps (regex
80
+ * redaction has run on every text field), never the span as received. */
81
+ export interface SpanPart {
82
+ trace_id: string;
83
+ span_id: string;
84
+ parent_span_id?: string;
85
+ name: string;
86
+ /** The OTLP span kind (2 server, 3 client, …). */
87
+ kind?: number;
88
+ /** ISO 8601. */
89
+ started_at: string;
90
+ ended_at?: string;
91
+ /** The exact times, in Unix nanoseconds, so parts that start in one millisecond still
92
+ * order. */
93
+ start_unix_nano?: string;
94
+ end_unix_nano?: string;
95
+ status?: "ok" | "error" | "unset";
96
+ /** `gen_ai.operation.name` (`chat`, `invoke_agent`, `execute_tool`, …). */
97
+ operation?: string;
98
+ /** The conversation thread it belongs to (`gen_ai.conversation.id`): inputs repeat history
99
+ * per thread, so history is matched within one. */
100
+ thread?: string;
101
+ /** What the span says went in: system instructions and input messages, as records. A chat
102
+ * request repeats the conversation so far; the assembler keeps only what is new. */
103
+ input?: NormalizedRecord[];
104
+ /** What came out: the response's messages, as records. */
105
+ output?: NormalizedRecord[];
106
+ /** The tool call an `execute_tool` span ran; written out only when no message already
107
+ * holds that call. */
108
+ tool?: SpanTool;
109
+ /** The model request the span stands for, when it reports one (model, usage, stop reason,
110
+ * error). Its id is unique within the session. */
111
+ llm_call?: LlmCall;
112
+ /** The response id (`gen_ai.response.id`): the same response reported by two spans (an
113
+ * SDK's client span and the API's server span) is kept once. */
114
+ response_id?: string;
115
+ /** Whether the span carried prompt or response content (F4.5). */
116
+ content: boolean;
117
+ /** The span ends the session (a final span, F4.4): the assembler need not wait the whole
118
+ * quiet period. */
119
+ final?: boolean;
120
+ /** What the session is, when the span says: the model, the agent's version, the working
121
+ * folder. The first part that names one wins. */
122
+ meta?: {
123
+ model?: string;
124
+ agent_version?: string;
125
+ cwd?: string;
126
+ };
127
+ }
128
+ /** What the assembler makes of a session's parts: its records (meta first) and the LLM calls
129
+ * they name. */
130
+ export interface AssembledSpans {
131
+ records: NormalizedRecord[];
132
+ llm_calls: LlmCall[];
133
+ }
134
+ /** The resource a batch of spans came with (`service.name`, …), as attributes. */
135
+ export type SpanResource = readonly SpanAttribute[];
136
+ /** How one span format reads spans (X4.2): a format adapter that takes span sets has one
137
+ * (`FormatAdapter.spans`). The OTLP receiver and pollers group spans into sessions with
138
+ * `sessionKey`, the pipeline normalizes each with `normalize` on arrival, and the assembler
139
+ * joins a session's parts with `assemble`. All three are pure. */
140
+ export interface SpanAdapter {
141
+ /** The session a span belongs to (F4.3), in the source's own naming: for OTLP
142
+ * `anthropic.session.id`, else `gen_ai.conversation.id`, else the trace id. */
143
+ sessionKey(span: ReceivedSpan, resource: SpanResource): string;
144
+ /** Whether the span carries prompt or response content: a batch where none does is from a
145
+ * metadata-only destination (F4.5). */
146
+ hasContent(span: ReceivedSpan, resource: SpanResource): boolean;
147
+ /** Identity the span asserts (X5.5): account ids, a user id. Recorded, never trusted. */
148
+ claims?(span: ReceivedSpan, resource: SpanResource): Claims | undefined;
149
+ /** One span → its part of the session, before redaction. Throws for a span it cannot
150
+ * read. */
151
+ normalize(span: ReceivedSpan, resource: SpanResource): SpanPart;
152
+ /** A session's parts, in any order and possibly repeated → its records and calls. */
153
+ assemble(parts: readonly SpanPart[], session: {
154
+ source: string;
155
+ }): AssembledSpans;
156
+ }
@@ -0,0 +1 @@
1
+ export declare const VERSION: string;