Skip to content

v0.4.0-alpha.0

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 26 Oct 13:27
· 41 commits to main since this release
b56a7e9

Added

  • melra setup --client claude-code --exclusive takes Claude Code's own tools that change anything or reach the network away in its settings, for every session in the workspace: with --write it merges a bare deny rule for each of a list pinned to Claude Code's tools reference (Bash, PowerShell, Monitor, Edit, Write, NotebookEdit, WebFetch, WebSearch and eight more) into the workspace's .claude/settings.local.json as a union, keeping every rule there, editing in place and saving the old file as .bak, and sets MELRA_HARNESS_TOOLS=1 in the .mcp.json entry; a settings file that is not strict JSON, which Claude Code would not load, is refused. --managed <dir> instead stages a managed-settings.json (the same list, plus allowManagedPermissionRulesOnly, allowManagedHooksOnly and permissions.disableBypassPermissionsMode) and a managed-mcp.json listing only melra, by absolute path, in <dir>, and prints the sudo install lines (on Windows, the destination) that put them where Claude Code reads managed settings, with each staged file's SHA-256. MELRA never writes that folder or runs sudo; it refuses an npx melra or a melra or node inside the home folder, a --managed folder inside Claude Code's (in any letter case on macOS), and a staged file that differs. --dry-run prints the .mcp.json and settings files as they would be written and writes nothing, not even the default policy. Other clients are refused. See Claude Code's settings.
  • melra doctor has a harness line, and its JSON a harness object, wherever Claude Code is in play: it reads the managed files at their platform path, the project's settings files and the user's, and reports each pinned tool as removed or present, each managed file's owner, mode and writability by this user, the lock keys set or missing, the servers managed-mcp.json lists and the executable its melra entry runs, admin-group membership and each file's SHA-256. It reads them as strict JSON, as Claude Code does. While claude.ai settings holding a policy rank above the managed files, it counts that policy's rules and locks in their place and names that file; under managedSourcesBehavior: "merge" it counts them together with the managed files without naming it. While an MDM profile it cannot read ranks above them on macOS, without merge, it counts no rule from any file and says so. It warns in either mode and never fails, and reports observations only.
  • melra probe [--json], run inside an agent's box before the agent starts, reports whether the box stops what it should. It creates and removes a file in the workspace, opens the database and key in MELRA_HOME (set to the server's, as the box sees it) without reading them, makes a TCP connection to a public address (--public, default 1.1.1.1:443) and to another local port (--local, default one it listens on itself), and starts the shell, and reports each as confined or open. Only a refusal counts as confined; what it could not try is open, not tested. It then checks that the MELRA running outside the box answers on --socket (or MELRA_SOCKET) or a loopback --url, asking without a token; with none of the three it refuses to run (probe_endpoint_missing). It exits 0 only when every check is confined and MELRA answers. It sends nothing over its connections, changes no setting, and proves only the checks on its list. See checking an agent's box.
  • examples/deploy/compose/compose.yaml runs MELRA and the agent in two containers, so the agent's only way to change the workspace or reach the network is MELRA's socket. MELRA serves --socket in enforced mode with the workspace read-write and its data in a volume of its own, on a volume that holds only the socket, with no port published. The agent gets the workspace read-only, no MELRA data, no credential but the token MELRA's socket asks for, and an internal network with no route out and, in gateway mode isolated (Docker Engine 28.0 or later), no address on the host, and runs as MELRA's user so the mode-0600 socket admits it. Both run with a read-only root, no capabilities, no-new-privileges, and caps on processes and memory (pids_limit, mem_limit). From a checkout, docker compose -f examples/deploy/compose/compose.yaml up starts it with a stand-in agent that runs melra probe. pnpm compose:smoke, run in CI on Linux, checks it from the agent's side: the probe must find the workspace write, MELRA's database and key, and connections out and to the host refused, both aimed at a port on the runner so nothing leaves it, and a file write through the socket with the TypeScript SDK, approved with melra approve in MELRA's container, must reach verified_success with a receipt. The docker run -i stdio recipe is now described as what it is: it boxes MELRA, not the agent, and is a developer-mode recipe. See MELRA and the agent in two containers.
  • An operator's deny says why: melra approve <task-id> --deny takes --reason wrong_target|too_broad|not_now|never|other (other when left out) and --note <text>, and the console's Deny takes a reason from a list and an optional note. The note holds up to 1,000 characters, is stored redacted and is never read by MELRA. Each deny is recorded once per challenge in a new approval_denials table with the approver, the channel (out_of_band from an enforced process), the time, the render digest and a keyed digest of the operation, and the task it cancels gains denial (reason, note, channel, approver, decidedAt), which melra_task_status returns. A task its agent cancelled with melra_task_cancel has no denial, so the two no longer leave the same record. Nothing acts on a denial yet.
  • Answers MELRA refuses for coming from the agent's side where only an operator answers, or for not matching what they answer, are now recorded (#424): approval_in_band_refused (from melra_execute, melra_workflow_advance and the approve harness tool), judgement_in_band_refused, workflow_input_in_band_refused, approval_action_digest_mismatch, approval_render_mismatch, approval_phrase_mismatch and approval_id_mismatch. A new refusals table keeps the task or run, the code, the mode, the sender's declared principal and the client its transport authenticated, if any, and the time, and nothing that was sent. It keeps one row per task or run and code, the first, so sending the same answer again adds nothing. A refused verdict is recorded after the transaction it was refused in is rolled back. An approval sent with melra workflow advance --approval or a verdict sent with melra judge is not recorded, such as melra judge without --mode enforced on an enforced task; a decision melra approve or the console records that does not match is recorded under the approver's name. melra tasks and melra status show how many are recorded and the latest five (refusals in their JSON, in melra tasks --json only when there are any), melra watch reports each new one, and melra tasks marks with ! a task whose agent sent an approval or verdict only an operator gives; a run's show in the latest five.
  • approval_denials and refusals arrive in migration 8 and are append-only, as migration 7's tables are (record_append_only). Only this version writes them, so an older MELRA sharing the home keeps writing as it did.
  • pnpm benchmark:aarm runs a self-check of MELRA against the 21 AARM v1.0 minimum tests (17 MUST, 4 SHOULD) through the real runtime, with no model and no network beyond loopback, in a few seconds. The cases are MELRA's own, as data in evals/src/aarm/corpus.ts; which cases map to which test, our paraphrase of each test and the sources (a hash of the aarm.dev table, never its text) are pre-registered in evals/manifests/aarm-v1.0-minimum-tests-v1.json, whose SHA-256 the harness pins and checks before it runs. A case needing an interface MELRA lacks (defer, modify, a record verifier, signed receipts, an audit export, sessions, labels), or whose steps are not written yet, is reported not_implemented, never run. It writes an artifact only with --output <file>. It is a self-run mapping, not AARM conformance. See docs/research/AARM_SELFCHECK.md.
  • wildcardMatch(value, pattern) in @melra/receipt-schema: the one * pattern match capability grants, credential delegations and url_matches share, in time linear in its input.

Changed

  • A task policy denies at planning now gets a POLICY_BLOCKED certificate, as one denied at execute already did, and its certificateId names it (#424).
  • Breaking: The console's deny route takes only { "reason", "note" }, both optional, where it ignored its body; any other body is refused with nothing recorded.
  • Breaking: melra workflow advance --approval now sends as the operator and checks MELRA_APPROVER as --input does, so a name it does not accept is refused before the run moves.
  • Breaking: the MELRA kernel is now licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only) instead of Apache-2.0, and XAGI Labs Private Limited also offers it under a commercial license. That covers @melra/cli, @melra/server and every other package except the SDKs: @melra/sdk, @melra/protocol and the melra Python package stay Apache-2.0, as do examples/ and the code samples in the documentation, so code that only calls MELRA is unaffected. Releases up to and including 0.3.0-alpha.22 were Apache-2.0 and stay so. Contributions now need the Contributor License Agreement as well as a DCO sign-off, and the MELRA name and logo are covered by TRADEMARKS.md. The official logo and hero artwork are now all rights reserved instead of CC BY-ND 4.0; copies already distributed under it keep that license. Each published package now ships its own LICENSE, and the release archive, container image and single executables carry LICENSE and NOTICE. LICENSING.md maps each path to its license.

Security

  • An agent's attempt, in enforced mode, to approve its own change, answer its own semantic question or answer a question meant for an operator is now recorded where the operator looks, not only refused. Each such record is bounded, so repeating an attempt cannot grow the store.
  • Matching URL and host patterns and redacting secrets, in text and in a command's arguments, now take time linear in their input, so a crafted value cannot stall MELRA. Grants, credential delegations and url_matches answer as before, and redaction takes out the same text.