@milpa/comal 0.2.2 → 0.2.4

package/README.md

@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.2.2` or `npm install --global @milpa/comal@0.2.2`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.2.4` or `npm install --global @milpa/comal@0.2.4`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 

package/backend/contracts/remote-commands-v1.json

@@ -91,18 +91,6 @@
       "description": "Model capability support and provenance",
       "argument_pattern": "(?:refresh)?"
     },
-    {
-      "name": "permissions",
-      "arguments": "",
-      "description": "Permission mode, saved rules and recent decisions (read-only)",
-      "argument_pattern": ""
-    },
-    {
-      "name": "autonomy",
-      "arguments": "",
-      "description": "Current autonomy level (read-only)",
-      "argument_pattern": ""
-    },
     {
       "name": "plugins",
       "arguments": "[status|list]",

package/backend/contracts/remote-device-v1.json

@@ -0,0 +1,423 @@
+{
+  "protocol": "comal.remote.device.v1",
+  "description": "Contract between a Comal Remote Control (/rc) session and an M5Stack device: pairing, the two inputs a device may send, the ephemeral permission card, the session.stats projection and the reasons a device is refused. The device is a pre-check surface only: the local Comal host revalidates every answer (arm, expiry, card digest, session, device) before mutating. Owned by the Comal Node repository; the backend keeps a byte-identical copy.",
+  "pairing": {
+    "code_alphabet": "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
+    "code_length": 8,
+    "code_ttl_seconds": 600,
+    "poll_interval_seconds": 5
+  },
+  "inputs": {
+    "permission_answer": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "question_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        },
+        "card_digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "decision": {
+          "type": "string",
+          "enum": [
+            "allow_once",
+            "deny"
+          ]
+        }
+      },
+      "required": [
+        "question_id",
+        "card_digest",
+        "decision"
+      ]
+    },
+    "quick_reply": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "enum": [
+            "continúa",
+            "sí",
+            "no"
+          ]
+        }
+      },
+      "required": [
+        "text"
+      ]
+    }
+  },
+  "stats": {
+    "maxBytes": 2048,
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "provider": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "profile": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "model": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "effort": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "effort_levels": {
+              "type": "array",
+              "maxItems": 8,
+              "items": {
+                "type": "string",
+                "maxLength": 64
+              }
+            }
+          }
+        },
+        "capabilities": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tools": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "vision": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "thinking": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "cache": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "sources": {
+              "type": "object",
+              "maxProperties": 8,
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 64
+              }
+            }
+          }
+        },
+        "permissions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "default",
+                "acceptEdits",
+                "plan",
+                "auto",
+                "bypassPermissions"
+              ]
+            },
+            "device_armed": {
+              "type": "boolean"
+            },
+            "device_until": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "add_dirs": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "input_tokens": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "window": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "output_reserve": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "percent": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100
+            },
+            "compaction_window": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "soft_threshold": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "hard_threshold": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "last_compaction": {
+              "type": [
+                "object",
+                "null"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "at": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "trigger": {
+                  "type": "string",
+                  "maxLength": 64
+                },
+                "before": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "after": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "messages_active": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "messages_original": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "usage": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "last": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "input": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "output": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "cached": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "session": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "input": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "output": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "cached": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "calls": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "call_limit": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "timing": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "comal_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "reasoning_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "first_response_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "tools_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "human_wait_ms": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "work": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "objective": {
+              "type": "string",
+              "maxLength": 120
+            },
+            "done": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "total": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "current_task": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "maxLength": 120
+            },
+            "checks_passing": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "checks_failing": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "connection": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "transport": {
+              "type": "string",
+              "enum": [
+                "websocket",
+                "https-polling",
+                "disconnected"
+              ]
+            },
+            "host_online": {
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    }
+  },
+  "card": {
+    "maxBytes": 4096,
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "question_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        },
+        "card_digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "tool": {
+          "type": "string",
+          "maxLength": 64
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "bash",
+            "write",
+            "edit",
+            "summary",
+            "terminal"
+          ]
+        },
+        "lines": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "maxLength": 120
+          }
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "overwrite": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "question_id",
+        "card_digest",
+        "tool",
+        "kind",
+        "lines",
+        "truncated"
+      ]
+    }
+  },
+  "arm": {
+    "default_seconds": 1800,
+    "max_seconds": 28800
+  },
+  "refusals": [
+    "disarmed",
+    "expired",
+    "stale",
+    "terminal_only",
+    "other_device",
+    "plan_mode",
+    "confirm_always",
+    "offline"
+  ]
+}

package/backend/contracts/remote-relay-answers-v1.json

@@ -0,0 +1,209 @@
+{
+  "protocol": "comal.remote.relay.answers.v1",
+  "description": "Typed browser answers to /relay cards (remote.inputs.enqueue kind=relay). Admission in Milpa is a useful pre-check, never authority: the local Comal host claims each control, revalidates it (ledger by request_id, session and epoch, local arm, expiry, card still pending, remote.inputs.validate, live relayd read) and only then mutates with the same functions as its terminal cards. The browser never sends tokens, idempotency keys, paths or ADR text. Owned by the Comal Node repository; the backend keeps a byte-identical copy.",
+  "control_ttl_seconds": 600,
+  "step_up_seconds": 600,
+  "arm_max_seconds": 28800,
+  "actions": {
+    "plan.approve": {
+      "card": "plan",
+      "fields": [
+        "digest",
+        "projection_sha256"
+      ],
+      "text": "none",
+      "text_max": 0,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "recent_login"
+    },
+    "plan.reject": {
+      "card": "plan",
+      "fields": [
+        "digest"
+      ],
+      "text": "required",
+      "text_max": 4096,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "none"
+    },
+    "question.option": {
+      "card": "question",
+      "fields": [
+        "option_index",
+        "option_label_sha256"
+      ],
+      "text": "optional",
+      "text_max": 1024,
+      "caps": [
+        "decide",
+        "converse"
+      ],
+      "step_up": "none"
+    },
+    "question.reply": {
+      "card": "question",
+      "fields": [],
+      "text": "required",
+      "text_max": 4096,
+      "caps": [
+        "converse"
+      ],
+      "step_up": "none"
+    },
+    "question.ack": {
+      "card": "question",
+      "fields": [],
+      "text": "none",
+      "text_max": 0,
+      "caps": [
+        "converse"
+      ],
+      "step_up": "none"
+    },
+    "criteria.accept": {
+      "card": "criteria",
+      "fields": [
+        "digest"
+      ],
+      "text": "none",
+      "text_max": 0,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "recent_login"
+    },
+    "criteria.reject": {
+      "card": "criteria",
+      "fields": [
+        "digest"
+      ],
+      "text": "required",
+      "text_max": 4096,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "none"
+    }
+  },
+  "outcomes": {
+    "applied": [
+      "approved",
+      "rejected",
+      "decided",
+      "answered",
+      "acked"
+    ],
+    "stale": [
+      "already_decided",
+      "stale",
+      "card_gone",
+      "epoch",
+      "digest",
+      "projection",
+      "option",
+      "not_pending",
+      "kind"
+    ],
+    "refused": [
+      "local_arm_off",
+      "local_in_progress",
+      "revoked",
+      "relay_unavailable",
+      "delegation",
+      "cap_missing",
+      "host_legacy",
+      "invalid",
+      "host_error"
+    ],
+    "expired": [
+      "expired"
+    ]
+  },
+  "terminal_only": [
+    "task.resume",
+    "review.override",
+    "review.retry",
+    "relay.trust",
+    "project.create",
+    "project.start",
+    "project.stop",
+    "project.attach",
+    "swarm.start",
+    "budget"
+  ],
+  "control": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "enum": [
+          "plan.approve",
+          "plan.reject",
+          "question.option",
+          "question.reply",
+          "question.ack",
+          "criteria.accept",
+          "criteria.reject"
+        ]
+      },
+      "card_id": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{32}$"
+      },
+      "card_seq": {
+        "type": "string",
+        "pattern": "^[1-9][0-9]{0,8}$"
+      },
+      "host_epoch": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{32}$"
+      },
+      "project": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,59}$"
+      },
+      "swarm": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
+      },
+      "subject": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,199}$"
+      },
+      "digest": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "projection_sha256": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "option_index": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 3
+      },
+      "option_label_sha256": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "text": {
+        "type": "string",
+        "maxLength": 4096
+      }
+    },
+    "required": [
+      "action",
+      "card_id",
+      "card_seq",
+      "host_epoch",
+      "project",
+      "swarm",
+      "subject"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,
@@ -19,10 +19,13 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "backend/verifier/transport.mjs",
     "backend/contracts/artifact-check-v1.schema.json",
     "backend/contracts/remote-commands-v1.json",
+    "backend/contracts/remote-relay-answers-v1.json",
     "backend/contracts/remote-workspace-v1.schema.json",
+    "backend/contracts/remote-device-v1.json",
     "governance/source-task-v1.json",
     "governance/source-task-v2.json",
     "governance/chrome-task-v1.json",