@jc_stack/ez-agents 0.1.0-beta.32 → 0.1.0-beta.33

package/AGENTS.md

@@ -73,6 +73,35 @@ can be stated briefly and deferred. Reviewers distinguish those blockers from
 optional follow-ups and do not hold a working increment for hypothetical polish.
 Measure progress by usable outcomes and feedback, not code or test volume.
 
+## Feasibility frame for non-trivial work
+
+Before implementing a non-trivial coding, architecture or product change, state
+the user-visible objective, no more than five task-relevant binding constraints,
+the component that owns the failed boundary, the subtraction or simplification
+option, the minimum evidence needed to prove the outcome, and the stop condition.
+Do not restate the full prompt or add this ceremony to minor mechanical edits.
+
+A result that violates a binding constraint is invalid even when tests pass or
+the immediate symptom disappears. Check behavioral correctness, architecture and
+ownership, real user-path evidence and authorized side effects separately. Before
+completion, inspect whether the change added a runner, wrapper, state owner, queue,
+retry loop, prompt layer, dependency or configuration format; retain it only when
+the existing owner or contract cannot solve the demonstrated problem. Use one
+bounded constraint review, then stop when sufficient evidence passes unless a
+concrete material risk remains.
+
+Frame that review as answers to these questions, not as an open-ended request to
+find flaws:
+
+1. Did the solution cross an architecture, ownership or authority boundary?
+2. Did it bypass a binding constraint or preserve the symptom through a workaround?
+3. Did it add machinery where deletion or a simpler existing contract would work?
+4. Does the evidence prove the real user-visible outcome rather than only a proxy?
+5. Is there one concrete unresolved risk severe enough to block completion?
+
+If no answer identifies a material blocker, finish. Do not start another review
+round merely to seek more criticism, tests or hypothetical edge cases.
+
 ## 3. Crash-Safe Atomic Disk State
 - All persistent stores (`ControlStore`, `RunStore`, outbox queue) must be disk-backed JSON files.
 - **Atomic write pattern:** Never write directly to a state file. Always write to a temporary file (`${target}.${process.pid}.tmp`) with mode `0o600`, then atomically `rename` it over the destination.
@@ -97,37 +126,23 @@ Measure progress by usable outcomes and feedback, not code or test volume.
 - Unapproved group messages from other senders and unknown DMs fail silently unless an exact-contact or any-conversation owner-approved channel grant admits them. Both grant types use the restricted task runner. Paired-owner group text is discovery routed to the owner's private chat; it grants no group reply authority.
 - Stopping work (`/stop`) must terminate the active worker PID immediately (`SIGTERM`, escalating to `SIGKILL` if unclosed after 3s).
 
-## 8. Mandatory Adversarial & Negative Tests
-Every pull request modifying authority, execution, or routing must include negative tests:
-1. Unapproved Telegram ID $\rightarrow$ no process spawned.
-2. Non-owner group message $\rightarrow$ silent ignore; owner group discovery $\rightarrow$ private destination only.
-3. Executor environment check $\rightarrow$ asserts `TELEGRAM_BOT_TOKEN` is `undefined`.
-4. Corrupt JSON in store $\rightarrow$ handled gracefully without process crash.
-5. Injected path traversal in IDs $\rightarrow$ rejected.
+## 8. Risk-based negative validation
+
+Changes to authority, execution, routing, secret isolation or durable state must
+validate the affected failure boundary, not rerun or recreate an unrelated fixed
+checklist. Examples include proving that an unapproved sender spawns no process,
+executor secrets remain absent, invalid IDs cannot traverse paths, ambiguous
+external writes are not retried, and corrupt state fails safely. Add or change a
+test only when it protects the changed contract or a demonstrated regression.
+Existing relevant checks plus focused real-path evidence may be sufficient.
 
 ## Public contribution workflow
 
-Read CONTRIBUTING.md before edits and docs/releasing.md before a release.
-Maintainers and external agents use the same PR, tests and documentation standard.
-Keep internal plans and private evidence outside this repository.
-
-Before edits, follow CONTRIBUTING.md's isolated-work rules: one task per dedicated
-worktree/branch/PR, starting from fetched origin/main. Do not switch or mix work in
-another task's checkout. Stage only this task's changes. Keep its worktree through
-review and QA; independent review and green CI precede an authorized merge.
-Never treat task completion as permission to merge or publish.
-Own the complete engineering/release handoff in CONTRIBUTING.md. Once ready,
-proactively request only missing merge/release authority, then ship and verify;
-do not leave the maintainer to discover ready drafts or operate the release.
-
-For every core or plugin PR you author, revise or review, apply CONTRIBUTING.md's
-architecture check and the README's engine/application boundary. A symptom fix
-and green tests do not justify a conflicting execution or context owner. Existing
-legacy channel-backend code is a documented limitation, not a pattern for new
-integrations; applications submit agent turns through the native Ez execution path.
-
-A coding-task handoff must include the pushed commit and draft PR URL, checks,
-independent-review status and remaining QA. If PR creation is blocked, state the
-blocker and preserved commit. The merging agent owns the post-merge worktree
-cleanup check and reports removal or the specific reason to retain it. Follow
-CONTRIBUTING.md for squash-merge evidence, ignored files and active-use checks.
+Read CONTRIBUTING.md before edits and docs/releasing.md before a release. It owns
+the worktree, PR, review, merge, release and cleanup process; do not duplicate that
+process here or in feature documentation. For every core or plugin change, apply
+its architecture check and the README's engine/application boundary. A symptom
+fix and green tests do not justify a conflicting execution or context owner.
+Existing legacy channel-backend code is a documented limitation, not a pattern
+for new integrations. Keep internal plans and private evidence outside this
+repository.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.0-beta.33
+
+- Allow compatible plugin updates to add commands to existing services, registering
+  their aliases atomically while retaining collision checks and rejecting changes
+  to existing command routes or deployment authority.
+- Simplify contribution guidance and bound independent constraint reviews without
+  changing the native engine, transport or plugin responsibility boundaries.
+
 ## 0.1.0-beta.32
 
 - Add shared authenticated inbound attachment staging for application and

package/CONTRIBUTING.md

@@ -16,9 +16,11 @@ repository. Public docs describe shipped behavior and explicit limitations.
    Packaging/runtime changes also need the Docker checks in docs/releasing.md.
 5. Open a PR explaining the problem, resulting behavior, verification and limits.
    Include a short sanitized reproduction. State which tests were not run.
-6. Obtain independent review and required CI, then complete the
-   maintainer-authorized merge. Maintainers use PRs too. No CLA, ticket
-   requirement, custom commit format or additional approval committee.
+6. Obtain one bounded independent final-head review and required CI, resolve
+   material findings, then complete the authorized merge. An owner or maintainer
+   request for a product change or fix authorizes this normal PR/merge loop;
+   unsolicited external contributions still require maintainer merge authority.
+   No CLA, ticket requirement, custom commit format or additional approval committee.
 
 You are responsible for understanding submitted code, including AI-generated
 code, and having the right to contribute it under this repository's license.
@@ -79,10 +81,10 @@ do not disguise them as supported architecture or start a duplicate repair.
   create one worktree/PR per repository and link dependencies and merge order.
   Branch from an unmerged feature only when the dependency is intentional and
   documented; do not quietly include it in an unrelated PR.
-- Push the task branch and open a draft PR as soon as the first coherent change
-  is reviewable, before reporting implementation complete. Do not leave completed
-  work only in a local branch. Continue through the release handoff below;
-  implementation completion alone does not authorize publication.
+- Push the task branch and open a PR when the coherent change is reviewable. Use
+  draft status only while implementation or a named gate remains incomplete; do
+  not leave completed mergeable work in a draft or only on a local branch.
+  Publication remains a separate authority boundary.
 - Every handoff names the repository, worktree, branch, exact commit, PR URL,
   checks, independent-review status and remaining QA with its next action. If
   pushing or PR creation is blocked, report the blocker and preserved local
@@ -98,9 +100,10 @@ do not disguise them as supported architecture or start a duplicate repair.
 - New substantive commits or conflict resolutions invalidate the affected review
   and test evidence. Refresh against current main, review the resulting diff and
   run the applicable checks. Do not bypass protected-branch requirements.
-- Merge only after review, required CI, applicable QA and maintainer authorization.
-  Publish only under the separate release process; commits and merges are not
-  releases. Record which source commit and artifact hash were tested.
+- Merge only after review, required CI and applicable QA under the authority in
+  the contribution checklist above. Publish only under the separate release
+  process; commits and merges are not releases. Record which source commit and
+  artifact hash were tested.
 - Keep the worktree while its PR or QA is open. After merge or explicit abandonment,
   inspect it for uncommitted/untracked files and local-only commits. Remove only
   the clean task worktree after valuable work is preserved; never force cleanup.
@@ -124,22 +127,22 @@ and prepare the release. Reuse valid final-commit evidence; repeat checks when
 changes or failures invalidate it. Do not leave a ready feature silently in draft
 or ask the maintainer to run commands, coordinate reviewers, or operate CI.
 
-The maintainer's request is authorization for the requested work and its normal
-implementation steps. Do not ask them to approve the same work again. Once the
-applicable gates pass, execute the requested merge/release and report the packages,
-versions, channel, verification and material limits. Batch related packages in
-dependency order. Prepare the reviewed commits, artifacts and checksums before
-shipping. A request to merge does not silently expand to publication or changing
-a private package's visibility; a request to release already authorizes release.
-If shipping was not requested, report readiness and the next step without treating
-every completed feature as permission to publish.
-
-Complete the authorized merge, publication and rollout using
-docs/releasing.md, then verify registry metadata, downloaded artifact and the
-installed runtime. Report the outcome. Escalate only a product decision, missing
-credential/2FA, failed gate that cannot be repaired in scope, or material scope
-change. Human attention belongs on product intent;
-the agent operates the technical workflow.
+The owner or maintainer request authorizes the requested work and its normal
+PR/merge steps; do not ask them to approve the same work again. Release remains
+separate authority: a request to merge does not authorize publication or changing
+a private package's visibility, while a request to release authorizes the merge
+and publication needed for that release. Prepare and verify the reviewed commits,
+artifacts and checksums before shipping. If release was not requested, stop after
+the merged contribution loop and report any distinct deployment or publication
+step without performing it.
+
+When release is authorized, complete publication using docs/releasing.md, then
+verify registry metadata, the downloaded artifact and any explicitly requested
+installed-runtime QA. Deployment is separate and requires a direct rollout
+request or the target's saved update policy. Report the outcome. Escalate only a
+product decision, missing credential/2FA, failed gate that cannot be repaired in
+scope, or material scope change. Human attention belongs on product intent; the
+agent operates the technical workflow.
 
 Example, substituting a unique task name and an absolute external directory:
 

package/docs/plugin-contributions.md

@@ -28,7 +28,10 @@ Before the first PR, provide:
 
 Copy CONTRIBUTING.md, SECURITY.md structure, PR template and docs/releasing.md
 from a released Ez repository; adapt commands and security facts to your plugin.
-Do not copy private QA, company policy, proposed features or unsupported claims.
+Add a short AGENTS.md that states the plugin's ownership boundary and applies the
+same compact feasibility frame and risk-based validation policy; do not copy
+core-only Telegram, state or dependency invariants. Do not copy private QA,
+company policy, proposed features or unsupported claims.
 Public instructions must work without the maintainer's parent workspace. Use
 reviewed local source and its inspected content hash; registry installation is
 inert. Installation is complete only after account onboarding and verified use.

package/docs/upgrades.md

@@ -174,10 +174,12 @@ No backup deletes live data or revokes credentials. Retain old package roots and
 images until QA and any recovery window are complete; there is no automatic GC.
 
 The updater accepts only matching state-schema and protocol contracts and an
-unchanged deployment layout. Changes to privileges, services, volumes or Compose
-configuration fail before replacement, even for an explicit candidate. These
-need a separately reviewed migration, not an override flag. Release authors must
-truthfully declare schema compatibility. Code rollback **does not rewind private
+unchanged deployment layout. Plugins may add command routes to existing services;
+existing routes and all services, privileges, volumes and other deployment
+configuration must remain unchanged. Incompatible changes fail before replacement,
+even for an explicit candidate, and need a separately reviewed migration rather
+than an override flag. Release authors must truthfully declare schema compatibility.
+Code rollback **does not rewind private
 state**, provider cursors or operation receipts; uncertain actions are never
 replayed. Docker health is not proof of live provider identity or delivery.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.32",
+  "version": "0.1.0-beta.33",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/src/updates/control.mjs

@@ -44,6 +44,14 @@ export async function check(home) {
   }
   return results;
 }
+const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])])):value;
+const same=(left,right)=>JSON.stringify(canonical(left))===JSON.stringify(canonical(right));
+function additiveCommands(previous,next) {
+  const before={...previous,commands:{}},after={...next,commands:{}};
+  if(!same(before,after))return false;
+  for(const [name,command] of Object.entries(previous.commands||{}))if(!same(next.commands?.[name],command))return false;
+  return Object.values(next.commands||{}).every(command=>next.services?.[command.service]);
+}
 export async function eligibility(home,target,root,automatic) {
   const old=await installed(home,target),pkg=await read(path.join(root,'package.json')),kind=target==='main'?'main':'plugin';
   if(pkg.name!==old.pkg.name)throw Error('Package identity mismatch');
@@ -54,7 +62,9 @@ export async function eligibility(home,target,root,automatic) {
   if(kind==='plugin') {
     const s=await snapshot(root);revision=s.revision;
     if(s.manifest.id!==target||s.manifest.version!==pkg.version)throw Error('Plugin identity/version mismatch');
-    if(JSON.stringify(s.deployment)!==JSON.stringify(old.record.deployment))throw Error('Deployment permissions/layout changed; a separately reviewed migration is required');
+    if(!additiveCommands(old.record.deployment,s.deployment))throw Error('Deployment permissions/layout changed; a separately reviewed migration is required');
+    const registry=await read(path.join(home,'registry.json'));
+    for(const alias of Object.keys(s.manifest.commands))if(registry.commands[alias]&&registry.commands[alias]!==target)throw Error('CLI alias collision');
   }else {
     for(const file of ['compose.yaml','compose.whatsapp.yaml'])if(!Buffer.from(await fs.readFile(path.join(root,file))).equals(await fs.readFile(path.join(old.root,file))))throw Error('Runtime deployment changed; a separately reviewed migration is required');
   }

package/src/updates/runtime.mjs

@@ -122,7 +122,9 @@ export async function perform(home,job,hooks) {
       for(const name of volumes)await backupVolume(run,old,name,backup);
       await atomic(old.compose,await compose(config,candidate,secrets,home));
       if(running)await run('docker',[...pluginArgs(candidate),'up','-d','--wait','--wait-timeout','90','--no-build']);
-      r.plugins[job.target]=candidate;await atomic(path.join(home,'registry.json'),r);
+      r.plugins[job.target]=candidate;
+      for(const alias of Object.keys(candidate.manifest.commands))r.commands[alias]=job.target;
+      await atomic(path.join(home,'registry.json'),r);
       job.runtimeVerified=running;
     }
     job.status='completed';job.endedAt=new Date().toISOString();await save();return job;

package/test/updates.test.mjs

@@ -9,7 +9,7 @@ import { promisify } from 'node:util';
 import { extract, digest, version, newer, compatible } from '../src/updates/artifact.mjs';
 import { prepare, submit, command, read, jobPath, eligibility, jobs } from '../src/updates/control.mjs';
 import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
-import { atomic, snapshot, compose } from '../src/plugins/manager.mjs';
+import { atomic, snapshot, compose, prepareCommand } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
 import { status as runtimeStatus } from '../src/updates/status.mjs';
 const exec=promisify(execFile);
@@ -191,6 +191,29 @@ test('stopped plugins remain stopped; removed plugins and expanded mounts reject
  const reg=await read(path.join(f.home,'registry.json'));delete reg.plugins.sample;await atomic(path.join(f.home,'registry.json'),reg);
  await assert.rejects(prepare(f.home,'sample',{file:await f.pack()}),/not installed/);
 });
+test('plugin updates register additive command routes on an unchanged deployment',async t=>{
+ const f=await fixture(t,'plugin'),manifest=await read(path.join(f.source,'ez-plugin.json')),deployment=await read(path.join(f.source,'ez-deployment.json'));
+ manifest.commands.query={executable:'bin/example.mjs',args:[],channelQuery:true,exposure:{receivesExternalContent:true,sendsExternally:false,changesRecords:false,requiresReview:false}};
+ deployment.commands.query={service:'sample',argv:['node','/app/bin/example.mjs','query']};
+ await atomic(path.join(f.source,'ez-plugin.json'),manifest);await atomic(path.join(f.source,'ez-deployment.json'),deployment);
+ assert.equal((await eligibility(f.home,'sample',f.source,false)).pkg.version,'0.1.1');
+ const job=await queued(f),r=runtime(f);assert.equal((await perform(f.home,job,r)).status,'completed');
+ const registry=await read(path.join(f.home,'registry.json'));assert.equal(registry.commands.query,'sample');
+ const dispatch=await prepareCommand(f.home,'query',[]);assert.deepEqual(dispatch.argv.slice(-4),['node','sample','/app/bin/example.mjs','query']);
+ assert(r.calls.some(call=>call.includes('up')));
+});
+test('plugin command additions ignore object key order but reject collisions and changed routes',async t=>{
+ const f=await fixture(t,'plugin'),deployment=await read(path.join(f.source,'ez-deployment.json'));
+ deployment.services.sample={healthcheck:deployment.services.sample.healthcheck,volumes:deployment.services.sample.volumes,buildTarget:deployment.services.sample.buildTarget};
+ await atomic(path.join(f.source,'ez-deployment.json'),deployment);assert.equal((await eligibility(f.home,'sample',f.source,false)).pkg.version,'0.1.1');
+ const manifest=await read(path.join(f.source,'ez-plugin.json'));manifest.commands.other={executable:'bin/example.mjs',args:[]};deployment.commands.other={service:'sample',argv:['node','/app/bin/example.mjs','other']};
+ await atomic(path.join(f.source,'ez-plugin.json'),manifest);await atomic(path.join(f.source,'ez-deployment.json'),deployment);
+ const registry=await read(path.join(f.home,'registry.json'));registry.commands.other='different';await atomic(path.join(f.home,'registry.json'),registry);
+ await assert.rejects(eligibility(f.home,'sample',f.source,false),/alias collision/);
+ delete registry.commands.other;await atomic(path.join(f.home,'registry.json'),registry);
+ deployment.commands.sample.argv.push('--changed');await atomic(path.join(f.source,'ez-deployment.json'),deployment);
+ await assert.rejects(eligibility(f.home,'sample',f.source,false),/deployment/i);
+});
 test('interrupted activation recovers previous code; rollback failure is explicit and blocks further jobs',async t=>{
  const f=await fixture(t),job=await queued(f),r=runtime(f);await perform(f.home,job,r);
  const interrupted=await read(path.join(jobPath(f.home,job.id),'job.json'));interrupted.status='applying';