@crewhaus/gateway-protocol 0.3.2 → 0.4.2

package/dist/index.d.ts

@@ -231,13 +231,125 @@ export declare const AuditTailParams: z.ZodObject<{
     sinceTs?: number | undefined;
 }>;
 export type AuditTailParamsT = z.infer<typeof AuditTailParams>;
-export declare const Method: z.ZodEnum<["runs.create", "runs.continue", "runs.cancel", "runs.subscribe", "sessions.list", "sessions.fork", "audit.tail"]>;
+/** Mirror of `@crewhaus/feedback-distill`'s `MAX_FEEDBACK_TEXT`. Kept in sync
+ *  by hand for the same reason as SESSION_ID_REGEX above; the distill side
+ *  still clips, so a drift can only ever be stricter here. */
+export declare const MAX_FEEDBACK_TEXT = 8192;
+export declare const FeedbackSubmitParams: z.ZodEffects<z.ZodObject<{
+    sessionId: z.ZodString;
+    /** 1-based ordinal of the rated user-text turn. */
+    turnNumber: z.ZodNumber;
+    thumbs: z.ZodOptional<z.ZodEnum<["up", "down"]>>;
+    stars: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        value: number;
+        min: number;
+        max: number;
+    }, {
+        value: number;
+        min: number;
+        max: number;
+    }>>;
+    comment: z.ZodOptional<z.ZodString>;
+    /** A better answer — becomes `expected_output` at distill time. */
+    correction: z.ZodOptional<z.ZodString>;
+    /** Opaque rater handle. Redacted at ingestion like every other free text. */
+    rater: z.ZodOptional<z.ZodString>;
+    /** B19 — this record settles a multi-rater disagreement. */
+    adjudication: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    sessionId: string;
+    turnNumber: number;
+    thumbs?: "up" | "down" | undefined;
+    stars?: number | undefined;
+    scale?: {
+        value: number;
+        min: number;
+        max: number;
+    } | undefined;
+    comment?: string | undefined;
+    correction?: string | undefined;
+    rater?: string | undefined;
+    adjudication?: boolean | undefined;
+}, {
+    sessionId: string;
+    turnNumber: number;
+    thumbs?: "up" | "down" | undefined;
+    stars?: number | undefined;
+    scale?: {
+        value: number;
+        min: number;
+        max: number;
+    } | undefined;
+    comment?: string | undefined;
+    correction?: string | undefined;
+    rater?: string | undefined;
+    adjudication?: boolean | undefined;
+}>, {
+    sessionId: string;
+    turnNumber: number;
+    thumbs?: "up" | "down" | undefined;
+    stars?: number | undefined;
+    scale?: {
+        value: number;
+        min: number;
+        max: number;
+    } | undefined;
+    comment?: string | undefined;
+    correction?: string | undefined;
+    rater?: string | undefined;
+    adjudication?: boolean | undefined;
+}, {
+    sessionId: string;
+    turnNumber: number;
+    thumbs?: "up" | "down" | undefined;
+    stars?: number | undefined;
+    scale?: {
+        value: number;
+        min: number;
+        max: number;
+    } | undefined;
+    comment?: string | undefined;
+    correction?: string | undefined;
+    rater?: string | undefined;
+    adjudication?: boolean | undefined;
+}>;
+export declare const FeedbackSubmitResult: z.ZodObject<{
+    recorded: z.ZodBoolean;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    recorded: boolean;
+}, {
+    id: string;
+    recorded: boolean;
+}>;
+export type FeedbackSubmitParamsT = z.infer<typeof FeedbackSubmitParams>;
+export type FeedbackSubmitResultT = z.infer<typeof FeedbackSubmitResult>;
+export declare const Method: z.ZodEnum<["runs.create", "runs.continue", "runs.cancel", "runs.subscribe", "sessions.list", "sessions.fork", "audit.tail", "feedback.submit"]>;
 export type MethodT = z.infer<typeof Method>;
 export declare function decodeRequest(raw: unknown): RequestEnvelopeT & {
     method: MethodT;
 };
 export declare function encodeSuccess(id: string, result: unknown): ResponseEnvelopeT;
 export declare function encodeError(id: string, code: string, message: string, data?: unknown): ResponseEnvelopeT;
+/** MIME type of a `runs.subscribe` response body. */
+export declare const SSE_CONTENT_TYPE: "text/event-stream";
+/**
+ * Encode one trace event as an SSE `data:` frame. `event` is serialized with
+ * `JSON.stringify` (a TraceEvent is always JSON-serializable), so the frame is
+ * a single `data:` line terminated by the mandatory blank line.
+ */
+export declare function encodeSseEvent(event: unknown): string;
+/**
+ * Encode an SSE comment frame (heartbeat / open marker). Any newline in `text`
+ * is collapsed to a space so the comment stays a single well-formed frame.
+ */
+export declare function encodeSseComment(text: string): string;
 export declare const ErrorCode: {
     readonly Unauthorized: "unauthorized";
     readonly Forbidden: "forbidden";

package/dist/index.js

@@ -116,6 +116,63 @@ export const SessionsForkResult = z.object({ newSessionId: z.string().min(1) }).
 export const AuditTailParams = z
     .object({ tenantId: z.string().min(1), sinceTs: z.number().int().nonnegative().optional() })
     .strict();
+/**
+ * NEW-inloop-coverage — the gateway's RATING-CAPTURE method. A gateway-served
+ * agent is the highest-traffic surface CrewHaus has, and until this method it
+ * had no spec'd way to record a human verdict at all: `distill`, `optimize
+ * --ratings`, `judge calibrate` and the auto-distill flywheel were all
+ * structurally unreachable for the managed shape.
+ *
+ * The params are the USER-SUPPLIED subset of a `FeedbackRecord` (the daemon
+ * stamps `schemaVersion`, `id`, `source: "ui"` and `ts` itself, so a client
+ * cannot forge provenance or backdate a rating past the auto-distill
+ * watermark). `sessionId` + `turnNumber` are the same join key `crewhaus
+ * rate` uses, so a gateway rating and a CLI rating distill identically.
+ *
+ * The grammars are pinned HERE, at the boundary, so a bad submission is a
+ * protocol error instead of a durable line nothing downstream can use:
+ *   - `sessionId` must match `@crewhaus/session-store`'s id grammar, which is
+ *     also what `isFeedbackRecord` requires — an id in any other shape would
+ *     be accepted, written, counted against disk, and then silently dropped
+ *     by every reader (and it is interpolated into a path by the managed
+ *     daemon's tenant-ownership check);
+ *   - the free-text fields are length-capped at the same bound
+ *     `clipFeedbackText` enforces, so oversize input is REFUSED rather than
+ *     silently truncated on a surface whose `correction` becomes a dataset's
+ *     `expected_output`.
+ */
+/** `@crewhaus/session-store`'s `generateId` grammar (mirrored — this package
+ *  is dependency-light by design and must not pull the store in). */
+const SESSION_ID_REGEX = /^sess_[0-9a-f]{16}$/;
+/** Mirror of `@crewhaus/feedback-distill`'s `MAX_FEEDBACK_TEXT`. Kept in sync
+ *  by hand for the same reason as SESSION_ID_REGEX above; the distill side
+ *  still clips, so a drift can only ever be stricter here. */
+export const MAX_FEEDBACK_TEXT = 8192;
+export const FeedbackSubmitParams = z
+    .object({
+    sessionId: z.string().regex(SESSION_ID_REGEX, "sessionId must look like sess_<16 hex digits>"),
+    /** 1-based ordinal of the rated user-text turn. */
+    turnNumber: z.number().int().positive(),
+    thumbs: z.enum(["up", "down"]).optional(),
+    stars: z.number().int().min(1).max(5).optional(),
+    scale: z.object({ value: z.number(), min: z.number(), max: z.number() }).strict().optional(),
+    comment: z.string().max(MAX_FEEDBACK_TEXT).optional(),
+    /** A better answer — becomes `expected_output` at distill time. */
+    correction: z.string().max(MAX_FEEDBACK_TEXT).optional(),
+    /** Opaque rater handle. Redacted at ingestion like every other free text. */
+    rater: z.string().max(MAX_FEEDBACK_TEXT).optional(),
+    /** B19 — this record settles a multi-rater disagreement. */
+    adjudication: z.boolean().optional(),
+})
+    .strict()
+    .refine((p) => p.thumbs !== undefined ||
+    p.stars !== undefined ||
+    p.scale !== undefined ||
+    (p.comment ?? "") !== "" ||
+    (p.correction ?? "") !== "", { message: "feedback.submit needs at least one of thumbs/stars/scale/comment/correction" });
+export const FeedbackSubmitResult = z
+    .object({ recorded: z.boolean(), id: z.string().min(1) })
+    .strict();
 export const Method = z.enum([
     "runs.create",
     "runs.continue",
@@ -124,6 +181,7 @@ export const Method = z.enum([
     "sessions.list",
     "sessions.fork",
     "audit.tail",
+    "feedback.submit",
 ]);
 const PARAM_SCHEMAS = {
     "runs.create": RunsCreateParams,
@@ -133,6 +191,7 @@ const PARAM_SCHEMAS = {
     "sessions.list": SessionsListParams,
     "sessions.fork": SessionsForkParams,
     "audit.tail": AuditTailParams,
+    "feedback.submit": FeedbackSubmitParams,
 };
 export function decodeRequest(raw) {
     const parsed = RequestEnvelope.safeParse(raw);
@@ -165,6 +224,45 @@ export function encodeError(id, code, message, data) {
     };
 }
 // ---------------------------------------------------------------------------
+// `runs.subscribe` — Server-Sent Events framing.
+//
+// `runs.subscribe` is the ONE method that does not answer with a JSON
+// `ResponseEnvelope`: it upgrades to a long-lived `text/event-stream` that
+// replays the run's buffered trace events and then live-streams new ones.
+// The frame format lives HERE (the wire-contract package) so the daemon and
+// every reference client encode/parse it identically:
+//
+//   - each trace event is one SSE `data:` frame carrying the event's JSON.
+//     `JSON.stringify` never emits a literal newline (newlines inside string
+//     fields are escaped to `\n`), so one event is always exactly one `data:`
+//     line — no multi-line-`data:` reassembly is required on the read side.
+//   - heartbeats and the connection-open marker are SSE COMMENT frames
+//     (`:`-prefixed); a spec-compliant client ignores them, so they keep
+//     intermediaries from idling the connection out without polluting the
+//     event stream. A comment body must not contain a newline.
+//
+// A stream carries no envelope `id`/`protocol` — those are per-request-reply
+// fields; the subscription is a fire-hose keyed by the `runId` in the
+// originating `runs.subscribe` request.
+// ---------------------------------------------------------------------------
+/** MIME type of a `runs.subscribe` response body. */
+export const SSE_CONTENT_TYPE = "text/event-stream";
+/**
+ * Encode one trace event as an SSE `data:` frame. `event` is serialized with
+ * `JSON.stringify` (a TraceEvent is always JSON-serializable), so the frame is
+ * a single `data:` line terminated by the mandatory blank line.
+ */
+export function encodeSseEvent(event) {
+    return `data: ${JSON.stringify(event)}\n\n`;
+}
+/**
+ * Encode an SSE comment frame (heartbeat / open marker). Any newline in `text`
+ * is collapsed to a space so the comment stays a single well-formed frame.
+ */
+export function encodeSseComment(text) {
+    return `: ${text.replace(/[\r\n]+/g, " ")}\n\n`;
+}
+// ---------------------------------------------------------------------------
 // Standard error codes — wire-stable so reference clients can switch on them.
 // ---------------------------------------------------------------------------
 export const ErrorCode = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/gateway-protocol",
-  "version": "0.3.2",
+  "version": "0.4.2",
   "type": "module",
   "description": "JSON-RPC wire protocol for the managed-daemon gateway — versioned envelope + Zod schemas",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.3.2",
+    "@crewhaus/errors": "0.4.2",
     "zod": "^3.23.8"
   },
   "license": "Apache-2.0",