@pushpalsdev/cli 1.0.18 → 1.0.20

package/runtime/sandbox/packages/protocol/src/schemas/http.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "HTTPContracts",
+  "definitions": {
+    "CreateSessionResponse": {
+      "type": "object",
+      "required": ["sessionId", "protocolVersion"],
+      "properties": {
+        "sessionId": { "type": "string" },
+        "protocolVersion": { "type": "string", "const": "0.1.0" }
+      },
+      "additionalProperties": false
+    },
+    "MessageRequest": {
+      "type": "object",
+      "required": ["text"],
+      "properties": {
+        "text": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "MessageResponse": {
+      "type": "object",
+      "required": ["ok"],
+      "properties": {
+        "ok": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "ApprovalDecisionRequest": {
+      "type": "object",
+      "required": ["decision"],
+      "properties": {
+        "decision": {
+          "type": "string",
+          "enum": ["approve", "deny"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "ApprovalDecisionResponse": {
+      "type": "object",
+      "required": ["ok"],
+      "properties": {
+        "ok": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/runtime/sandbox/packages/protocol/src/types.ts

@@ -0,0 +1,267 @@
+import { PROTOCOL_VERSION } from "./version";
+
+// ─── Artifact type (reused across several payloads) ─────────────────────────
+export interface Artifact {
+  kind: string;
+  uri?: string;
+  text?: string;
+}
+
+/**
+ * Payload types for each event type - enables type narrowing
+ */
+export interface EventTypePayloadMap {
+  // ── Existing events ───────────────────────────────────────────────────────
+  log: { level: "debug" | "info" | "warn" | "error"; message: string };
+  scan_result: {
+    summary: string;
+    filesRead: string[];
+    gitStatusPorcelain: string;
+    gitDiff: string;
+  };
+  suggestions: {
+    items: Array<{ id: string; title: string; detail: string; effort: "S" | "M" | "L" }>;
+  };
+  diff_ready: { unifiedDiff: string; diffStat: string; branch: string };
+  approval_required: {
+    approvalId: string;
+    action: "git.commit" | "git.push" | "other";
+    summary: string;
+    details: Record<string, unknown>;
+  };
+  approved: { approvalId: string };
+  denied: { approvalId: string };
+  committed: { branch: string; commitHash: string; message: string };
+  assistant_message: { text: string };
+  error: { message: string; detail?: string };
+  done: { ok: boolean };
+
+  // ── Multi-agent events ────────────────────────────────────────────────────
+  agent_status: {
+    agentId: string;
+    status: "idle" | "busy" | "error";
+    message?: string;
+  };
+
+  // ── Task lifecycle events ─────────────────────────────────────────────────
+  task_created: {
+    taskId: string;
+    title: string;
+    description: string;
+    createdBy: string;
+    priority?: string;
+    tags?: string[];
+  };
+  task_started: { taskId: string };
+  task_progress: { taskId: string; message: string; percent?: number };
+  task_completed: {
+    taskId: string;
+    summary: string;
+    artifacts?: Artifact[];
+  };
+  task_failed: { taskId: string; message: string; detail?: string };
+
+  // ── Tool call/result events ───────────────────────────────────────────────
+  tool_call: {
+    toolCallId: string;
+    taskId?: string;
+    tool: string;
+    args: Record<string, unknown>;
+    requiresApproval?: boolean;
+  };
+  tool_result: {
+    toolCallId: string;
+    taskId?: string;
+    ok: boolean;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    artifacts?: Artifact[];
+  };
+
+  // ── Delegation events ─────────────────────────────────────────────────────
+  delegate_request: {
+    requestId: string;
+    toAgentId: string;
+    input: Record<string, unknown>;
+  };
+  delegate_response: {
+    requestId: string;
+    ok: boolean;
+    output?: Record<string, unknown>;
+    error?: string;
+  };
+
+  // ── Job queue events ──────────────────────────────────────────────────────
+  job_enqueued: {
+    jobId: string;
+    taskId: string;
+    kind: string;
+    params: Record<string, unknown>;
+    origin?: "user" | "autonomy";
+    autonomy?: {
+      objectiveId?: string;
+      runId?: string;
+      snapshotId?: string;
+      patternKey?: string;
+    };
+  };
+  job_claimed: { jobId: string; workerId: string };
+  job_completed: {
+    jobId: string;
+    summary?: string;
+    artifacts?: Artifact[];
+  };
+  job_failed: { jobId: string; message: string; detail?: string };
+  // ── Streaming / lifecycle events ──────────────────────────────────────
+  /** User-facing chat message (from client to server) */
+  message: { text: string; intent?: Record<string, unknown> };
+
+  /** Streaming log line from a worker executing a job */
+  job_log: {
+    jobId: string;
+    stream: "stdout" | "stderr";
+    seq: number;
+    line: string;
+    ts?: string;
+  };
+
+  /** System heartbeat / status beacon */
+  status: {
+    agentId: string;
+    state: "idle" | "busy" | "error" | "shutting_down";
+    uptimeMs?: number;
+    detail?: string;
+  };
+
+  // —— Autonomous system lifecycle events ————————————————————————————————————————————
+  autonomy_cycle_started: {
+    runId: string;
+    snapshotId: string;
+    phase?: string;
+  };
+  autonomy_candidates_generated: {
+    runId: string;
+    snapshotId: string;
+    candidateCount: number;
+    topCandidateIds?: string[];
+  };
+  autonomy_objective_dispatched: {
+    runId: string;
+    snapshotId: string;
+    objectiveId: string;
+    requestId: string;
+    patternKey: string;
+    origin?: "autonomy";
+  };
+  autonomy_objective_blocked: {
+    runId: string;
+    snapshotId: string;
+    objectiveId: string;
+    reason: string;
+    questionId?: string;
+    patternKey?: string;
+    origin?: "autonomy";
+  };
+  autonomy_feedback_recorded: {
+    objectiveId: string;
+    patternKey: string;
+    outcome: string;
+    success: boolean;
+  };
+  question_asked: {
+    questionId: string;
+    objectiveId: string;
+    question: string;
+    questionType: string;
+  };
+  question_answered: {
+    questionId: string;
+    objectiveId: string;
+    status: "valid" | "invalid";
+    answerSummary?: string;
+  };
+}
+
+/**
+ * Discriminated union of all event payload types
+ */
+export type EventPayload = EventTypePayloadMap[keyof EventTypePayloadMap];
+
+export type EventType = keyof EventTypePayloadMap;
+
+/**
+ * EventEnvelope parameterized by event type for type-safe access to payload
+ *
+ * Routing / meta fields (all optional):
+ * - from:          originator identifier (e.g. "client", "agent:local1")
+ * - to:            destination identifier (e.g. "broadcast", "worker:queue:default")
+ * - correlationId: threads a whole conversation turn together
+ * - parentId:      links tool calls/results under their parent task event
+ * - turnId:        one per user message; groups all downstream events
+ */
+export interface EventEnvelope<T extends EventType = EventType> {
+  protocolVersion: typeof PROTOCOL_VERSION;
+  id: string;
+  ts: string; // ISO-8601
+  sessionId: string;
+  type: T;
+  traceId?: string;
+
+  // Routing / meta
+  from?: string;
+  to?: string;
+  correlationId?: string;
+  parentId?: string;
+  turnId?: string;
+
+  payload: EventTypePayloadMap[T];
+}
+
+/**
+ * Any EventEnvelope - for cases where type is not known at compile time
+ */
+export type AnyEventEnvelope = EventEnvelope<EventType>;
+
+/**
+ * HTTP Request/Response types
+ */
+export interface CreateSessionResponse {
+  sessionId: string;
+  protocolVersion: typeof PROTOCOL_VERSION;
+}
+
+export interface MessageRequest {
+  text: string;
+  intent?: Record<string, unknown>;
+}
+
+export interface MessageResponse {
+  ok: boolean;
+}
+
+export interface ApprovalDecisionRequest {
+  decision: "approve" | "deny";
+}
+
+export interface ApprovalDecisionResponse {
+  ok: boolean;
+}
+
+/**
+ * Command request (agent-friendly ingest)
+ */
+export interface CommandRequest {
+  type: EventType;
+  payload: Record<string, unknown>;
+  from?: string;
+  to?: string;
+  correlationId?: string;
+  turnId?: string;
+  parentId?: string;
+}
+
+export interface CommandResponse {
+  ok: boolean;
+  eventId?: string;
+}

package/runtime/sandbox/packages/protocol/src/validate.browser.ts

@@ -0,0 +1,154 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import envelopeSchema from "./schemas/envelope.schema.json";
+import eventsSchema from "./schemas/events.schema.json";
+
+const ajv = new Ajv({ strict: true });
+addFormats(ajv);
+
+// Register schemas to help $ref linking when present
+try {
+  ajv.addSchema(envelopeSchema as object, "envelope.schema.json");
+  ajv.addSchema(eventsSchema as object, "events.schema.json");
+} catch (_e) {
+  // ignore addSchema failures; we'll still compile below
+}
+
+const validateEnvelopeBase = ajv.compile(envelopeSchema as unknown as object);
+const validateEventPayload = ajv.compile(eventsSchema as unknown as object);
+
+const validateMessageRequestSchema = ajv.compile({
+  type: "object",
+  required: ["text"],
+  properties: { text: { type: "string" }, intent: { type: "object", additionalProperties: true } },
+  additionalProperties: false,
+});
+
+const validateMessageResponseSchema = ajv.compile({
+  type: "object",
+  required: ["ok"],
+  properties: { ok: { type: "boolean" } },
+  additionalProperties: false,
+});
+
+const validateApprovalDecisionRequestSchema = ajv.compile({
+  type: "object",
+  required: ["decision"],
+  properties: { decision: { type: "string", enum: ["approve", "deny"] } },
+  additionalProperties: false,
+});
+
+const validateApprovalDecisionResponseSchema = ajv.compile({
+  type: "object",
+  required: ["ok"],
+  properties: { ok: { type: "boolean" } },
+  additionalProperties: false,
+});
+
+export interface ValidationResult {
+  ok: boolean;
+  errors?: string[];
+}
+
+export function validateEventEnvelope(data: unknown): ValidationResult {
+  const baseValid = validateEnvelopeBase(data);
+  if (!baseValid) {
+    const errors = (validateEnvelopeBase.errors ?? []).map((e) =>
+      `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+    );
+    return { ok: false, errors };
+  }
+
+  // Validate only the `{ type, payload }` pairing against the events schema.
+  const maybe = data as any;
+  const pair = { type: maybe?.type, payload: maybe?.payload };
+
+  const payloadValid = validateEventPayload(pair);
+  if (!payloadValid) {
+    const errors = (validateEventPayload.errors ?? []).map((e) =>
+      `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+    );
+    return { ok: false, errors };
+  }
+
+  return { ok: true };
+}
+
+export function validateMessageRequest(data: unknown): ValidationResult {
+  const valid = validateMessageRequestSchema(data);
+  const errors = valid
+    ? undefined
+    : (validateMessageRequestSchema.errors ?? []).map((e) =>
+        `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+      );
+  return { ok: valid, errors };
+}
+
+export function validateMessageResponse(data: unknown): ValidationResult {
+  const valid = validateMessageResponseSchema(data);
+  const errors = valid
+    ? undefined
+    : (validateMessageResponseSchema.errors ?? []).map((e) =>
+        `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+      );
+  return { ok: valid, errors };
+}
+
+export function validateCommandRequest(data: unknown): ValidationResult {
+  const allEventTypes = [
+    "log",
+    "scan_result",
+    "suggestions",
+    "diff_ready",
+    "approval_required",
+    "approved",
+    "denied",
+    "committed",
+    "assistant_message",
+    "error",
+    "done",
+    "agent_status",
+    "task_created",
+    "task_started",
+    "task_progress",
+    "task_completed",
+    "task_failed",
+    "tool_call",
+    "tool_result",
+    "delegate_request",
+    "delegate_response",
+    "job_enqueued",
+    "job_claimed",
+    "job_completed",
+    "job_failed",
+    "message",
+    "job_log",
+    "status",
+  ];
+  const d = data as any;
+  if (!d || typeof d !== "object") return { ok: false, errors: ["Expected object"] };
+  if (!d.type || !allEventTypes.includes(d.type)) return { ok: false, errors: ["Invalid type"] };
+  if (!d.payload || typeof d.payload !== "object")
+    return { ok: false, errors: ["Invalid payload"] };
+  return { ok: true };
+}
+
+export function validateApprovalDecisionRequest(data: unknown): ValidationResult {
+  const valid = validateApprovalDecisionRequestSchema(data);
+  const errors = valid
+    ? undefined
+    : (validateApprovalDecisionRequestSchema.errors ?? []).map((e) =>
+        `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+      );
+  return { ok: valid, errors };
+}
+
+export function validateApprovalDecisionResponse(data: unknown): ValidationResult {
+  const valid = validateApprovalDecisionResponseSchema(data);
+  const errors = valid
+    ? undefined
+    : (validateApprovalDecisionResponseSchema.errors ?? []).map((e) =>
+        `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+      );
+  return { ok: valid, errors };
+}

package/runtime/sandbox/packages/protocol/src/validate.ts

@@ -0,0 +1,233 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ajv = new Ajv({ strict: true });
+
+// Add format validators for date-time, etc.
+addFormats(ajv);
+
+/**
+ * Expected runtime layout (after `npm run build` / `bun --cwd packages/protocol build`):
+ *
+ * packages/protocol/dist/index.js
+ * packages/protocol/dist/validate.js
+ * packages/protocol/dist/schemas/*.json
+ *
+ * The loader below prefers `dist/schemas` when running compiled JS and falls
+ * back to `../src/schemas` during development. The `scripts/copy-schemas.js`
+ * build step copies `src/schemas` into `dist/schemas` to satisfy runtime loads.
+ */
+
+/**
+ * Load schema from file. Deterministic order:
+ * 1. Built/runtime: `dist/schemas` (when running compiled JS)
+ * 2. Development: `src/schemas` (when running from source)
+ */
+function loadSchema(filename: string): Record<string, unknown> {
+  const distSchemasPath = join(__dirname, "schemas", filename); // dist/schemas when compiled
+  const srcSchemasPath = join(__dirname, "..", "src", "schemas", filename); // src/schemas during development
+  const envSchemasDir = String(process.env.PUSHPALS_PROTOCOL_SCHEMAS_DIR ?? "").trim();
+  const envSchemasPath = envSchemasDir ? join(envSchemasDir, filename) : "";
+  const candidates = [distSchemasPath, srcSchemasPath, envSchemasPath].filter(Boolean);
+
+  for (const pathValue of candidates) {
+    try {
+      return JSON.parse(readFileSync(pathValue, "utf-8"));
+    } catch {
+      // try next path
+    }
+  }
+
+  throw new Error(
+    `Failed to load schema ${filename}. Expected at dist/schemas (build), src/schemas (dev), or PUSHPALS_PROTOCOL_SCHEMAS_DIR.`,
+  );
+}
+
+// Load schemas
+const envelopeSchema = loadSchema("envelope.schema.json");
+const eventsSchema = loadSchema("events.schema.json");
+
+// Register schemas with AJV (helps with $ref resolution across files)
+try {
+  ajv.addSchema(envelopeSchema as object, "envelope.schema.json");
+  ajv.addSchema(eventsSchema as object, "events.schema.json");
+} catch (_e) {
+  // addSchema may throw in strict modes for malformed schemas; compilation below
+  // will still attempt to compile standalone validators.
+}
+
+// Compile validators
+const validateEnvelopeBase = ajv.compile(envelopeSchema as object);
+const validateEventPayload = ajv.compile(eventsSchema as object);
+const validateMessageRequestSchema = ajv.compile({
+  type: "object",
+  required: ["text"],
+  properties: {
+    text: { type: "string" },
+    intent: { type: "object", additionalProperties: true },
+  },
+  additionalProperties: false,
+});
+const validateMessageResponseSchema = ajv.compile({
+  type: "object",
+  required: ["ok"],
+  properties: {
+    ok: { type: "boolean" },
+  },
+  additionalProperties: false,
+});
+const validateApprovalDecisionRequestSchema = ajv.compile({
+  type: "object",
+  required: ["decision"],
+  properties: {
+    decision: {
+      type: "string",
+      enum: ["approve", "deny"],
+    },
+  },
+  additionalProperties: false,
+});
+const validateApprovalDecisionResponseSchema = ajv.compile({
+  type: "object",
+  required: ["ok"],
+  properties: {
+    ok: { type: "boolean" },
+  },
+  additionalProperties: false,
+});
+
+export interface ValidationResult {
+  ok: boolean;
+  errors?: string[];
+}
+
+/**
+ * Validate an EventEnvelope against the full schema
+ */
+export function validateEventEnvelope(data: unknown): ValidationResult {
+  const baseValid = validateEnvelopeBase(data);
+  if (!baseValid) {
+    const errors = (validateEnvelopeBase.errors ?? []).map((e) =>
+      `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+    );
+    return { ok: false, errors };
+  }
+
+  // Validate only the `{ type, payload }` pairing against the events schema.
+  // This ensures branch validation focuses on the event discriminant and
+  // its payload shape, while envelope-level fields are handled above.
+  const maybe = data as any;
+  const pair = { type: maybe?.type, payload: maybe?.payload };
+
+  const payloadValid = validateEventPayload(pair);
+  if (!payloadValid) {
+    const errors = (validateEventPayload.errors ?? []).map((e) =>
+      `${e.instancePath || "/"} ${e.message ?? ""}`.trim(),
+    );
+    return { ok: false, errors };
+  }
+
+  return { ok: true };
+}
+
+export function validateMessageRequest(data: unknown): ValidationResult {
+  const valid = validateMessageRequestSchema(data);
+  return {
+    ok: valid,
+    errors: valid ? undefined : ajv.errorsText(validateMessageRequestSchema.errors).split(", "),
+  };
+}
+
+export function validateMessageResponse(data: unknown): ValidationResult {
+  const valid = validateMessageResponseSchema(data);
+  return {
+    ok: valid,
+    errors: valid ? undefined : ajv.errorsText(validateMessageResponseSchema.errors).split(", "),
+  };
+}
+
+export function validateApprovalDecisionRequest(data: unknown): ValidationResult {
+  const valid = validateApprovalDecisionRequestSchema(data);
+  return {
+    ok: valid,
+    errors: valid
+      ? undefined
+      : ajv.errorsText(validateApprovalDecisionRequestSchema.errors).split(", "),
+  };
+}
+
+export function validateApprovalDecisionResponse(data: unknown): ValidationResult {
+  const valid = validateApprovalDecisionResponseSchema(data);
+  return {
+    ok: valid,
+    errors: valid
+      ? undefined
+      : ajv.errorsText(validateApprovalDecisionResponseSchema.errors).split(", "),
+  };
+}
+
+// Command request schema (agent-friendly ingest)
+const allEventTypes = [
+  "log",
+  "scan_result",
+  "suggestions",
+  "diff_ready",
+  "approval_required",
+  "approved",
+  "denied",
+  "committed",
+  "assistant_message",
+  "error",
+  "done",
+  "agent_status",
+  "task_created",
+  "task_started",
+  "task_progress",
+  "task_completed",
+  "task_failed",
+  "tool_call",
+  "tool_result",
+  "delegate_request",
+  "delegate_response",
+  "job_enqueued",
+  "job_claimed",
+  "job_completed",
+  "job_failed",
+  "message",
+  "job_log",
+  "status",
+  "autonomy_cycle_started",
+  "autonomy_candidates_generated",
+  "autonomy_objective_dispatched",
+  "autonomy_objective_blocked",
+  "autonomy_feedback_recorded",
+  "question_asked",
+  "question_answered",
+];
+
+const validateCommandRequestSchema = ajv.compile({
+  type: "object",
+  required: ["type", "payload"],
+  properties: {
+    type: { type: "string", enum: allEventTypes },
+    payload: { type: "object", additionalProperties: true },
+    from: { type: "string" },
+    to: { type: "string" },
+    correlationId: { type: "string" },
+    turnId: { type: "string" },
+    parentId: { type: "string" },
+  },
+  additionalProperties: false,
+});
+
+export function validateCommandRequest(data: unknown): ValidationResult {
+  const valid = validateCommandRequestSchema(data);
+  return {
+    ok: valid,
+    errors: valid ? undefined : ajv.errorsText(validateCommandRequestSchema.errors).split(", "),
+  };
+}

package/runtime/sandbox/packages/protocol/src/version.ts

@@ -0,0 +1 @@
+export const PROTOCOL_VERSION = "0.1.0";