@drisp/protocol 0.6.0

package/dist/index.js

@@ -0,0 +1,613 @@
+// src/version.ts
+var PROTOCOL_VERSION = 1;
+
+// src/domain.ts
+import { z } from "zod";
+var RunStatusSchema = z.enum([
+  "running",
+  "awaiting_attention",
+  "completed",
+  "blocked",
+  "exhausted",
+  "failed",
+  "cancelled"
+]);
+var RunSchema = z.object({
+  runId: z.string(),
+  /** The durable Athena Session this Run belongs to. */
+  athenaSessionId: z.string(),
+  workflowName: z.string().optional(),
+  /** What the Run was asked to do — the `**Goal**` its Run section records. */
+  goal: z.string().optional(),
+  /** Index of the most recent Turn (0 before Turn 1). */
+  iteration: z.int().nonnegative(),
+  maxIterations: z.int().positive().optional(),
+  status: RunStatusSchema,
+  stopReason: z.string().optional(),
+  /** Vendor session id of the Run's most recent Agent Session (ADR 0014). */
+  adapterSessionId: z.string().optional(),
+  startedAt: z.number(),
+  endedAt: z.number().optional()
+});
+var TurnContinuationSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("fresh") }),
+  z.object({ mode: z.literal("resume"), handle: z.string() }),
+  z.object({ mode: z.literal("reuse-current") })
+]);
+var TurnOutcomeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("continue") }),
+  z.object({
+    kind: z.literal("stop"),
+    status: RunStatusSchema,
+    stopReason: z.string().optional()
+  }),
+  z.object({
+    kind: z.literal("suspend"),
+    status: RunStatusSchema,
+    stopReason: z.string()
+  })
+]);
+var TurnSchema = z.object({
+  runId: z.string(),
+  /** 1-based Iteration of this Turn within its Run. */
+  iteration: z.int().positive(),
+  continuation: TurnContinuationSchema,
+  /** Vendor session id of the Agent Session this Turn ran in, once known. */
+  adapterSessionId: z.string().optional(),
+  startedAt: z.number(),
+  endedAt: z.number().optional(),
+  outcome: TurnOutcomeSchema.optional()
+});
+var HardFailureCodeSchema = z.enum([
+  "auth",
+  "billing",
+  "invalid_request",
+  "model_not_found",
+  "unclassified"
+]);
+var ExhaustedCapSchema = z.enum([
+  "retry",
+  "nudge",
+  "iterations",
+  "handover",
+  "tokens"
+]);
+var interruptionBase = {
+  /** Human-readable summary of why the Run parked. */
+  message: z.string()
+};
+var InterruptionSchema = z.discriminatedUnion("kind", [
+  z.object({
+    ...interruptionBase,
+    kind: z.literal("blocked"),
+    /** The `: reason` suffix of `NEEDS_HUMAN[: reason]`, when given. */
+    reason: z.string().optional()
+  }),
+  z.object({
+    ...interruptionBase,
+    kind: z.literal("question"),
+    /**
+     * The pending request an `answer` frame must address. Absent when the
+     * runner interrupted the Turn instead of leaving the question waiting
+     * (an unattended Workflow Run kills the Agent Session on a question,
+     * so there is no request left to answer); such a Run is woken with a
+     * `steer` carrying the human's guidance.
+     */
+    requestId: z.string().optional(),
+    question: z.string().optional()
+  }),
+  z.object({
+    ...interruptionBase,
+    kind: z.literal("hard_failure"),
+    code: HardFailureCodeSchema
+  }),
+  z.object({
+    ...interruptionBase,
+    kind: z.literal("cap_exhausted"),
+    cap: ExhaustedCapSchema,
+    limit: z.int().positive().optional(),
+    /** Structured policy decision. Older senders may supply only cap/message. */
+    resource: z.object({
+      cause: z.enum(["tokens", "iterations", "context", "restart"]),
+      limit: z.number().nonnegative(),
+      used: z.number().nonnegative(),
+      detail: z.string().optional(),
+      checkpointPath: z.string().optional(),
+      fresh: z.boolean()
+    }).optional()
+  })
+]);
+var RunSpecSchema = z.looseObject({
+  prompt: z.string().optional(),
+  athenaSessionId: z.string().optional(),
+  adapterResumeSessionId: z.string().optional(),
+  sessionId: z.string().optional(),
+  projectDir: z.string().optional(),
+  workflow: z.looseObject({
+    source: z.string().optional(),
+    ref: z.string().optional(),
+    version: z.string().optional()
+  }).optional(),
+  harness: z.string().optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  timeoutSec: z.number().optional(),
+  /** Per-run callback channel minted by the hub; both or neither. */
+  callbackWsUrl: z.string().optional(),
+  callbackToken: z.string().optional()
+});
+var RuntimeIntentSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("permission_allow") }),
+  z.object({ kind: z.literal("permission_deny"), reason: z.string() }),
+  z.object({
+    kind: z.literal("question_answer"),
+    answers: z.record(z.string(), z.string())
+  }),
+  z.object({ kind: z.literal("pre_tool_allow") }),
+  z.object({ kind: z.literal("pre_tool_deny"), reason: z.string() }),
+  z.object({ kind: z.literal("stop_block"), reason: z.string() }),
+  z.object({ kind: z.literal("compact_block"), reason: z.string() })
+]);
+var RuntimeDecisionSchema = z.object({
+  type: z.enum(["passthrough", "block", "json"]),
+  source: z.enum(["user", "timeout", "rule"]),
+  intent: RuntimeIntentSchema.optional(),
+  reason: z.string().optional(),
+  data: z.unknown().optional()
+});
+var AttachmentSchema = z.object({
+  runnerId: z.string(),
+  name: z.string().optional(),
+  slug: z.string().optional(),
+  executionTarget: z.string().optional(),
+  remoteInstanceId: z.string().optional()
+});
+var InstalledWorkflowSourceSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("builtin") }),
+  z.object({ kind: z.literal("marketplace-remote"), ref: z.string() }),
+  z.object({
+    kind: z.literal("marketplace-local"),
+    repoDir: z.string(),
+    workflowName: z.string()
+  }),
+  z.object({ kind: z.literal("filesystem"), path: z.string() }),
+  z.object({ kind: z.literal("unknown") })
+]);
+var InstalledWorkflowSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().optional(),
+  source: InstalledWorkflowSourceSchema
+});
+var AssignmentRejectedReasonSchema = z.enum([
+  "local_capacity",
+  "duplicate",
+  "malformed_assignment",
+  "workspace_unresolved",
+  "workspace_invalid"
+]);
+
+// src/events.ts
+import { z as z2 } from "zod";
+var RunStreamEventSchema = z2.object({
+  runId: z2.string(),
+  /** Runner-local order within the Run. */
+  seq: z2.int().nonnegative(),
+  ts: z2.number(),
+  kind: z2.string(),
+  payload: z2.unknown().optional()
+});
+var FeedEventLevelSchema = z2.enum(["debug", "info", "warn", "error"]);
+var FeedEventCauseSchema = z2.object({
+  parent_event_id: z2.string().optional(),
+  hook_request_id: z2.string().optional(),
+  tool_use_id: z2.string().optional(),
+  transcript_path: z2.string().optional()
+});
+var FeedEventSchema = z2.looseObject({
+  event_id: z2.string(),
+  seq: z2.int().nonnegative(),
+  ts: z2.number(),
+  session_id: z2.string(),
+  /** A Feed Run id (`{session_id}:R{n}`) — unrelated to a Workflow Run id. */
+  run_id: z2.string(),
+  prompt_id: z2.string().optional(),
+  effort_level: z2.string().optional(),
+  kind: z2.string(),
+  level: FeedEventLevelSchema,
+  actor_id: z2.string(),
+  cause: FeedEventCauseSchema.optional(),
+  title: z2.string(),
+  body: z2.string().optional(),
+  ui: z2.object({
+    collapsed_default: z2.boolean().optional(),
+    pin: z2.boolean().optional(),
+    badge: z2.string().optional()
+  }).optional(),
+  display: z2.object({ title: z2.string().optional() }).optional(),
+  data: z2.unknown(),
+  raw: z2.unknown().optional()
+});
+var PHASE_FEED_EVENT_KIND = "phase";
+var PhaseEventSchema = z2.object({
+  /** The Workflow Run id (not a Feed Run id). */
+  runId: z2.string(),
+  /** 1-based Iteration of the Turn whose Journal named this step. */
+  turn: z2.int().positive(),
+  step: z2.string().min(1),
+  stepIndex: z2.int().positive().optional(),
+  stepTotal: z2.int().positive().optional()
+});
+var PhaseFeedEventSchema = FeedEventSchema.extend({
+  kind: z2.literal(PHASE_FEED_EVENT_KIND),
+  data: PhaseEventSchema
+});
+var FeedOriginSchema = z2.enum(["local", "dashboard"]);
+var FeedEnvelopeSchema = z2.object({
+  instanceId: z2.string(),
+  athenaSessionId: z2.string(),
+  runId: z2.string(),
+  origin: FeedOriginSchema,
+  eventId: z2.string(),
+  feedSeq: z2.int().nonnegative(),
+  emittedAt: z2.number(),
+  feedEvent: FeedEventSchema
+});
+
+// src/frames.ts
+import { z as z3 } from "zod";
+var runStartBody = {
+  runId: z3.string(),
+  runSpec: RunSpecSchema.optional(),
+  /**
+   * The runner this assignment is bound to — top-level so the CLI can route
+   * to the right Attachment without inspecting `runSpec`. Absent from hubs
+   * that use single-runtime semantics.
+   */
+  runnerId: z3.string().optional()
+};
+var answerBody = {
+  athenaSessionId: z3.string(),
+  requestId: z3.string(),
+  decision: RuntimeDecisionSchema
+};
+var stopBody = {
+  runId: z3.string(),
+  runnerId: z3.string().optional()
+};
+var PingFrameSchema = z3.object({
+  type: z3.literal("ping"),
+  ts: z3.number()
+});
+var PongFrameSchema = z3.object({
+  type: z3.literal("pong"),
+  ts: z3.number()
+});
+var AssignmentAcceptedFrameSchema = z3.object({
+  type: z3.literal("assignment_accepted"),
+  runId: z3.string()
+});
+var AssignmentRejectedFrameSchema = z3.object({
+  type: z3.literal("assignment_rejected"),
+  runId: z3.string(),
+  reason: AssignmentRejectedReasonSchema,
+  message: z3.string().optional()
+});
+var DecisionAckFrameSchema = z3.object({
+  type: z3.literal("decision_ack"),
+  athenaSessionId: z3.string(),
+  requestId: z3.string()
+});
+var FeedAckFrameSchema = z3.object({
+  type: z3.literal("feed_ack"),
+  deliverySeq: z3.int().nonnegative().optional(),
+  eventId: z3.string().optional()
+});
+var AttachmentsChangedFrameSchema = z3.object({
+  type: z3.literal("attachments.changed"),
+  attachments: z3.array(AttachmentSchema)
+});
+var ErrorFrameSchema = z3.object({
+  type: z3.literal("error"),
+  code: z3.string(),
+  message: z3.string().optional()
+});
+var JobAssignmentFrameSchema = z3.object({
+  type: z3.literal("job_assignment"),
+  ...runStartBody
+});
+var DashboardDecisionFrameSchema = z3.object({
+  type: z3.literal("dashboard_decision"),
+  ...answerBody
+});
+var CancelFrameSchema = z3.object({
+  type: z3.literal("cancel"),
+  ...stopBody
+});
+var RunEventFrameSchema = z3.object({
+  type: z3.literal("run_event"),
+  ...RunStreamEventSchema.shape
+});
+var FeedEventFrameSchema = z3.object({
+  type: z3.literal("feed_event"),
+  /** Runner-local outbox order, used only for delivery retry. */
+  deliverySeq: z3.int().nonnegative(),
+  envelope: FeedEnvelopeSchema
+});
+var HelloFrameSchema = z3.object({
+  type: z3.literal("hello"),
+  protocolVersion: z3.int().positive(),
+  role: z3.enum(["runner", "hub"]).optional(),
+  instanceId: z3.string().optional(),
+  agent: z3.object({ name: z3.string(), version: z3.string().optional() }).optional(),
+  capabilities: z3.array(z3.string()).optional(),
+  workflows: z3.array(InstalledWorkflowSchema).optional()
+});
+var WorkflowsChangedFrameSchema = z3.object({
+  type: z3.literal("workflows.changed"),
+  workflows: z3.array(InstalledWorkflowSchema)
+});
+var RunStartFrameSchema = z3.object({
+  type: z3.literal("run.start"),
+  ...runStartBody
+});
+var AnswerFrameSchema = z3.object({
+  type: z3.literal("answer"),
+  ...answerBody
+});
+var StopFrameSchema = z3.object({
+  type: z3.literal("stop"),
+  ...stopBody
+});
+var SteerFrameSchema = z3.object({
+  type: z3.literal("steer"),
+  runId: z3.string(),
+  athenaSessionId: z3.string().optional(),
+  text: z3.string().min(1)
+});
+var NeedsHumanFrameSchema = z3.object({
+  type: z3.literal("needs_human"),
+  runId: z3.string(),
+  athenaSessionId: z3.string().optional(),
+  interruption: InterruptionSchema
+});
+var RunStreamEventFrameSchema = z3.object({
+  type: z3.literal("event"),
+  stream: z3.literal("run"),
+  ...RunStreamEventSchema.shape
+});
+var FeedStreamEventFrameSchema = z3.object({
+  type: z3.literal("event"),
+  stream: z3.literal("feed"),
+  deliverySeq: z3.int().nonnegative(),
+  envelope: FeedEnvelopeSchema
+});
+var EventFrameSchema = z3.discriminatedUnion("stream", [
+  RunStreamEventFrameSchema,
+  FeedStreamEventFrameSchema
+]);
+var unchangedFrames = [
+  PingFrameSchema,
+  PongFrameSchema,
+  AssignmentAcceptedFrameSchema,
+  AssignmentRejectedFrameSchema,
+  DecisionAckFrameSchema,
+  FeedAckFrameSchema,
+  AttachmentsChangedFrameSchema,
+  ErrorFrameSchema
+];
+var LegacyFrameSchema = z3.discriminatedUnion("type", [
+  JobAssignmentFrameSchema,
+  DashboardDecisionFrameSchema,
+  CancelFrameSchema,
+  RunEventFrameSchema,
+  FeedEventFrameSchema,
+  ...unchangedFrames
+]);
+var CanonicalFrameSchema = z3.discriminatedUnion("type", [
+  HelloFrameSchema,
+  RunStartFrameSchema,
+  AnswerFrameSchema,
+  StopFrameSchema,
+  SteerFrameSchema,
+  NeedsHumanFrameSchema,
+  WorkflowsChangedFrameSchema,
+  EventFrameSchema,
+  ...unchangedFrames
+]);
+var FrameSchema = z3.discriminatedUnion("type", [
+  JobAssignmentFrameSchema,
+  DashboardDecisionFrameSchema,
+  CancelFrameSchema,
+  RunEventFrameSchema,
+  FeedEventFrameSchema,
+  HelloFrameSchema,
+  RunStartFrameSchema,
+  AnswerFrameSchema,
+  StopFrameSchema,
+  SteerFrameSchema,
+  NeedsHumanFrameSchema,
+  WorkflowsChangedFrameSchema,
+  EventFrameSchema,
+  ...unchangedFrames
+]);
+function hello(input = {}) {
+  return { type: "hello", protocolVersion: PROTOCOL_VERSION, ...input };
+}
+
+// src/normalize.ts
+var FRAME_NAME_MAP = {
+  job_assignment: "run.start",
+  dashboard_decision: "answer",
+  cancel: "stop",
+  run_event: "event",
+  feed_event: "event",
+  ping: "ping",
+  pong: "pong",
+  assignment_accepted: "assignment_accepted",
+  assignment_rejected: "assignment_rejected",
+  decision_ack: "decision_ack",
+  feed_ack: "feed_ack",
+  "attachments.changed": "attachments.changed",
+  error: "error"
+};
+function normalizeFrame(input) {
+  return canonicalize(FrameSchema.parse(input));
+}
+function safeNormalizeFrame(input) {
+  const parsed = FrameSchema.safeParse(input);
+  if (!parsed.success) return { success: false, error: parsed.error };
+  return { success: true, frame: canonicalize(parsed.data) };
+}
+function canonicalize(frame) {
+  switch (frame.type) {
+    case "job_assignment": {
+      const { type: _type, ...body } = frame;
+      return { type: "run.start", ...body };
+    }
+    case "dashboard_decision": {
+      const { type: _type, ...body } = frame;
+      return { type: "answer", ...body };
+    }
+    case "cancel": {
+      const { type: _type, ...body } = frame;
+      return { type: "stop", ...body };
+    }
+    case "run_event": {
+      const { type: _type, ...body } = frame;
+      return { type: "event", stream: "run", ...body };
+    }
+    case "feed_event": {
+      const { type: _type, ...body } = frame;
+      return { type: "event", stream: "feed", ...body };
+    }
+    default:
+      return frame;
+  }
+}
+function toLegacyFrame(frame) {
+  switch (frame.type) {
+    case "run.start": {
+      const { type: _type, ...body } = frame;
+      return { type: "job_assignment", ...body };
+    }
+    case "answer": {
+      const { type: _type, ...body } = frame;
+      return { type: "dashboard_decision", ...body };
+    }
+    case "stop": {
+      const { type: _type, ...body } = frame;
+      return { type: "cancel", ...body };
+    }
+    case "event": {
+      if (frame.stream === "run") {
+        const { type: _type2, stream: _stream2, ...body2 } = frame;
+        return { type: "run_event", ...body2 };
+      }
+      const { type: _type, stream: _stream, ...body } = frame;
+      return { type: "feed_event", ...body };
+    }
+    default:
+      return frame;
+  }
+}
+
+// src/jsonSchema.ts
+import { z as z4 } from "zod";
+var JSON_SCHEMA_SOURCES = {
+  frame: FrameSchema,
+  "canonical-frame": CanonicalFrameSchema,
+  "legacy-frame": LegacyFrameSchema,
+  hello: HelloFrameSchema,
+  run: RunSchema,
+  turn: TurnSchema,
+  interruption: InterruptionSchema,
+  "installed-workflow": InstalledWorkflowSchema,
+  "run-spec": RunSpecSchema,
+  "runtime-decision": RuntimeDecisionSchema,
+  "run-stream-event": RunStreamEventSchema,
+  "feed-event": FeedEventSchema,
+  "feed-envelope": FeedEnvelopeSchema,
+  "phase-event": PhaseEventSchema,
+  "phase-feed-event": PhaseFeedEventSchema
+};
+function jsonSchemaId(name) {
+  return `https://raw.githubusercontent.com/drisplabs/cli/main/packages/protocol/schema/${name}.json`;
+}
+function buildJsonSchemas() {
+  const out = {};
+  for (const name of Object.keys(JSON_SCHEMA_SOURCES)) {
+    const generated = z4.toJSONSchema(JSON_SCHEMA_SOURCES[name], {
+      target: "draft-2020-12",
+      unrepresentable: "any"
+    });
+    out[name] = {
+      $schema: generated.$schema,
+      $id: jsonSchemaId(name),
+      title: name,
+      "x-protocol-version": PROTOCOL_VERSION,
+      ...generated
+    };
+  }
+  return out;
+}
+export {
+  AnswerFrameSchema,
+  AssignmentAcceptedFrameSchema,
+  AssignmentRejectedFrameSchema,
+  AssignmentRejectedReasonSchema,
+  AttachmentSchema,
+  AttachmentsChangedFrameSchema,
+  CancelFrameSchema,
+  CanonicalFrameSchema,
+  DashboardDecisionFrameSchema,
+  DecisionAckFrameSchema,
+  ErrorFrameSchema,
+  EventFrameSchema,
+  ExhaustedCapSchema,
+  FRAME_NAME_MAP,
+  FeedAckFrameSchema,
+  FeedEnvelopeSchema,
+  FeedEventCauseSchema,
+  FeedEventFrameSchema,
+  FeedEventLevelSchema,
+  FeedEventSchema,
+  FeedOriginSchema,
+  FeedStreamEventFrameSchema,
+  FrameSchema,
+  HardFailureCodeSchema,
+  HelloFrameSchema,
+  InstalledWorkflowSchema,
+  InstalledWorkflowSourceSchema,
+  InterruptionSchema,
+  JSON_SCHEMA_SOURCES,
+  JobAssignmentFrameSchema,
+  LegacyFrameSchema,
+  NeedsHumanFrameSchema,
+  PHASE_FEED_EVENT_KIND,
+  PROTOCOL_VERSION,
+  PhaseEventSchema,
+  PhaseFeedEventSchema,
+  PingFrameSchema,
+  PongFrameSchema,
+  RunEventFrameSchema,
+  RunSchema,
+  RunSpecSchema,
+  RunStartFrameSchema,
+  RunStatusSchema,
+  RunStreamEventFrameSchema,
+  RunStreamEventSchema,
+  RuntimeDecisionSchema,
+  RuntimeIntentSchema,
+  SteerFrameSchema,
+  StopFrameSchema,
+  TurnContinuationSchema,
+  TurnOutcomeSchema,
+  TurnSchema,
+  WorkflowsChangedFrameSchema,
+  buildJsonSchemas,
+  hello,
+  jsonSchemaId,
+  normalizeFrame,
+  safeNormalizeFrame,
+  toLegacyFrame
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@drisp/protocol",
+	"version": "0.6.0",
+	"description": "Wire contract between a drisp runner and the hub: zod schemas, inferred types, and JSON Schema for the instance-socket frames, Run, Turn, Interruption, and the event stream",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/drisplabs/cli.git",
+		"directory": "packages/protocol"
+	},
+	"homepage": "https://github.com/drisplabs/cli/tree/main/packages/protocol#readme",
+	"bugs": {
+		"url": "https://github.com/drisplabs/cli/issues"
+	},
+	"keywords": [
+		"drisp",
+		"protocol",
+		"zod",
+		"json-schema"
+	],
+	"license": "MIT",
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./schema/*.json": "./schema/*.json",
+		"./package.json": "./package.json"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"!dist/**/*.js.map",
+		"schema"
+	],
+	"scripts": {
+		"build": "tsup",
+		"typecheck": "tsc --noEmit",
+		"schema:generate": "vite-node scripts/generate-schema.ts",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"zod": "^4.3.6"
+	}
+}