@jc_stack/ez-agents 0.1.0-beta.43 → 0.1.0-beta.44

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0-beta.44
+
+- Let isolated native agents read declared installed plugin skills through the
+  existing authorized broker. Discovery supplies literal skill-read commands,
+  so tools such as EzStudy work without copying package instructions into the
+  agent workspace or rebuilding native context.
+- Keep skill reads bound to the installed revision and active authorized run;
+  reject undeclared paths, traversal, symlinks and oversized files.
+
 ## 0.1.0-beta.43
 
 - Keep model and reasoning settings with each named conversation and preserve

package/bin/ez

@@ -88,7 +88,7 @@ const manager = async args => {
 const main = async () => {
   const args = process.argv.slice(2);
   if (!args.length || args[0] === '--help' || args[0] === '-h') {
-    process.stdout.write(JSON.stringify({commands:['tools list [--details]','<registered CLI> ...'],native:await installedNativeHelp(fileURLToPath(new URL('.',import.meta.url)))})+'\n');
+    process.stdout.write(JSON.stringify({commands:['tools list [--details]','tools skill <plugin> <declared-path>','<registered CLI> ...'],native:await installedNativeHelp(fileURLToPath(new URL('.',import.meta.url)))})+'\n');
     return;
   }
   const stdin = ['plugins', 'tools', 'updates', 'status'].includes(args[0]) ? '' : await readStdin();

package/docs/plugin-guide.md

@@ -57,7 +57,16 @@ At minimum, provide:
   machine-readable commands, stable exit codes, and readback for writes.
 
 The manager snapshots the package according to `package.json.files` plus the
-required manifests and Docker inputs. Keep one canonical checkout; do not keep
+required manifests and Docker inputs. `ez tools list --details` includes
+`skillReads`: literal command argument arrays for reading each installed skill.
+Use `ez tools skill <plugin> <declared-path>` to return its text and pinned
+revision. The isolated executor cannot open private host package paths directly;
+the authorized broker reads only manifest-declared regular skill files, without
+copying them into the agent workspace. Skill reads reject symlinks and files over
+64 KiB. The existing generic discovery footer remains accurate; no plugin-specific
+usage snippet or per-turn instruction is needed for this read contract.
+
+Keep one canonical checkout; do not keep
 permanent packaged copies or a second registry. See the full
 [plugin contribution requirements](plugin-contributions.md) and the
 [plugin manager contract](plugins.md#deployment-descriptors).
@@ -199,4 +208,3 @@ hash.
 
 For contribution, security, and removal details, follow the links above and the
 plugin's own `CONTRIBUTING.md`, `SECURITY.md`, and README.
-

package/docs/plugins.md

@@ -400,6 +400,12 @@ and `skills`. Descriptions are limited to 200 characters in this view; full
 instructions stay in the skill. Installation, replacement and removal are reflected
 on the next read, without hooks, LLM calls or a cached inventory file.
 
+The additive `skillReads` field supplies literal argument arrays for
+`ez tools skill <plugin> <declared-path>`. This read returns JSON with the
+installed plugin revision, declared path and skill content. Use it in isolated
+agents, where host package paths are private. It reads only the installed
+manifest's skills; arbitrary files, symlinks and files over 64 KiB are rejected.
+
 `ez tools list` retains its alias mapping for existing clients. Native AGENTS.md
 contains only the agent-bound discovery shortcut. New workspaces do not seed
 TOOLS.md, SOUL.md, USER.md, or an `inbox/`/`work/` layout; upgrades preserve

package/package.json

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

package/src/plugin-broker.mjs

@@ -59,6 +59,7 @@ const validateManagerArgs = async (value, workspace) => {
   if (!args.length) throw Error('Missing broker management command');
   const [group, action, name, extra, ...tail] = args;
   if (group === 'tools' && action === 'list' && (args.length === 2 || args.length === 3 && name === '--details')) return args;
+  if (group === 'tools' && action === 'skill' && IDENTIFIER.test(name) && args.length === 4) return args;
   if (group === 'tools' && action === 'exposure' && args.length === 2) return args;
   if (group === 'plugins' && action === 'available' && args.length === 2) return args;
   if (group === 'plugins' && action === 'list' && args.length === 2) return args;

package/src/plugins/manager.mjs

@@ -600,17 +600,34 @@ export async function main(args) {
     return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1),{publish:port,serve:true});
   }
   if(group==='tools'&&action==='connect')return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1));
-  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list [--details]|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<registered CLI> ...'],native:await installedNativeHelp(path.join(home,'bin')),foreignWorkspace:'Relay-bound registries run only from their owning agent workspace',scope:home});
+  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list [--details]|skill <plugin> <declared-path>|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<registered CLI> ...'],native:await installedNativeHelp(path.join(home,'bin')),foreignWorkspace:'Relay-bound registries run only from their owning agent workspace',scope:home});
   if(group==='plugins'&&(!action||args.includes('--help'))) return emit({commands:['available','list','inspect <id>','install <id>','start <id>','stop <id>','status <id>','logs <id>','uninstall <id>','catalog-add <id> --source PATH --revision HASH','export <id> <artifact> --output PATH','folder-bind <id> --service NAME --source PATH --target PATH [--writable]','folder-unbind <id> --service NAME --target PATH','folders <id>','shared-enable <id> <service>','shared-disable <id> <service>','shared-status <id> <service>'],uninstall:'Stops and removes containers/network and unregisters aliases; retains all volumes and secrets. No data deletion flag.',scope:home});
   if(group==='plugins'||group==='tools') {
     args=rest;args=args.filter(a=>a!=='--json');
     if(action==='available'&&group==='plugins') return emit(config.catalog);
     const r=await registry(home);
+    if(group==='tools' && action==='skill') {
+      if(args.length!==2)throw Error('Use tools skill <plugin> <declared-path>');
+      const [name,skill]=args,record=r.plugins[id(name)];
+      if(!record || !record.manifest.skills.includes(skill))throw Error('Unknown installed plugin skill');
+      if(path.isAbsolute(skill) || skill.split('/').some(part=>!part || part==='.' || part==='..') || /[\0\r\n]/.test(skill))throw Error('Unsafe skill path');
+      const source=await fs.realpath(record.source);
+      if(source!==record.source || !childOf(source,home))throw Error('Skill source must stay inside installed packages');
+      let file=source;
+      for(const part of skill.split('/')) {
+        file=path.join(file,part);
+        if((await fs.lstat(file)).isSymbolicLink())throw Error('Skill symlinks are not supported');
+      }
+      const stat=await fs.stat(file);
+      if(!stat.isFile() || stat.size>64*1024)throw Error('Skill must be a regular file of at most 64 KiB');
+      return emit({plugin:name,revision:record.revision,path:skill,content:await fs.readFile(file,'utf8')});
+    }
     if(action==='list') {
       if(group==='tools' && args.length===1 && args[0]==='--details')return emit(Object.fromEntries(Object.entries(r.plugins).map(([name,p])=>[name,{
         description:typeof p.manifest.description==='string'?p.manifest.description.replace(/\s+/g,' ').trim().slice(0,200):'',
         commands:Object.keys(p.manifest.commands).map(alias=>`ez ${alias} --help`),
         skills:p.manifest.skills.map(skill=>path.join(p.source,skill)),
+        skillReads:p.manifest.skills.map(skill=>['ez','tools','skill',name,skill]),
       }])));
       if(args.length)throw Error('Use tools list [--details] or plugins list');
       return emit(group==='tools'?r.commands:r.plugins);

package/test/plugin-broker.test.mjs

@@ -42,11 +42,12 @@ async function fixture(t) {
     revision,
     source,
     project: `ezp-${hash(realHome).slice(0, 16)}-sample`,
-    manifest: { schemaVersion: 1, id: 'sample', version: '1.0.0', commands: { sample: { executable: 'client.mjs', args: [] } }, skills: [] },
+    manifest: { schemaVersion: 1, id: 'sample', version: '1.0.0', commands: { sample: { executable: 'client.mjs', args: [] } }, skills: ['SKILL.md'] },
     deployment: { schemaVersion: 1, services: { sample: { buildTarget: 'runtime', volumes: {}, workspace: false, healthcheck: ['node', '--version'] } }, commands: { sample: { service: 'sample', argv: ['node', '/app/client.mjs'], suffix: [] } }, exports: {} },
     compose: path.join(home, 'packages', 'sample', 'compose.json'),
   };
   await fs.writeFile(path.join(home, 'registry.json'), JSON.stringify({ schemaVersion: 1, owner: realHome, plugins: { sample: record }, commands: { sample: 'sample' } }) + '\n', { mode: 0o600 });
+  await fs.writeFile(path.join(source, 'SKILL.md'), '# Synthetic authoring format\n');
   const fake = path.join(root, 'fake');
   await fs.mkdir(fake, { mode: 0o700 });
   await fs.writeFile(path.join(fake, 'docker'), `#!${process.execPath}
@@ -103,6 +104,13 @@ test('isolated broker authenticates an owned run, pins plugin revision, and writ
     const detailed = await request(f.socket, { version: 1, id: randomUUID(), operation: 'manager', runId: f.runId, args: ['tools', 'list', '--details'] });
     assert.equal(detailed.ok, true);
     assert.deepEqual(JSON.parse(detailed.stdout).sample.commands, ['ez sample --help']);
+    assert.deepEqual(JSON.parse(detailed.stdout).sample.skillReads, [['ez', 'tools', 'skill', 'sample', 'SKILL.md']]);
+    const skill = await request(f.socket, { version: 1, id: randomUUID(), operation: 'manager', runId: f.runId, args: ['tools', 'skill', 'sample', 'SKILL.md'] });
+    assert.equal(skill.code, 0);
+    assert.deepEqual(JSON.parse(skill.stdout), { plugin: 'sample', revision, path: 'SKILL.md', content: '# Synthetic authoring format\n' });
+    const privateFile = await request(f.socket, { version: 1, id: randomUUID(), operation: 'manager', runId: f.runId, args: ['tools', 'skill', 'sample', '../../config.json'] });
+    assert.notEqual(privateFile.code, 0);
+    assert.equal(privateFile.stdout, '');
     const resolved = await request(f.socket, { version: 1, id: randomUUID(), operation: 'resolve', runId: f.runId, alias: 'sample' });
     assert.equal(resolved.ok, true);
     assert.equal(resolved.revision, revision);
@@ -162,6 +170,9 @@ test('broker rejects resolve and invoke for a revoked run', async t => {
   try {
     await waitForSocket(f.socket);
     await new RunStore(f.controlDir).patch(f.runId, { status: 'cancelled' });
+    const skill = await request(f.socket, { version: 1, id: randomUUID(), operation: 'manager', runId: f.runId, args: ['tools', 'skill', 'sample', 'SKILL.md'] });
+    assert.equal(skill.ok, false);
+    assert.equal(skill.stdout, undefined);
     const resolved = await request(f.socket, { version: 1, id: randomUUID(), operation: 'resolve', runId: f.runId, alias: 'sample' });
     assert.equal(resolved.ok, false);
     const invoked = await request(f.socket, { version: 1, id: randomUUID(), operation: 'invoke', runId: f.runId, alias: 'sample', revision, capability: 'a'.repeat(64), args: [] });

package/test/plugin-manager.test.mjs

@@ -104,12 +104,26 @@ test('installed snippets follow install, upgrade and uninstall without files or
   const before=await fs.readFile(f.log,'utf8'),index=await details();
   assert.equal(index.sample.description,description);assert.deepEqual(index.sample.commands,['ez sample --help']);
   assert.equal(await fs.readFile(index.sample.skills[0],'utf8'),'Synthetic');
+  assert.deepEqual(index.sample.skillReads,[['ez','tools','skill','sample','SKILL.md']]);
+  assert.deepEqual(JSON.parse((await f.call('tools','skill','sample','SKILL.md')).stdout),{plugin:'sample',revision:p.revision,path:'SKILL.md',content:'Synthetic'});
   assert.equal(await fs.readFile(f.log,'utf8'),before);
   assert.deepEqual(JSON.parse((await f.call('tools','list')).stdout),{sample:'sample'});
   await f.call('plugins','uninstall','sample');assert.deepEqual(await details(),{});
  }
  await assert.rejects(fs.access(path.join(f.workspace,'TOOLS.md')),{code:'ENOENT'});
 });
+test('skill reads reject undeclared paths, traversal, symlinks and oversized files',async t=>{
+ const f=await fixture(t),p=await snapshot(f.source);await init(f.home,f.workspace);await f.call('plugins','install','sample','--source',f.source,'--revision',p.revision);
+ for(const requested of ['../config.json','/etc/passwd','client.mjs'])await assert.rejects(f.call('tools','skill','sample',requested),/Unknown installed plugin skill/);
+ await assert.rejects(f.call('tools','skill','foreign','SKILL.md'),/Unknown installed plugin skill/);
+ const r=JSON.parse(await fs.readFile(path.join(f.home,'registry.json'),'utf8')),file=path.join(r.plugins.sample.source,'SKILL.md');
+ await fs.rm(file);await fs.symlink(path.join(f.home,'config.json'),file);
+ await assert.rejects(f.call('tools','skill','sample','SKILL.md'),/symlink/);
+ await fs.rm(file);await fs.writeFile(file,'x'.repeat(64*1024+1));
+ await assert.rejects(f.call('tools','skill','sample','SKILL.md'),/64 KiB/);
+ r.plugins.sample.manifest.skills=['../config.json'];await fs.writeFile(path.join(f.home,'registry.json'),JSON.stringify(r));
+ await assert.rejects(f.call('tools','skill','sample','../config.json'),/Unsafe skill path/);
+});
 test('application plugin context is namespaced, authorized, and absent from ordinary commands',async t=>{
  const f=await fixture(t),p=await snapshot(f.source);await init(f.home,f.workspace);await f.call('plugins','install','sample','--source',f.source,'--revision',p.revision);
  const home=await fs.realpath(f.home);