@kynetic-ai/spec 0.1.0

package/dist/sessions/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Session event storage types and schemas.
+ *
+ * Provides JSONL-based event storage for agent sessions with:
+ * - Session metadata tracking
+ * - Append-only event logs
+ * - Integration with kspec commit boundaries
+ */
+import { z } from 'zod';
+/**
+ * Session status enum.
+ * - active: Session is in progress
+ * - completed: Session ended normally
+ * - abandoned: Session ended without explicit close
+ */
+export declare const SessionStatusSchema: z.ZodEnum<["active", "completed", "abandoned"]>;
+export type SessionStatus = z.infer<typeof SessionStatusSchema>;
+/**
+ * Session metadata stored in session.yaml.
+ * AC-5: includes task_id (optional), agent_type, status, started_at, ended_at
+ */
+export declare const SessionMetadataSchema: z.ZodObject<{
+    /** Session ULID */
+    id: z.ZodString;
+    /** Optional task being worked on */
+    task_id: z.ZodOptional<z.ZodString>;
+    /** Type of agent running the session */
+    agent_type: z.ZodString;
+    /** Current session status */
+    status: z.ZodEnum<["active", "completed", "abandoned"]>;
+    /** When session started (ISO 8601) */
+    started_at: z.ZodString;
+    /** When session ended (ISO 8601) - only set when status != 'active' */
+    ended_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "completed" | "active" | "abandoned";
+    id: string;
+    started_at: string;
+    agent_type: string;
+    task_id?: string | undefined;
+    ended_at?: string | undefined;
+}, {
+    status: "completed" | "active" | "abandoned";
+    id: string;
+    started_at: string;
+    agent_type: string;
+    task_id?: string | undefined;
+    ended_at?: string | undefined;
+}>;
+export type SessionMetadata = z.infer<typeof SessionMetadataSchema>;
+/**
+ * Input for creating a new session.
+ */
+export declare const SessionMetadataInputSchema: z.ZodObject<Omit<{
+    /** Session ULID */
+    id: z.ZodString;
+    /** Optional task being worked on */
+    task_id: z.ZodOptional<z.ZodString>;
+    /** Type of agent running the session */
+    agent_type: z.ZodString;
+    /** Current session status */
+    status: z.ZodEnum<["active", "completed", "abandoned"]>;
+    /** When session started (ISO 8601) */
+    started_at: z.ZodString;
+    /** When session ended (ISO 8601) - only set when status != 'active' */
+    ended_at: z.ZodOptional<z.ZodString>;
+}, "status" | "started_at" | "ended_at"> & {
+    status: z.ZodOptional<z.ZodEnum<["active", "completed", "abandoned"]>>;
+    started_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    agent_type: string;
+    status?: "completed" | "active" | "abandoned" | undefined;
+    started_at?: string | undefined;
+    task_id?: string | undefined;
+}, {
+    id: string;
+    agent_type: string;
+    status?: "completed" | "active" | "abandoned" | undefined;
+    started_at?: string | undefined;
+    task_id?: string | undefined;
+}>;
+export type SessionMetadataInput = z.infer<typeof SessionMetadataInputSchema>;
+/**
+ * Supported event types for session tracking.
+ */
+export declare const EventTypeSchema: z.ZodEnum<["session.start", "session.update", "session.end", "prompt.sent", "tool.call", "tool.result", "note"]>;
+export type EventType = z.infer<typeof EventTypeSchema>;
+/**
+ * A single event in the session log.
+ * AC-2: Events include ts and seq auto-assigned on append.
+ */
+export declare const SessionEventSchema: z.ZodObject<{
+    /** Unix timestamp in milliseconds (auto-assigned) */
+    ts: z.ZodNumber;
+    /** Sequence number in session (auto-assigned, 0-indexed) */
+    seq: z.ZodNumber;
+    /** Event type */
+    type: z.ZodEnum<["session.start", "session.update", "session.end", "prompt.sent", "tool.call", "tool.result", "note"]>;
+    /** Session this event belongs to */
+    session_id: z.ZodString;
+    /** Optional trace ID for correlation */
+    trace_id: z.ZodOptional<z.ZodString>;
+    /** Type-specific event payload */
+    data: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "note" | "session.start" | "session.update" | "session.end" | "prompt.sent" | "tool.call" | "tool.result";
+    ts: number;
+    seq: number;
+    session_id: string;
+    data?: unknown;
+    trace_id?: string | undefined;
+}, {
+    type: "note" | "session.start" | "session.update" | "session.end" | "prompt.sent" | "tool.call" | "tool.result";
+    ts: number;
+    seq: number;
+    session_id: string;
+    data?: unknown;
+    trace_id?: string | undefined;
+}>;
+export type SessionEvent = z.infer<typeof SessionEventSchema>;
+/**
+ * Input for appending an event (without auto-assigned fields).
+ */
+export declare const SessionEventInputSchema: z.ZodObject<Omit<{
+    /** Unix timestamp in milliseconds (auto-assigned) */
+    ts: z.ZodNumber;
+    /** Sequence number in session (auto-assigned, 0-indexed) */
+    seq: z.ZodNumber;
+    /** Event type */
+    type: z.ZodEnum<["session.start", "session.update", "session.end", "prompt.sent", "tool.call", "tool.result", "note"]>;
+    /** Session this event belongs to */
+    session_id: z.ZodString;
+    /** Optional trace ID for correlation */
+    trace_id: z.ZodOptional<z.ZodString>;
+    /** Type-specific event payload */
+    data: z.ZodUnknown;
+}, "ts" | "seq"> & {
+    ts: z.ZodOptional<z.ZodNumber>;
+    seq: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "note" | "session.start" | "session.update" | "session.end" | "prompt.sent" | "tool.call" | "tool.result";
+    session_id: string;
+    data?: unknown;
+    ts?: number | undefined;
+    seq?: number | undefined;
+    trace_id?: string | undefined;
+}, {
+    type: "note" | "session.start" | "session.update" | "session.end" | "prompt.sent" | "tool.call" | "tool.result";
+    session_id: string;
+    data?: unknown;
+    ts?: number | undefined;
+    seq?: number | undefined;
+    trace_id?: string | undefined;
+}>;
+export type SessionEventInput = z.infer<typeof SessionEventInputSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/sessions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sessions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iDAA+C,CAAC;AAChF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE;;;GAGG;AACH,eAAO,MAAM,qBAAqB;IAChC,mBAAmB;;IAGnB,oCAAoC;;IAGpC,wCAAwC;;IAGxC,6BAA6B;;IAG7B,sCAAsC;;IAGtC,uEAAuE;;;;;;;;;;;;;;;;EAEvE,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,0BAA0B;IAxBrC,mBAAmB;;IAGnB,oCAAoC;;IAGpC,wCAAwC;;IAGxC,6BAA6B;;IAG7B,sCAAsC;;IAGtC,uEAAuE;;;;;;;;;;;;;;;;;EAgBvE,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI9E;;GAEG;AACH,eAAO,MAAM,eAAe,kHAQ1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD;;;GAGG;AACH,eAAO,MAAM,kBAAkB;IAC7B,qDAAqD;;IAGrD,4DAA4D;;IAG5D,iBAAiB;;IAGjB,oCAAoC;;IAGpC,wCAAwC;;IAGxC,kCAAkC;;;;;;;;;;;;;;;;EAElC,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,uBAAuB;IAxBlC,qDAAqD;;IAGrD,4DAA4D;;IAG5D,iBAAiB;;IAGjB,oCAAoC;;IAGpC,wCAAwC;;IAGxC,kCAAkC;;;;;;;;;;;;;;;;;;;EAelC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/sessions/types.js

@@ -0,0 +1,90 @@
+/**
+ * Session event storage types and schemas.
+ *
+ * Provides JSONL-based event storage for agent sessions with:
+ * - Session metadata tracking
+ * - Append-only event logs
+ * - Integration with kspec commit boundaries
+ */
+import { z } from 'zod';
+// ─── Session Status ──────────────────────────────────────────────────────────
+/**
+ * Session status enum.
+ * - active: Session is in progress
+ * - completed: Session ended normally
+ * - abandoned: Session ended without explicit close
+ */
+export const SessionStatusSchema = z.enum(['active', 'completed', 'abandoned']);
+// ─── Session Metadata ────────────────────────────────────────────────────────
+/**
+ * Session metadata stored in session.yaml.
+ * AC-5: includes task_id (optional), agent_type, status, started_at, ended_at
+ */
+export const SessionMetadataSchema = z.object({
+    /** Session ULID */
+    id: z.string(),
+    /** Optional task being worked on */
+    task_id: z.string().optional(),
+    /** Type of agent running the session */
+    agent_type: z.string(),
+    /** Current session status */
+    status: SessionStatusSchema,
+    /** When session started (ISO 8601) */
+    started_at: z.string().datetime(),
+    /** When session ended (ISO 8601) - only set when status != 'active' */
+    ended_at: z.string().datetime().optional(),
+});
+/**
+ * Input for creating a new session.
+ */
+export const SessionMetadataInputSchema = SessionMetadataSchema.omit({
+    status: true,
+    started_at: true,
+    ended_at: true,
+}).extend({
+    status: SessionStatusSchema.optional(),
+    started_at: z.string().datetime().optional(),
+});
+// ─── Event Types ─────────────────────────────────────────────────────────────
+/**
+ * Supported event types for session tracking.
+ */
+export const EventTypeSchema = z.enum([
+    'session.start',
+    'session.update',
+    'session.end',
+    'prompt.sent',
+    'tool.call',
+    'tool.result',
+    'note',
+]);
+// ─── Session Event ───────────────────────────────────────────────────────────
+/**
+ * A single event in the session log.
+ * AC-2: Events include ts and seq auto-assigned on append.
+ */
+export const SessionEventSchema = z.object({
+    /** Unix timestamp in milliseconds (auto-assigned) */
+    ts: z.number(),
+    /** Sequence number in session (auto-assigned, 0-indexed) */
+    seq: z.number().int().nonnegative(),
+    /** Event type */
+    type: EventTypeSchema,
+    /** Session this event belongs to */
+    session_id: z.string(),
+    /** Optional trace ID for correlation */
+    trace_id: z.string().optional(),
+    /** Type-specific event payload */
+    data: z.unknown(),
+});
+/**
+ * Input for appending an event (without auto-assigned fields).
+ */
+export const SessionEventInputSchema = SessionEventSchema.omit({
+    ts: true,
+    seq: true,
+}).extend({
+    ts: z.number().optional(),
+    seq: z.number().int().nonnegative().optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/sessions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sessions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAGhF,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,mBAAmB;IACnB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IAEd,oCAAoC;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE9B,wCAAwC;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IAEtB,6BAA6B;IAC7B,MAAM,EAAE,mBAAmB;IAE3B,sCAAsC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEjC,uEAAuE;IACvE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,qBAAqB,CAAC,IAAI,CAAC;IACnE,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;CACf,CAAC,CAAC,MAAM,CAAC;IACR,MAAM,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAIH,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC;IACpC,eAAe;IACf,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,WAAW;IACX,aAAa;IACb,MAAM;CACP,CAAC,CAAC;AAIH,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,qDAAqD;IACrD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IAEd,4DAA4D;IAC5D,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAEnC,iBAAiB;IACjB,IAAI,EAAE,eAAe;IAErB,oCAAoC;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IAEtB,wCAAwC;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE/B,kCAAkC;IAClC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;CAClB,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAAkB,CAAC,IAAI,CAAC;IAC7D,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,IAAI;CACV,CAAC,CAAC,MAAM,CAAC;IACR,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC"}