@pushpalsdev/cli 1.0.18 → 1.0.19

package/runtime/sandbox/configs/backend.toml

@@ -0,0 +1,79 @@
+default_backend = "miniswe"
+
+[env]
+shared_passthrough = [
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "ALL_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "all_proxy",
+  "PUSHPALS_GIT_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "GIT_TOKEN",
+  "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
+  "OPENAI_API_BASE",
+  "OPENAI_ORG_ID",
+  "OPENAI_PROJECT",
+  "PUSHPALS_REPO_PATH",
+  "WORKERPALS_DEBUG",
+]
+
+[backends.openhands]
+script_segments = ["backends", "openhands", "openhands_executor.py"]
+python_config_key = "openhandsPython"
+timeout_config_key = "openhandsTimeoutMs"
+passthrough_env = [
+  "WORKERPALS_OPENHANDS_PROMPT_PROFILE",
+  "WORKERPALS_OPENHANDS_AGENT_MAX_STEPS",
+  "WORKERPALS_OPENHANDS_WORKSPACE_PYTHON",
+  "WORKERPALS_OPENHANDS_LLM_NUM_RETRIES",
+  "WORKERPALS_OPENHANDS_LLM_RETRY_MULTIPLIER",
+  "WORKERPALS_OPENHANDS_LLM_RETRY_MIN_WAIT",
+  "WORKERPALS_OPENHANDS_LLM_RETRY_MAX_WAIT",
+  "WORKERPALS_OPENHANDS_LLM_TIMEOUT_SEC",
+  "WORKERPALS_OPENHANDS_LLM_MAX_MESSAGE_CHARS",
+  "WORKERPALS_OPENHANDS_LLM_TIMEOUT_RECOVERY_ATTEMPTS",
+  "WORKERPALS_OPENHANDS_LLM_TIMEOUT_RECOVERY_BACKOFF_SEC",
+  "WORKERPALS_OPENHANDS_TASK_PROMPT_MODE",
+  "WORKERPALS_OPENHANDS_LARGE_INSTRUCTION_CHARS",
+  "WORKERPALS_OPENHANDS_ENABLE_BROWSER_TOOL",
+  "WORKERPALS_OPENHANDS_ENABLE_WEB_MCP",
+  "WORKERPALS_OPENHANDS_MCP_CONFIG_JSON",
+  "WORKERPALS_OPENHANDS_WEB_MCP_URL",
+  "WORKERPALS_OPENHANDS_WEB_MCP_NAME",
+  "WORKERPALS_OPENHANDS_WEB_MCP_TRANSPORT",
+  "WORKERPALS_OPENHANDS_WEB_MCP_AUTH_TOKEN",
+  "WORKERPALS_OPENHANDS_WEB_MCP_HEADERS_JSON",
+  "WORKERPALS_OPENHANDS_WEB_MCP_TIMEOUT_SEC",
+]
+
+[backends.miniswe]
+script_segments = ["backends", "miniswe", "miniswe_executor.py"]
+python_config_key = "miniswePython"
+timeout_config_key = "minisweTimeoutMs"
+passthrough_env = [
+  "WORKERPALS_MINISWE_AGENT_MAX_STEPS",
+  "WORKERPALS_MINISWE_TOOLCALL_RETRY_MAX",
+  "WORKERPALS_MINISWE_TOOL_BROKER",
+  "WORKERPALS_MINISWE_TOOL_BROKER_MAX_STEPS",
+  "WORKERPALS_MINISWE_TOOL_BROKER_MAX_ACTIONS_PER_STEP",
+  "WORKERPALS_MINISWE_TOOL_BROKER_SHELL_TIMEOUT_SEC",
+]
+
+[backends.openai_codex]
+script_segments = ["backends", "openai_codex", "openai_codex_executor.py"]
+python_config_key = "openaiCodexPython"
+timeout_config_key = "openaiCodexTimeoutMs"
+passthrough_env = [
+  "PUSHPALS_OPENAI_CODEX_BIN",
+  "PUSHPALS_OPENAI_CODEX_BIN_JSON",
+  "PUSHPALS_OPENAI_CODEX_AUTH_MODE",
+  "PUSHPALS_OPENAI_CODEX_BASE_URL",
+  "PUSHPALS_OPENAI_CODEX_HOST_CODEX_HOME",
+  "PUSHPALS_OPENAI_CODEX_CONTAINER_CODEX_HOME",
+]

package/runtime/sandbox/configs/default.toml

@@ -0,0 +1,260 @@
+profile = "dev"
+session_id = "dev"
+
+[llm.lmstudio]
+context_window = 4096
+min_output_tokens = 256
+token_safety_margin = 64
+batch_tail_messages = 3
+batch_chunk_tokens = 0
+batch_memory_chars = 0
+
+[paths]
+data_dir = "outputs/data"
+shared_db_path = "outputs/data/pushpals.db"
+remotebuddy_db_path = "outputs/data/remotebuddy-state.db"
+
+[server]
+url = "http://127.0.0.1:3001"
+host = "127.0.0.1"
+port = 3001
+debug_http = false
+stale_claim_ttl_ms = 120000
+stale_claim_sweep_interval_ms = 5000
+
+[localbuddy]
+enabled = false
+port = 3003
+status_heartbeat_ms = 120000
+
+[localbuddy.llm]
+backend = "lmstudio"
+endpoint = "http://127.0.0.1:1234"
+model = "local-model"
+session_id = "localbuddy-dev"
+
+[remotebuddy]
+poll_ms = 2000
+status_heartbeat_ms = 120000
+workerpal_online_ttl_ms = 15000
+wait_for_workerpal_ms = 15000
+auto_spawn_workerpals = true
+max_workerpals = 10
+workerpal_startup_timeout_ms = 10000
+workerpal_docker = true
+workerpal_require_docker = true
+workerpal_image = ""
+workerpal_poll_ms = 0
+workerpal_heartbeat_ms = 0
+workerpal_labels = []
+execution_budget_interactive_ms = 600000
+execution_budget_normal_ms = 1500000
+execution_budget_background_ms = 1800000
+finalization_budget_ms = 120000
+crash_restart_enabled = true
+crash_restart_max_restarts = 3
+crash_restart_backoff_ms = 3000
+
+[remotebuddy.memory]
+enabled = true
+include_cross_session = true
+max_recall_items = 12
+max_recall_chars = 2400
+max_summary_chars = 420
+retention_days = 30
+
+[remotebuddy.llm]
+backend = "lmstudio"
+endpoint = "http://127.0.0.1:1234"
+model = "local-model"
+session_id = "remotebuddy-dev"
+
+[remotebuddy.autonomy]
+enabled = true
+kill_switch_enabled = false
+tick_interval_ms = 300000
+heartbeat_log_ms = 30000
+vision_context_max_chars = 65536
+ideation_budget_ms = 20000
+llm_timeout_ms = 60000
+allow_dirty_worktree = false
+ideation_max_candidates = 20
+top_k = 3
+explore_rate = 0.3
+min_confidence = 0.65
+max_concurrent_objectives = 2
+max_dispatch_per_hour = 6
+max_dispatch_per_hour_by_type = { flaky_test = 4, lint_fix = 3, type_fix = 3, small_refactor = 2, feature_small = 2, feature_medium = 1, feature_large = 0, docs = 1, dep_bump = 0 }
+max_dispatch_per_hour_by_component = { "apps/server" = 3, "apps/remotebuddy" = 2, "apps/workerpals" = 2, "apps/client" = 2, "packages/protocol" = 1, "packages/shared" = 2, "tests/integration" = 2, "tests/unit" = 2 }
+max_token_usage_per_hour = 120000
+max_runtime_ms_per_hour = 5400000
+cooldown_fail_streak_threshold = 2
+cooldown_ms = 1800000
+stale_objective_ttl_ms = 2700000
+stale_objective_sweep_interval_ms = 60000
+auto_freeze_fail_streak_threshold = 3
+auto_freeze_duration_ms = 1800000
+evaluator_window_hours = 24
+evaluator_min_samples = 6
+evaluator_min_success_rate = 0.45
+evaluator_max_regret_rate = 0.35
+evaluator_run_interval_ms = 120000
+alert_queue_pending_threshold = 20
+alert_job_failure_rate_threshold = 0.3
+alert_autonomy_failure_rate_threshold = 0.45
+allow_read_anywhere = true
+pr_feedback_comment_rows = 16
+pr_feedback_comment_chars = 600
+pr_feedback_summary_chars = 600
+question_ttl_ms = 259200000
+policy_version = "policy-v3.3"
+impact_model_version = "impact-v1"
+
+[remotebuddy.autonomy.replay]
+store_prompt_payloads = false
+max_runs_with_payloads = 50
+max_payload_bytes = 262144
+
+[workerpals]
+poll_ms = 2000
+heartbeat_ms = 5000
+executor = "miniswe"
+openhands_python = "python"
+openhands_timeout_ms = 1800000
+miniswe_python = "python"
+miniswe_timeout_ms = 1800000
+openai_codex_python = "python"
+openai_codex_timeout_ms = 7200000
+openhands_stuck_guard_enabled = true
+openhands_stuck_guard_explore_limit = 18
+openhands_stuck_guard_min_elapsed_ms = 180000
+openhands_stuck_guard_broad_scan_limit = 2
+openhands_stuck_guard_no_progress_max_ms = 300000
+require_push = false
+push_agent_branch = false
+require_docker = false
+skip_docker_self_check = false
+docker_image = "pushpals-worker-sandbox:latest"
+docker_timeout_ms = 7260000
+docker_idle_timeout_ms = 600000
+docker_agent_startup_timeout_ms = 45000
+docker_warm_max_attempts = 3
+docker_warm_retry_backoff_ms = 2000
+docker_job_max_attempts = 2
+docker_job_retry_backoff_ms = 3000
+docker_warm_memory_mb = 2048
+docker_warm_cpus = 2
+file_modifying_jobs = ["task.execute"]
+output_max_chars = 196608
+output_max_lines = 600
+output_max_head_lines = 120
+quality_max_auto_revisions = 1
+quality_validation_step_timeout_ms = 180000
+quality_critic_timeout_ms = 45000
+quality_soft_pass_on_exhausted = true
+quality_critic_min_score = 8.0
+quality_critic_max_diff_chars = 16000
+quality_critic_max_validation_output_chars = 8000
+executor_result_prefix = "__PUSHPALS_OH_RESULT__ "
+docker_network_mode = "bridge"
+base_ref = "origin/main_agents"
+labels = []
+failure_cooldown_ms = 20000
+
+[workerpals.openhands]
+workspace_python = "python3"
+agent_server_url = ""
+prompt_profile = "auto"
+task_prompt_mode = "none"
+large_instruction_chars = 1800
+enable_web_mcp = false
+web_mcp_url = ""
+web_mcp_name = "web-search"
+web_mcp_transport = "streamable-http"
+web_mcp_timeout_sec = 0
+enable_browser_tool = false
+lmstudio_slot_id = -1
+llm_num_retries = 2
+llm_retry_multiplier = 1.5
+llm_retry_min_wait = 1
+llm_retry_max_wait = 4
+llm_timeout_sec = 240
+llm_max_message_chars = 8000
+llm_timeout_recovery_attempts = 2
+llm_timeout_recovery_backoff_sec = 5
+agent_max_steps = 30
+auto_steer_enabled = true
+auto_steer_initial_delay_sec = 90
+auto_steer_interval_sec = 60
+auto_steer_max_nudges = 30
+
+[workerpals.llm]
+backend = "lmstudio"
+endpoint = "http://127.0.0.1:1234"
+model = "local-model"
+session_id = "workerpals-dev"
+
+[workerpals.openai_codex]
+timeout_ms = 7200000
+progress_log_interval_s = 30
+reasoning_effort = "high"
+approval_policy = "never"
+sandbox = "workspace-write"
+color = "never"
+json = true
+
+[source_control_manager]
+repo_path = ".worktrees/source_control_manager"
+remote = "origin"
+pushpals_branch = "main_agents"
+base_branch = "main"
+branch_prefix = "agent/"
+poll_interval_seconds = 10
+checks = []
+state_dir = "outputs/data/source_control_manager"
+port = 3002
+delete_after_merge = false
+max_attempts = 3
+merge_strategy = "cherry-pick"
+push_main_after_merge = true
+open_pr_after_push = true
+pr_base_branch = "main"
+pr_title = ""
+pr_body = ""
+pr_draft = false
+status_heartbeat_ms = 120000
+skip_clean_check = false
+auto_create_main_branch = false
+
+[source_control_manager.review_agent]
+enabled = false
+poll_interval_ms = 60000
+reviewer_md_path = "prompts/review_agent/reviewer.md"
+pass_threshold = 9.5
+max_pr_comments_before_give_up = 10
+merge_method = "squash"
+codex_auth_mode = "chatgpt"
+codex_bin = "bun x --yes @openai/codex"
+codex_home_dir = ""
+codex_timeout_ms = 300000
+
+[startup]
+worker_image_rebuild = "auto"
+log_config_on_start = true
+sync_integration_with_main = true
+skip_llm_preflight = false
+auto_start_lmstudio = true
+lmstudio_ready_timeout_ms = 120000
+lmstudio_cli = "lms"
+lmstudio_port = 1234
+lmstudio_start_args = ""
+startup_warmup = true
+startup_warmup_timeout_ms = 120000
+startup_warmup_poll_ms = 1000
+allow_external_clean = false
+port_preflight = true
+port_conflict_policy = "terminate_pushpals"
+
+[client]
+local_agent_url = "http://127.0.0.1:3003"
+trace_tail_lines = 100

package/runtime/sandbox/configs/dev.toml

@@ -0,0 +1,2 @@
+[source_control_manager]
+skip_clean_check = true

package/runtime/sandbox/configs/local.example.toml

@@ -0,0 +1,129 @@
+# Copy this file to configs/local.toml for machine-specific, non-secret overrides.
+# Keep secrets in .env (or CI secret store), not in TOML.
+
+# Uncomment to enable LocalBuddy when using `bun run start`.
+# The `bun run start` supervisor applies `localbuddy.enabled` changes live.
+# [localbuddy]
+# enabled = true
+
+[localbuddy.llm]
+backend = "openai_codex"
+model = "gpt-5-codex"
+codex_auth_mode = "chatgpt"
+codex_bin = "bun x --yes @openai/codex"
+codex_timeout_ms = 120000
+reasoning_effort = "high"
+
+[remotebuddy.llm]
+backend = "openai_codex"
+model = "gpt-5-codex"
+codex_auth_mode = "chatgpt"
+codex_bin = "bun x --yes @openai/codex"
+codex_timeout_ms = 120000
+reasoning_effort = "high"
+
+[remotebuddy]
+max_workerpals = 10
+crash_restart_enabled = true
+crash_restart_max_restarts = 3
+crash_restart_backoff_ms = 3000
+
+[remotebuddy.autonomy]
+llm_timeout_ms = 60000
+allow_dirty_worktree = false
+
+[remotebuddy.memory]
+enabled = true
+include_cross_session = true
+max_recall_items = 12
+max_recall_chars = 2400
+max_summary_chars = 420
+retention_days = 30
+
+[workerpals.llm]
+backend = "openai_codex"
+model = "gpt-5-codex"
+codex_auth_mode = "chatgpt"
+codex_bin = "bun x --yes @openai/codex"
+codex_timeout_ms = 120000
+reasoning_effort = "high"
+
+[workerpals]
+executor = "openai_codex"
+docker_image = "pushpals-worker-sandbox:latest"
+openhands_timeout_ms = 1800000
+openai_codex_timeout_ms = 7200000
+docker_timeout_ms = 7260000
+openhands_stuck_guard_enabled = true
+openhands_stuck_guard_explore_limit = 18
+openhands_stuck_guard_min_elapsed_ms = 180000
+openhands_stuck_guard_broad_scan_limit = 2
+openhands_stuck_guard_no_progress_max_ms = 300000
+docker_warm_memory_mb = 2048
+docker_warm_cpus = 2
+file_modifying_jobs = ["task.execute"]
+output_max_chars = 196608
+output_max_lines = 600
+output_max_head_lines = 120
+quality_max_auto_revisions = 1
+quality_validation_step_timeout_ms = 180000
+quality_critic_timeout_ms = 45000
+quality_soft_pass_on_exhausted = true
+quality_critic_min_score = 8.0
+quality_critic_max_diff_chars = 16000
+quality_critic_max_validation_output_chars = 8000
+executor_result_prefix = "__PUSHPALS_OH_RESULT__ "
+
+[workerpals.openhands]
+prompt_profile = "minimal"
+llm_timeout_sec = 180
+llm_max_message_chars = 12000
+llm_timeout_recovery_attempts = 2
+llm_timeout_recovery_backoff_sec = 5
+agent_max_steps = 30
+auto_steer_enabled = true
+auto_steer_initial_delay_sec = 90
+auto_steer_interval_sec = 60
+auto_steer_max_nudges = 30
+
+[workerpals.openai_codex]
+auth_mode = "chatgpt"
+bin = "bun x --yes @openai/codex"
+timeout_ms = 7200000
+progress_log_interval_s = 30
+# timeout_s = 120  # optional; if set, overrides timeout_ms
+reasoning_effort = "high"
+approval_policy = "never"
+sandbox = "workspace-write"
+color = "never"
+json = true
+
+[llm.lmstudio]
+context_window = 4096
+min_output_tokens = 256
+batch_tail_messages = 3
+
+[source_control_manager]
+repo_path = ".worktrees/source_control_manager"
+pushpals_branch = "main_agents"
+base_branch = "main"
+checks = []
+
+[source_control_manager.review_agent]
+enabled = true
+poll_interval_ms = 60000
+reviewer_md_path = "prompts/review_agent/reviewer.md"
+pass_threshold = 8.1
+max_pr_comments_before_give_up = 10
+merge_method = "squash"
+codex_auth_mode = "chatgpt"
+codex_bin = "bun x --yes @openai/codex"
+codex_home_dir = ""
+codex_timeout_ms = 300000
+
+[startup]
+log_config_on_start = true
+startup_warmup = true
+lmstudio_ready_timeout_ms = 120000
+port_preflight = true
+port_conflict_policy = "terminate_pushpals"  # fail|terminate_pushpals

package/runtime/sandbox/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pushpals",
+  "private": true,
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "cli": "bun run scripts/pushpals-cli.ts",
+    "cli:integration": "bun run scripts/cli-integration.ts",
+    "cli:bundle": "bun run --cwd packages/cli build",
+    "cli:monitor:export": "bun run scripts/sync-cli-monitor-ui.ts",
+    "protocol:build": "bun --cwd packages/protocol build",
+    "protocol:typecheck": "bun --cwd packages/protocol typecheck",
+    "server:only": "bun --cwd apps/server --env-file ../../.env dev",
+    "client:only": "bun run scripts/start-client.ts",
+    "client:only:offline": "bun run scripts/start-client.ts --offline",
+    "web:only": "bun --cwd apps/client web",
+    "ios:only": "bun --cwd apps/client ios",
+    "android:only": "bun --cwd apps/client android",
+    "localbuddy:only": "bun --cwd apps/localbuddy --env-file ../../.env dev",
+    "workerpals:only": "bun --cwd apps/workerpals --env-file ../../.env start",
+    "workerpals:only:watch": "bun --cwd apps/workerpals --env-file ../../.env dev",
+    "workerpals:only:docker": "bun --cwd apps/workerpals --env-file ../../.env start -- --docker --require-docker",
+    "workerpals:only:docker:watch": "bun --cwd apps/workerpals --env-file ../../.env dev -- --docker --require-docker",
+    "source_control_manager:only": "bun --cwd apps/source_control_manager --env-file ../../.env start",
+    "source_control_manager:only:dev": "bun --cwd apps/source_control_manager --env-file ../../.env start -- --skip-clean-check",
+    "remotebuddy:only": "bun --cwd apps/remotebuddy --env-file ../../.env start",
+    "remotebuddy:only:watch": "bun --cwd apps/remotebuddy --env-file ../../.env dev",
+    "server": "bun run protocol:build && bun run server:only",
+    "client": "bun run protocol:build && bun run client:only",
+    "web": "bun run protocol:build && bun run web:only",
+    "ios": "bun run protocol:build && bun run ios:only",
+    "android": "bun run protocol:build && bun run android:only",
+    "localbuddy": "bun run protocol:build && bun run localbuddy:only",
+    "workerpals": "bun run protocol:build && bun run workerpals:only",
+    "source_control_manager": "bun run protocol:build && bun run source_control_manager:only",
+    "remotebuddy": "bun run protocol:build && bun run remotebuddy:only",
+    "dev": "bun run protocol:build && concurrently -p \"[{time}][{name}]\" -t \"HH:mm:ss\" -n server,client -c blue,green \"bun run server:only\" \"bun run client:only\"",
+    "dev:full": "bun run protocol:build && concurrently -p \"[{time}][{name}]\" -t \"HH:mm:ss\" -n server,localbuddy,remotebuddy,workerpals,source_control_manager,client -c blue,magenta,red,yellow,cyan,green \"bun run server:only\" \"bun run localbuddy:only\" \"bun run remotebuddy:only\" \"bun run workerpals:only:docker\" \"bun run source_control_manager:only:dev\" \"bun run client:only:offline\"",
+    "start": "bun run scripts/start.ts",
+    "lint": "bun --cwd apps/client lint",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test:prompt-policy": "bun test tests/prompt-policy.enforcement.test.ts",
+    "test:cli:integration": "bun test tests/cli.invocation-logging.test.ts tests/cli.runtime-bootstrap.test.ts tests/client.runtime-bootstrap.test.ts tests/shared.client-preflight.test.ts",
+    "test:root": "bun test tests",
+    "test:protocol": "bun run tests/protocol.integration.ts",
+    "test:integration": "python -u tests/integration/integration_controller.py --mode integration",
+    "test:integration:eval": "python -u tests/integration/integration_controller.py --mode eval",
+    "test": "bun run test:prompt-policy && bun run test:root && bun run test:protocol",
+    "smoke": "bun run scripts/smoke-test.ts",
+    "vscode:client:compile": "bun run --cwd apps/vscode-client compile",
+    "vscode:client:lint": "bun run --cwd apps/vscode-client lint",
+    "vscode:client:test": "bun run --cwd apps/vscode-client test",
+    "vscode:client:package": "bun run --cwd apps/vscode-client package"
+  },
+  "bin": {
+    "pushpals": "./scripts/pushpals-cli.ts"
+  },
+  "devDependencies": {
+    "concurrently": "^9.2.1",
+    "prettier": "^3.8.1"
+  }
+}

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

@@ -0,0 +1,168 @@
+# PushPals Protocol (v0.1.0)
+
+A shared, versioned protocol package for PushPals event streaming over both SSE (web) and WebSocket (mobile/desktop).
+
+## Overview
+
+The protocol defines:
+
+- **JSON Schemas** for all events and HTTP contracts
+- **TypeScript types** generated from/validated against schemas
+- **Runtime validators** (AJV-based) for both server and client
+- **A2A adapter scaffolding** for future Agent-to-Agent integration
+
+## Files
+
+- `src/version.ts` - Protocol version constant (0.1.0)
+- `src/types.ts` - TypeScript type definitions
+- `src/validate.ts` - Runtime validators (Ajv)
+- `src/index.ts` - Public API
+- `src/schemas/` - JSON Schema definitions
+  - `envelope.schema.json` - Base event envelope structure
+  - `events.schema.json` - Event type discriminator + payloads
+  - `http.schema.json` - HTTP request/response contracts
+  - `approvals.schema.json` - Approval workflow schemas
+- `src/a2a/` - A2A adapter scaffolding (future)
+  - `README.md` - Architecture notes
+  - `mapping.ts` - Placeholder interfaces
+
+## Event Types
+
+All events conform to `EventEnvelope`:
+
+```typescript
+{
+  protocolVersion: "0.1.0",
+  id: string,              // UUID or other unique ID
+  ts: string,              // ISO-8601 timestamp
+  sessionId: string,       // Session identifier
+  type: EventType,         // Discriminator
+  traceId?: string,        // Optional for debugging
+  payload: Record<string, unknown>
+}
+```
+
+### Supported Types
+
+- `log` - Debug/info/warn/error logging
+- `scan_result` - Repository scan results
+- `suggestions` - List of actionable suggestions
+- `diff_ready` - Diff and stat information
+- `approval_required` - Awaiting human approval
+- `approved` / `denied` - Approval decisions
+- `committed` - Git commit result
+- `error` - Error event
+- `done` - Workflow completed
+
+## Usage
+
+### In Server (apps/server)
+
+```typescript
+import { EventEnvelope, validateEventEnvelope, PROTOCOL_VERSION } from "protocol";
+
+const envelope: EventEnvelope = {
+  protocolVersion: PROTOCOL_VERSION,
+  id: randomUUID(),
+  ts: new Date().toISOString(),
+  sessionId: "...",
+  type: "log",
+  payload: { level: "info", message: "Hello" },
+};
+
+const validation = validateEventEnvelope(envelope);
+if (validation.ok) {
+  // Send via SSE or WebSocket
+}
+```
+
+### In Client (apps/client)
+
+```typescript
+import { subscribeEvents } from "./lib/pushpalsApi";
+
+subscribeEvents("http://localhost:3001", sessionId, (event) => {
+  if (event.type === "_error") {
+    console.error(event.message);
+    return;
+  }
+
+  console.log(`Event: ${event.type}`, event.payload);
+});
+```
+
+## HTTP Contracts
+
+### POST /sessions
+
+**Response:**
+
+```json
+{ "sessionId": "uuid", "protocolVersion": "0.1.0" }
+```
+
+### POST /sessions/:id/message
+
+**Request:**
+
+```json
+{ "text": "user input" }
+```
+
+**Response:**
+
+```json
+{ "ok": true }
+```
+
+### POST /approvals/:approvalId
+
+**Request:**
+
+```json
+{ "decision": "approve" | "deny" }
+```
+
+**Response:**
+
+```json
+{ "ok": true }
+```
+
+### GET /sessions/:id/events (SSE)
+
+Content-Type: `text/event-stream`
+
+```
+event: message
+data: <JSON EventEnvelope>
+```
+
+### GET /sessions/:id/ws (WebSocket)
+
+Sends EventEnvelope as JSON messages.
+
+## Validation
+
+All validators are compiled at module load time for performance:
+
+```typescript
+import {
+  validateEventEnvelope,
+  validateMessageRequest,
+  validateApprovalDecisionRequest,
+} from "protocol";
+
+const result = validateEventEnvelope(data);
+if (!result.ok) {
+  console.error("Validation errors:", result.errors);
+}
+```
+
+## Notes
+
+- Protocol version is pinned to **0.1.0** across all envelopes
+- Event IDs should be UUIDs for traceability
+- All times are ISO-8601 UTC
+- The protocol is immutable; changes require a version bump
+- A2A integration is future work; see `src/a2a/README.md`