@pushpalsdev/cli 1.0.18 → 1.0.20

package/runtime/sandbox/packages/protocol/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.browser.js"
+    },
+    "./react-native": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.browser.js"
+    }
+  },
+  "scripts": {
+    "build": "bun x --bun tsc && node scripts/copy-schemas.js",
+    "tsc": "bun x --bun tsc",
+    "test": "bun run ../../tests/protocol.integration.ts",
+    "typecheck": "bun x --bun tsc --noEmit"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2",
+    "json-schema-to-ts": "^3.1.0",
+    "@types/node": "^20.0.0"
+  },
+  "private": true
+}

package/runtime/sandbox/packages/protocol/scripts/copy-schemas.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { cpSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const srcSchemas = join(__dirname, "../src/schemas");
+const distSchemas = join(__dirname, "../dist/schemas");
+
+try {
+  mkdirSync(distSchemas, { recursive: true });
+  cpSync(srcSchemas, distSchemas, { recursive: true });
+  console.log("Copied schema files to dist/schemas");
+} catch (err) {
+  console.error("Failed to copy schemas:", err);
+  process.exit(1);
+}

package/runtime/sandbox/packages/protocol/src/a2a/README.md

@@ -0,0 +1,52 @@
+# A2A Protocol Adapter (Future)
+
+## Overview
+
+PushPals will provide an adapter layer to support integration with the [A2A (Agent-to-Agent) Project](https://github.com/a2aproject).
+
+This directory contains placeholders and design notes for how PushPals events and approvals will map to A2A message formats.
+
+## Mapping Strategy
+
+### EventEnvelope → A2A Message
+
+PushPals `EventEnvelope` and A2A message envelopes share similar concerns:
+
+- Versioning
+- Tracing (id, traceId)
+- Timestamps
+- Payload discrimination by type
+
+**Planned mapping:**
+
+- `EventEnvelope.id` ↔ A2A `message.id`
+- `EventEnvelope.ts` ↔ A2A `message.timestamp`
+- `EventEnvelope.type` ↔ A2A `message.type`
+- `EventEnvelope.payload` ↔ A2A `message.body` (may require re-serialization)
+
+### Approvals as Tool Results
+
+A2A supports "tools" and tool invocations with results. Approvals in PushPals map naturally:
+
+- `approval_required` event → Tool invocation awaiting result
+- `approved` / `denied` events → Tool result (success/failure)
+
+**Planned mapping:**
+
+- `approval_required.approvalId` ↔ A2A `tool.invocationId`
+- `approval_required.action` ↔ A2A `tool.name`
+- `approved.approvalId` ↔ A2A `result.invocationId` with `status: "success"`
+- `denied.approvalId` ↔ A2A `result.invocationId` with `status: "failure"`
+
+## Implementation Notes
+
+- **Not implemented yet.** No A2A dependencies or endpoints yet.
+- Adapter will be in `packages/protocol/src/a2a/adapter.ts` (future).
+- Server will accept A2A messages alongside native protocol (future).
+- Client will be able to display A2A workflows (future).
+
+## References
+
+- [A2A Project](https://github.com/a2aproject)
+- PushPals EventEnvelope: `packages/protocol/src/types.ts`
+- PushPals Event Types: `packages/protocol/src/schemas/events.schema.json`

package/runtime/sandbox/packages/protocol/src/a2a/mapping.ts

@@ -0,0 +1,55 @@
+/**
+ * A2A Protocol Adapter Placeholders
+ *
+ * This file contains placeholder interfaces for A2A integration.
+ * No implementation yet; serves as a design document and future interface.
+ */
+
+/**
+ * Represents the mapping between PushPals approval workflow
+ * and A2A tool invocation + result pattern.
+ */
+export interface A2AApprovalMapping {
+  /**
+   * PushPals approvalId ↔ A2A invocationId
+   */
+  approvalId: string;
+  invocationId: string;
+
+  /**
+   * PushPals action (git.commit, git.push, etc.) ↔ A2A tool name
+   */
+  pushpalsAction: string;
+  a2aToolName: string;
+}
+
+/**
+ * Represents the mapping between PushPals EventEnvelope
+ * and A2A message envelope.
+ */
+export interface A2AEventMapping {
+  /**
+   * PushPals msgId ↔ A2A message id
+   */
+  pushpalsMessageId: string;
+  a2aMessageId: string;
+
+  /**
+   * Event type mapping (e.g., "approval_required" → "tool_invocation")
+   */
+  pushpalsEventType: string;
+  a2aMessageType: string;
+
+  /**
+   * Whether the payload needs re-serialization to comply with A2A spec
+   */
+  requiresPayloadTransform: boolean;
+}
+
+/**
+ * Future: adapter functions will live here
+ *
+ * export function pushpalsToA2AMessage(envelope: EventEnvelope): A2AMessage { ... }
+ * export function a2aMessageToPushpals(message: A2AMessage): EventEnvelope { ... }
+ * export function createApprovalMapping(approval: ApprovalRequiredEvent, tool: A2ATool): A2AApprovalMapping { ... }
+ */

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

@@ -0,0 +1,25 @@
+export { PROTOCOL_VERSION } from "./version";
+export type {
+  Artifact,
+  EventEnvelope,
+  AnyEventEnvelope,
+  EventType,
+  EventPayload,
+  EventTypePayloadMap,
+  CreateSessionResponse,
+  MessageRequest,
+  MessageResponse,
+  ApprovalDecisionRequest,
+  ApprovalDecisionResponse,
+  CommandRequest,
+  CommandResponse,
+} from "./types";
+export {
+  validateEventEnvelope,
+  validateMessageRequest,
+  validateMessageResponse,
+  validateApprovalDecisionRequest,
+  validateApprovalDecisionResponse,
+  validateCommandRequest,
+  type ValidationResult,
+} from "./validate.browser";

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

@@ -0,0 +1,25 @@
+export { PROTOCOL_VERSION } from "./version";
+export type {
+  Artifact,
+  EventEnvelope,
+  AnyEventEnvelope,
+  EventType,
+  EventPayload,
+  EventTypePayloadMap,
+  CreateSessionResponse,
+  MessageRequest,
+  MessageResponse,
+  ApprovalDecisionRequest,
+  ApprovalDecisionResponse,
+  CommandRequest,
+  CommandResponse,
+} from "./types";
+export {
+  validateEventEnvelope,
+  validateMessageRequest,
+  validateMessageResponse,
+  validateApprovalDecisionRequest,
+  validateApprovalDecisionResponse,
+  validateCommandRequest,
+  type ValidationResult,
+} from "./validate";

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

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ApprovalsSchema",
+  "type": "object",
+  "description": "Schemas for approval workflows"
+}

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

@@ -0,0 +1,96 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "EventEnvelope",
+  "type": "object",
+  "required": ["protocolVersion", "id", "ts", "sessionId", "type", "payload"],
+  "properties": {
+    "protocolVersion": {
+      "type": "string",
+      "const": "0.1.0",
+      "description": "Protocol version must be 0.1.0"
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique event identifier (e.g., UUID)"
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp"
+    },
+    "sessionId": {
+      "type": "string",
+      "description": "Session identifier"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "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"
+      ],
+      "description": "Event type discriminator"
+    },
+    "traceId": {
+      "type": "string",
+      "description": "Optional trace ID for debugging"
+    },
+    "from": {
+      "type": "string",
+      "description": "Originator identifier (e.g. client, agent:local1, worker:lint)"
+    },
+    "to": {
+      "type": "string",
+      "description": "Destination identifier (e.g. broadcast, agent:local1, worker:queue:default)"
+    },
+    "correlationId": {
+      "type": "string",
+      "description": "Threads a whole conversation turn together"
+    },
+    "parentId": {
+      "type": "string",
+      "description": "Links tool calls/results under their parent task event"
+    },
+    "turnId": {
+      "type": "string",
+      "description": "One per user message; groups all downstream events"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Payload depends on event type"
+    }
+  },
+  "additionalProperties": false
+}