@shipfox/api-logs-dto 2.0.0

package/src/schemas/record.test.ts

@@ -0,0 +1,275 @@
+import {Buffer} from 'node:buffer';
+import {
+  type LogRecord,
+  logRecordSchema,
+  MAX_RECORD_DATA_BYTES,
+  MAX_RECORD_GROUP_ID_BYTES,
+  MAX_RECORD_NAME_BYTES,
+  parseLogRecordLine,
+  parseRawLogRecordLine,
+  type RawLogRecord,
+  rawLogRecordSchema,
+} from './record.js';
+
+const ts = 1765531200123;
+const sessionRow = {
+  kind: 'message',
+  timestamp: ts,
+  role: 'assistant',
+  label: 'assistant',
+  meta: [],
+  text: 'hello',
+  terminalFailure: false,
+} as const;
+
+/** Every record `type` and whether it is valid on the raw write path. */
+const recordsByType: Array<{record: LogRecord; raw: boolean}> = [
+  {record: {v: 1, ts, type: 'output', stream: 'stdout', data: 'hello\n'}, raw: true},
+  {
+    record: {v: 1, ts, type: 'group_start', group_id: 'g1', parent_group_id: null, name: 'Install'},
+    raw: true,
+  },
+  {record: {v: 1, ts, type: 'group_end', group_id: 'g1'}, raw: true},
+  {record: {v: 1, ts, type: 'end', total_bytes: 1048576}, raw: true},
+  {record: {v: 1, ts, type: 'gap', dropped_bytes: 4096}, raw: true},
+  {
+    record: {
+      v: 1,
+      ts,
+      type: 'agent_session',
+      row: sessionRow,
+    },
+    raw: false,
+  },
+  {record: {v: 1, ts, type: 'capped'}, raw: false},
+  {record: {v: 1, ts, type: 'runner_lost'}, raw: false},
+];
+
+describe('logRecordSchema (read union)', () => {
+  it.each(recordsByType)('parses the $record.type record', ({record}) => {
+    const parsed = logRecordSchema.parse(record);
+
+    expect(parsed).toEqual(record);
+  });
+
+  it('parses an output record carrying stderr', () => {
+    const parsed = logRecordSchema.parse({v: 1, ts, type: 'output', stream: 'stderr', data: 'x'});
+
+    expect(parsed).toEqual({v: 1, ts, type: 'output', stream: 'stderr', data: 'x'});
+  });
+
+  it('rejects an unknown record type', () => {
+    expect(() => logRecordSchema.parse({v: 1, ts, type: 'exploded'})).toThrow();
+  });
+
+  it('rejects an unsupported version', () => {
+    expect(() =>
+      logRecordSchema.parse({v: 2, ts, type: 'output', stream: 'stdout', data: 'x'}),
+    ).toThrow();
+  });
+
+  it('rejects an output record without a stream pipe', () => {
+    expect(() => logRecordSchema.parse({v: 1, ts, type: 'output', data: 'x'})).toThrow();
+  });
+
+  it('rejects an output record whose data exceeds the per-record byte cap', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'output',
+        stream: 'stdout',
+        data: 'x'.repeat(MAX_RECORD_DATA_BYTES + 1),
+      }),
+    ).toThrow();
+  });
+
+  it('accepts data exactly at the per-record byte cap', () => {
+    const data = 'x'.repeat(MAX_RECORD_DATA_BYTES);
+
+    const parsed = logRecordSchema.parse({v: 1, ts, type: 'output', stream: 'stdout', data});
+
+    expect(Buffer.byteLength((parsed as {data: string}).data, 'utf8')).toBe(MAX_RECORD_DATA_BYTES);
+  });
+
+  it('rejects an empty output record so it cannot store bytes without payload', () => {
+    expect(() =>
+      logRecordSchema.parse({v: 1, ts, type: 'output', stream: 'stdout', data: ''}),
+    ).toThrow();
+  });
+
+  it('parses a normalized agent_session record', () => {
+    const parsed = logRecordSchema.parse({v: 1, ts, type: 'agent_session', row: sessionRow});
+
+    expect(parsed).toEqual({v: 1, ts, type: 'agent_session', row: sessionRow});
+  });
+
+  it('rejects a raw agent_session record on the read path', () => {
+    expect(() => logRecordSchema.parse({v: 1, ts, type: 'agent_session', data: '{}'})).toThrow();
+  });
+
+  it('accepts a null parent_group_id at the top level', () => {
+    const parsed = logRecordSchema.parse({
+      v: 1,
+      ts,
+      type: 'group_start',
+      group_id: 'g1',
+      parent_group_id: null,
+      name: 'root',
+    });
+
+    expect(parsed).toMatchObject({type: 'group_start', parent_group_id: null});
+  });
+
+  it('rejects a group_start whose name exceeds the per-record byte cap', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'group_start',
+        group_id: 'g1',
+        parent_group_id: null,
+        name: 'x'.repeat(MAX_RECORD_NAME_BYTES + 1),
+      }),
+    ).toThrow();
+  });
+
+  it('rejects a group_start whose group_id exceeds the byte cap', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'group_start',
+        group_id: 'g'.repeat(MAX_RECORD_GROUP_ID_BYTES + 1),
+        parent_group_id: null,
+        name: 'root',
+      }),
+    ).toThrow();
+  });
+
+  it('rejects a group_start whose parent_group_id exceeds the byte cap', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'group_start',
+        group_id: 'g1',
+        parent_group_id: 'g'.repeat(MAX_RECORD_GROUP_ID_BYTES + 1),
+        name: 'root',
+      }),
+    ).toThrow();
+  });
+
+  it('accepts a group_id exactly at the byte cap', () => {
+    const group_id = 'g'.repeat(MAX_RECORD_GROUP_ID_BYTES);
+
+    const parsed = logRecordSchema.parse({
+      v: 1,
+      ts,
+      type: 'group_start',
+      group_id,
+      parent_group_id: null,
+      name: 'root',
+    });
+
+    expect(parsed).toMatchObject({type: 'group_start', group_id});
+  });
+
+  it('rejects a group_end whose group_id exceeds the byte cap', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'group_end',
+        group_id: 'g'.repeat(MAX_RECORD_GROUP_ID_BYTES + 1),
+      }),
+    ).toThrow();
+  });
+
+  it('rejects an empty group_id', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'group_start',
+        group_id: '',
+        parent_group_id: null,
+        name: 'root',
+      }),
+    ).toThrow();
+  });
+
+  it('rejects an empty parent_group_id (a non-null parent must be a real id)', () => {
+    expect(() =>
+      logRecordSchema.parse({
+        v: 1,
+        ts,
+        type: 'group_start',
+        group_id: 'g1',
+        parent_group_id: '',
+        name: 'root',
+      }),
+    ).toThrow();
+  });
+});
+
+describe('rawLogRecordSchema (write path)', () => {
+  it.each(recordsByType.filter((r) => r.raw))('accepts the raw $record.type record', ({record}) => {
+    const parsed = rawLogRecordSchema.parse(record);
+
+    expect(parsed).toEqual(record);
+  });
+
+  it.each(
+    recordsByType.filter((r) => !r.raw),
+  )('rejects the read-only $record.type record even though the read union accepts it', ({
+    record,
+  }) => {
+    expect(() => logRecordSchema.parse(record)).not.toThrow();
+
+    expect(() => rawLogRecordSchema.parse(record)).toThrow();
+  });
+
+  it('accepts a raw agent_session record whose data far exceeds the output byte cap', () => {
+    const data = 'x'.repeat(MAX_RECORD_DATA_BYTES * 4);
+
+    const parsed = rawLogRecordSchema.parse({v: 1, ts, type: 'agent_session', data});
+
+    expect(Buffer.byteLength((parsed as {data: string}).data, 'utf8')).toBe(
+      MAX_RECORD_DATA_BYTES * 4,
+    );
+  });
+
+  it('rejects an empty raw agent_session record', () => {
+    expect(() => rawLogRecordSchema.parse({v: 1, ts, type: 'agent_session', data: ''})).toThrow();
+  });
+});
+
+describe('parseLogRecordLine', () => {
+  it('parses a JSON line', () => {
+    const parsed: LogRecord = parseLogRecordLine(
+      '{"v":1,"ts":1,"type":"output","stream":"stdout","data":"hi"}',
+    );
+
+    expect(parsed).toMatchObject({type: 'output', data: 'hi'});
+  });
+
+  it('throws on invalid JSON', () => {
+    expect(() => parseLogRecordLine('{not json')).toThrow();
+  });
+});
+
+describe('parseRawLogRecordLine', () => {
+  it('parses a raw JSON line', () => {
+    const parsed: RawLogRecord = parseRawLogRecordLine(
+      '{"v":1,"ts":1,"type":"output","stream":"stdout","data":"hi"}',
+    );
+
+    expect(parsed).toMatchObject({type: 'output', data: 'hi'});
+  });
+
+  it('rejects a forged server-only tombstone', () => {
+    expect(() => parseRawLogRecordLine('{"v":1,"ts":1,"type":"capped"}')).toThrow();
+    expect(() => parseRawLogRecordLine('{"v":1,"ts":1,"type":"runner_lost"}')).toThrow();
+  });
+});

package/src/schemas/record.ts

@@ -0,0 +1,151 @@
+import {z} from 'zod';
+import {sessionViewRowSchema} from './session-view.js';
+
+/**
+ * NDJSON log record contract — one JSON object per line, runner-framed.
+ *
+ * `offset` / `committed_length` are byte positions in the raw append NDJSON spool stream
+ * (envelope included) — the offset-CAS axis the runner tracks. The per-job accrual
+ * budget charges the normalized NDJSON bytes the server stores, so framing and control records
+ * count against it too. The per-record byte caps below bound each record so a single
+ * entry's overhead is known and a runner cannot grow storage without moving the
+ * budget: `data` is non-empty and <= MAX_RECORD_DATA_BYTES, the group `name` is
+ * <= MAX_RECORD_NAME_BYTES, the group ids are <= MAX_RECORD_GROUP_ID_BYTES, and every
+ * other field is fixed-shape.
+ *
+ * The envelope is `{v, ts}`, and every record is discriminated by a single flat
+ * `type`. The raw/write and stored/read unions are distinct types: the server-only
+ * `capped` / `runner_lost` tombstones are members of the read union only, so a forged
+ * tombstone cannot pass append validation.
+ *
+ * The append-side `agent_session` record carries one verbatim agent session entry line
+ * in `data`, forwarded opaquely by the runner. On successful ingest, the API normalizes
+ * that raw entry into one or more read-side `agent_session` records whose `row` is the
+ * canonical session view row. The raw and normalized records travel through the same log
+ * append/read pipe; only their contract at each boundary differs.
+ */
+
+/** Largest decoded `data` payload per record. Longer lines are split by the runner. */
+export const MAX_RECORD_DATA_BYTES = 16 * 1024;
+
+/** Largest `group_start` name. Bounds the only variable-length control field. */
+export const MAX_RECORD_NAME_BYTES = 1024;
+
+/**
+ * Largest `group_id` / `parent_group_id`. The runner emits short monotonic ids (`g1`,
+ * `g2`, …); this only bounds a forged id from a lease-scoped writer so the ids stay a
+ * fixed-shape field like every other record field.
+ */
+export const MAX_RECORD_GROUP_ID_BYTES = 256;
+
+// UTF-8 byte length without node:buffer, so this shared DTO stays browser-safe (the
+// client log viewer imports these types too). Identical to Buffer.byteLength(x, 'utf8').
+const utf8Encoder = new TextEncoder();
+const utf8ByteLength = (value: string): number => utf8Encoder.encode(value).length;
+
+const groupId = z
+  .string()
+  .min(1, {message: 'group id must not be empty'})
+  .refine((value) => utf8ByteLength(value) <= MAX_RECORD_GROUP_ID_BYTES, {
+    message: `group id exceeds ${MAX_RECORD_GROUP_ID_BYTES} bytes`,
+  });
+
+const envelope = {
+  v: z.literal(1),
+  /** Epoch milliseconds, assigned by the runner at capture. */
+  ts: z.number().int().nonnegative(),
+};
+
+const logOutput = z.object({
+  ...envelope,
+  type: z.literal('output'),
+  stream: z.enum(['stdout', 'stderr']),
+  data: z
+    .string()
+    .min(1, {message: 'output data must not be empty'})
+    .refine((value) => utf8ByteLength(value) <= MAX_RECORD_DATA_BYTES, {
+      message: `data exceeds ${MAX_RECORD_DATA_BYTES} payload bytes`,
+    }),
+});
+
+const logGroupStart = z.object({
+  ...envelope,
+  type: z.literal('group_start'),
+  group_id: groupId,
+  parent_group_id: groupId.nullable(),
+  name: z.string().refine((value) => utf8ByteLength(value) <= MAX_RECORD_NAME_BYTES, {
+    message: `group name exceeds ${MAX_RECORD_NAME_BYTES} bytes`,
+  }),
+});
+
+const logGroupEnd = z.object({...envelope, type: z.literal('group_end'), group_id: groupId});
+
+const logEnd = z.object({
+  ...envelope,
+  type: z.literal('end'),
+  total_bytes: z.number().int().nonnegative(),
+});
+
+const logGap = z.object({
+  ...envelope,
+  type: z.literal('gap'),
+  dropped_bytes: z.number().int().nonnegative(),
+});
+
+// One verbatim agent session entry line, forwarded opaquely by the runner. `data` is
+// intentionally uncapped here: the per-line byte limit is the server's configurable
+// LOG_MAX_SESSION_LINE_BYTES (a Zod schema cannot read runtime config, and a static cap
+// would collide with the body-limit invariant), enforced in the append write path.
+const rawAgentSession = z.object({
+  ...envelope,
+  type: z.literal('agent_session'),
+  data: z.string().min(1, {message: 'agent_session data must not be empty'}),
+});
+
+const agentSession = z.object({
+  ...envelope,
+  type: z.literal('agent_session'),
+  row: sessionViewRowSchema,
+});
+
+// Server-only tombstones: NOT members of the raw write union.
+const logCapped = z.object({...envelope, type: z.literal('capped')});
+const logRunnerLost = z.object({...envelope, type: z.literal('runner_lost')});
+
+/** Records a lease-scoped runner may append. The write path validates against this. */
+export const rawLogRecordSchema = z.discriminatedUnion('type', [
+  logOutput,
+  logGroupStart,
+  logGroupEnd,
+  logEnd,
+  logGap,
+  rawAgentSession,
+]);
+
+/** Stored/read records: regular records, normalized agent sessions, and tombstones. */
+export const logRecordSchema = z.discriminatedUnion('type', [
+  logOutput,
+  logGroupStart,
+  logGroupEnd,
+  logEnd,
+  logGap,
+  agentSession,
+  logCapped,
+  logRunnerLost,
+]);
+
+export type RawLogRecord = z.infer<typeof rawLogRecordSchema>;
+export type LogRecord = z.infer<typeof logRecordSchema>;
+
+export function parseLogRecordLine(line: string): LogRecord {
+  return logRecordSchema.parse(JSON.parse(line));
+}
+
+/**
+ * Parses one NDJSON line against the raw write union. A forged
+ * server-only `capped` / `runner_lost` record fails here even though it is valid
+ * under the read union — this is the write-path forgery guard.
+ */
+export function parseRawLogRecordLine(line: string): RawLogRecord {
+  return rawLogRecordSchema.parse(JSON.parse(line));
+}

package/src/schemas/session-view.test.ts

@@ -0,0 +1,96 @@
+import {
+  SESSION_VIEW_VERSION,
+  type SessionViewRow,
+  sessionViewRawRowSchema,
+  sessionViewRowSchema,
+  sessionViewSchema,
+} from './session-view.js';
+
+const timestamp = 1_765_531_200_123;
+
+const rowsByKind: SessionViewRow[] = [
+  {
+    kind: 'message',
+    timestamp,
+    role: 'assistant',
+    label: 'assistant',
+    meta: [{label: 'model', value: 'anthropic/claude-opus-4'}],
+    text: 'Implemented the change.',
+    terminalFailure: false,
+  },
+  {kind: 'thinking', timestamp, text: 'Inspect the existing parser first.'},
+  {
+    kind: 'tool-call',
+    timestamp,
+    id: 'call-1',
+    name: 'read_file',
+    input: '{"path":"src/index.ts"}',
+  },
+  {
+    kind: 'tool-result',
+    timestamp,
+    toolCallId: 'call-1',
+    toolName: 'read_file',
+    output: 'file contents',
+    isError: false,
+  },
+  {
+    kind: 'lifecycle',
+    timestamp,
+    label: 'Session started',
+    detail: 'session-1',
+    meta: [],
+    tone: 'default',
+    terminalFailure: false,
+  },
+  {
+    kind: 'raw',
+    timestamp,
+    label: 'Unknown session entry',
+    raw: '{"type":"future_entry","payload":{"value":true}}',
+  },
+];
+
+describe('sessionViewRowSchema', () => {
+  it.each(rowsByKind)('parses the $kind row', (row) => {
+    const parsed = sessionViewRowSchema.parse(row);
+
+    expect(parsed).toEqual(row);
+  });
+
+  it('rejects an unsupported row kind', () => {
+    const parse = () => sessionViewRowSchema.parse({kind: 'harness-specific', timestamp});
+
+    expect(parse).toThrow();
+  });
+
+  it('keeps the raw fallback variant harness-neutral', () => {
+    const parsed = sessionViewRawRowSchema.parse({
+      kind: 'raw',
+      timestamp,
+      label: 'Malformed session entry',
+      raw: '{not json',
+    });
+
+    expect(parsed).toEqual({
+      kind: 'raw',
+      timestamp,
+      label: 'Malformed session entry',
+      raw: '{not json',
+    });
+  });
+});
+
+describe('sessionViewSchema', () => {
+  it('parses the versioned session view envelope', () => {
+    const parsed = sessionViewSchema.parse({v: SESSION_VIEW_VERSION, rows: rowsByKind});
+
+    expect(parsed.rows).toHaveLength(rowsByKind.length);
+  });
+
+  it('rejects an unsupported session view version', () => {
+    const parse = () => sessionViewSchema.parse({v: 2, rows: []});
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/session-view.ts

@@ -0,0 +1,89 @@
+import {z} from 'zod';
+
+export const SESSION_VIEW_VERSION = 1;
+
+const timestampSchema = z.number().int().nonnegative();
+
+export const sessionViewRowMetaSchema = z.object({
+  label: z.string().min(1),
+  value: z.string(),
+  inline: z.boolean().optional(),
+});
+
+const sessionViewRowBase = {
+  timestamp: timestampSchema,
+};
+
+export const sessionViewMessageRowSchema = z.object({
+  ...sessionViewRowBase,
+  kind: z.literal('message'),
+  role: z.string().min(1),
+  label: z.string().min(1),
+  meta: z.array(sessionViewRowMetaSchema).readonly(),
+  text: z.string(),
+  terminalFailure: z.boolean(),
+});
+
+export const sessionViewThinkingRowSchema = z.object({
+  ...sessionViewRowBase,
+  kind: z.literal('thinking'),
+  text: z.string(),
+});
+
+export const sessionViewToolCallRowSchema = z.object({
+  ...sessionViewRowBase,
+  kind: z.literal('tool-call'),
+  id: z.string().nullable(),
+  name: z.string().min(1),
+  input: z.string(),
+});
+
+export const sessionViewToolResultRowSchema = z.object({
+  ...sessionViewRowBase,
+  kind: z.literal('tool-result'),
+  toolCallId: z.string().nullable(),
+  toolName: z.string().min(1),
+  output: z.string(),
+  isError: z.boolean(),
+});
+
+export const sessionViewLifecycleRowSchema = z.object({
+  ...sessionViewRowBase,
+  kind: z.literal('lifecycle'),
+  label: z.string().min(1),
+  detail: z.string().nullable(),
+  meta: z.array(sessionViewRowMetaSchema).readonly(),
+  tone: z.enum(['default', 'warning', 'error']),
+  terminalFailure: z.boolean(),
+});
+
+export const sessionViewRawRowSchema = z.object({
+  ...sessionViewRowBase,
+  kind: z.literal('raw'),
+  label: z.string().min(1),
+  raw: z.string(),
+});
+
+export const sessionViewRowSchema = z.discriminatedUnion('kind', [
+  sessionViewMessageRowSchema,
+  sessionViewThinkingRowSchema,
+  sessionViewToolCallRowSchema,
+  sessionViewToolResultRowSchema,
+  sessionViewLifecycleRowSchema,
+  sessionViewRawRowSchema,
+]);
+
+export const sessionViewSchema = z.object({
+  v: z.literal(SESSION_VIEW_VERSION),
+  rows: z.array(sessionViewRowSchema).readonly(),
+});
+
+export type SessionViewRowMeta = z.infer<typeof sessionViewRowMetaSchema>;
+export type SessionViewMessageRow = z.infer<typeof sessionViewMessageRowSchema>;
+export type SessionViewThinkingRow = z.infer<typeof sessionViewThinkingRowSchema>;
+export type SessionViewToolCallRow = z.infer<typeof sessionViewToolCallRowSchema>;
+export type SessionViewToolResultRow = z.infer<typeof sessionViewToolResultRowSchema>;
+export type SessionViewLifecycleRow = z.infer<typeof sessionViewLifecycleRowSchema>;
+export type SessionViewRawRow = z.infer<typeof sessionViewRawRowSchema>;
+export type SessionViewRow = z.infer<typeof sessionViewRowSchema>;
+export type SessionViewDto = z.infer<typeof sessionViewSchema>;

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/node",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}