workbite 0.1.0 → 0.1.2

package/README.md

@@ -6,8 +6,8 @@ WorkBite installs and opens **Work Stack** (organizes the work) and
 ```sh
 npm install -g workbite
 workbite install
-workbite open --workspace /abs/path/new-folder --init
-workbite open --workspace /abs/path/existing-workspace
+workbite open --workspace /abs/path/new-folder --init      # first time, once
+workbite                                                   # afterwards
 ```
 
 Node.js 20+ on Windows x64 or Linux x64 (glibc 2.28+).
@@ -21,6 +21,11 @@ Node.js 20+ on Windows x64 or Linux x64 (glibc 2.28+).
   workspace's Work Stack owner and a StackBite backend (only processes it can
   prove it started), then runs the Work Stack terminal UI. Backends keep
   running after the UI exits.
+- `workbite` (or `workbite open` without `--workspace`) reopens the last
+  workspace that opened successfully; an explicit `--workspace` always wins.
+  It refuses, starting nothing, if that workspace is missing, moved or its
+  `workspace.json` id changed, and never picks another folder by itself.
+  `--init` always needs an explicit `--workspace`.
 - Each backend's startup record (private token, launch id, port) is saved in
   the state folder *before* the process is started. A later `open` reuses
   that same attempt once it authenticates (also after a slow start), and
@@ -35,5 +40,21 @@ with absolute `WORKBITE_HOME` / `WORKBITE_STATE_DIR`) and never touches
 separately installed Work Stack or StackBite apps, their state or ports. It
 never approves provider trust or starts paid agents by itself.
 
+Coding agents read and record Tasks of a workspace whose owner `workbite open`
+already runs; nothing is started for them:
+
+```sh
+workbite agent status                                    # bound workspace path + UUID
+workbite agent --workspace ABS --workspace-uid UUID context --task T-0001
+workbite agent --workspace ABS --workspace-uid UUID tasks create --intent-id ID --input-file FILE
+workbite mcp --workspace ABS --workspace-uid UUID         # MCP stdio server
+```
+
+Writes (`tasks create`, `tasks update`, `checkpoint`) always need the explicit
+`--workspace` + `--workspace-uid` pair. `workbite mcp` binds one workspace when
+it starts. The `workbite-native` agent skill shipped in this package
+(`skills/workbite-native/`) describes the commands, packets and recovery
+rules.
+
 This package is `UNLICENSED` (all rights reserved). Third-party licenses ship
 in each bundle's `licenses/` folder.

package/lib/agent.js

@@ -0,0 +1,210 @@
+'use strict';
+// WorkBite agent interface: binds one already-running, WorkBite-owned Work Stack
+// owner and forwards curated agent commands to it through the pinned native
+// client's v1 `cli.execute` RPC. The native client is the only mapper to the
+// owner's versioned APIs. Nothing here starts, downloads, initializes or adopts
+// an owner, falls back to another workspace or tool, or replays a write.
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { randomBytes } = require('node:crypto');
+const { fail, exists, readSmall, sha256, UUID } = require('./common');
+const { cleanEnvironment, stateLayout, workspaceKey, readWorkspaceUid, rememberedWorkspace, engineIdentity } = require('./runtime');
+
+const OWNER_SCHEMA = 'workbite.owner.v2';
+const LOOPBACK = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/;
+const LAUNCH = /^[0-9a-f]{16}$/;
+const MAX_PACKET_BYTES = 32768;
+const MAX_ARGV = 128;
+const MAX_STDOUT = 1024 * 1024 + 8192;
+const MAX_STDERR = 65536;
+const DEFAULT_DEADLINE = 30000;
+// Placeholder authority for the static capability table only; the client never contacts it for that command.
+const NO_ENDPOINT = 'http://127.0.0.1:9';
+const NO_UID = '00000000-0000-4000-8000-000000000000';
+
+// Curated command paths; every other native command (raw rpc, legacy, deploy, delete, migration) is refused.
+const AGENT_COMMANDS = Object.freeze(['capabilities', 'status', 'tasks list', 'tasks create', 'tasks update', 'context',
+  'checkpoint', 'operation-status']);
+const WRITE_COMMANDS = Object.freeze(['tasks create', 'tasks update', 'checkpoint']);
+const FORBIDDEN_FLAGS = new Set(['--data-dir', '--endpoint', '--token-env', '--token', '--workspace', '--read-retries',
+  '--timeout-ms', '--request-id', '--generation', '--packet-file']);
+
+const EXPLICIT = 'Name it with --workspace ABS --workspace-uid UUID, or open it once with: workbite open --workspace ABS';
+const bindings = new WeakMap();
+
+// Only the bound --workspace-uid (once, exactly that UID) may precede the command words.
+function commandOf(argv, uid) {
+  if (!Array.isArray(argv) || argv[0] !== 'agent') return null;
+  let start = 1;
+  if (typeof uid === 'string' && uid) {
+    if (argv[1] === '--workspace-uid' && argv[2] === uid) start = 3;
+    else if (argv[1] === `--workspace-uid=${uid}`) start = 2;
+  }
+  const words = [];
+  for (const item of argv.slice(start)) { if (item.startsWith('-')) break; words.push(item); }
+  const name = words.join(' ');
+  return AGENT_COMMANDS.includes(name) ? name : null;
+}
+function checkedArgv(argv, uid) {
+  if (!Array.isArray(argv) || !argv.length || argv.length > MAX_ARGV
+      || argv.some(item => typeof item !== 'string' || item.includes('\0'))
+      || argv.reduce((total, item) => total + Buffer.byteLength(item), 0) > MAX_PACKET_BYTES) fail('Invalid WorkBite agent arguments');
+  const command = commandOf(argv, uid);
+  if (!command) fail('Unsupported WorkBite agent command; supported: ' + AGENT_COMMANDS.join(', '));
+  argv.forEach((item, index) => {
+    const key = item.split('=')[0];
+    if (FORBIDDEN_FLAGS.has(key)) fail(`WorkBite agent commands do not accept ${key}; authority comes from the binding`);
+    if (key === '--workspace-uid') {
+      const value = item.includes('=') ? item.slice(item.indexOf('=') + 1) : argv[index + 1];
+      if (value !== uid) fail('--workspace-uid does not match the bound WorkBite workspace');
+    }
+  });
+  return command;
+}
+function checkedStdin(stdin) {
+  if (stdin === undefined || stdin === null) return null;
+  if (typeof stdin !== 'string' || Buffer.byteLength(stdin) > MAX_PACKET_BYTES || stdin.includes('\0')) {
+    fail(`WorkBite agent input must be UTF-8 text of at most ${MAX_PACKET_BYTES} bytes`);
+  }
+  return stdin;
+}
+function clientCommand(installed, commands) {
+  const command = commands?.workstack_client || [installed?.executables?.workstack_client];
+  if (!Array.isArray(command) || typeof command[0] !== 'string' || !path.isAbsolute(command[0])) {
+    fail('The verified WorkBite native client is not available; run workbite check.');
+  }
+  return command;
+}
+
+function explicitWorkspace(workspace, workspaceUid) {
+  if ((workspace === undefined) !== (workspaceUid === undefined)) fail('--workspace and --workspace-uid must be given together');
+  if (typeof workspace !== 'string' || !path.isAbsolute(workspace) || /[\x00-\x1f]/.test(workspace)
+      || (process.platform === 'win32' && /^[\\/](?![\\/])/.test(workspace))) fail('--workspace must be an absolute path');
+  if (typeof workspaceUid !== 'string' || !UUID.test(workspaceUid)) fail('--workspace-uid must be a canonical workspace UUID');
+  return { workspace: path.resolve(workspace), uid: workspaceUid };
+}
+// Only the saved selection (written after a fully proven open) names a default; never a guess.
+async function selectedWorkspace(layout) {
+  if (!await exists(layout.selection)) fail(`No WorkBite workspace is selected. ${EXPLICIT}`);
+  return rememberedWorkspace(layout);
+}
+
+async function ownerRecord(layout, workspace, uid) {
+  const file = path.join(layout.owners, `${workspaceKey(workspace)}.json`);
+  let bytes, record;
+  try { bytes = await readSmall(file, 65536); record = JSON.parse(bytes.toString('utf8')); } catch {
+    fail(`No ready WorkBite-owned Work Stack owner is recorded for ${workspace}. Start it with: workbite open --workspace ABS`);
+  }
+  const same = typeof record?.workspace === 'string' && path.isAbsolute(record.workspace)
+    && workspaceKey(path.resolve(record.workspace)) === workspaceKey(workspace);
+  if (record === null || typeof record !== 'object' || Array.isArray(record) || record.schema !== OWNER_SCHEMA
+      || record.state !== 'ready' || !same || record.workspace_uid !== uid || typeof record.launch !== 'string'
+      || !LAUNCH.test(record.launch) || typeof record.token !== 'string' || !/^[0-9a-f]{64}$/.test(record.token)
+      || typeof record.endpoint !== 'string' || !LOOPBACK.test(record.endpoint)) {
+    fail(`The Work Stack owner record for ${workspace} is not a ready WorkBite owner for that workspace UID. Open it with: workbite open --workspace ABS`);
+  }
+  return { file, digest: sha256(bytes), record };
+}
+async function proveOwner(layout, workspace, uid) {
+  if (await readWorkspaceUid(workspace) !== uid) fail(`The workspace.json id of ${workspace} does not match --workspace-uid`);
+  const owner = await ownerRecord(layout, workspace, uid);
+  if (!await engineIdentity(owner.record.endpoint, owner.record.token, uid)) {
+    fail(`The WorkBite Work Stack owner for ${workspace} could not be authenticated (stopped or replaced). Start it with: workbite open --workspace ABS`);
+  }
+  return owner;
+}
+
+async function bindAgent({ installed, stateRoot, environment = process.env, workspace, workspaceUid, commands, timeouts = {} } = {}) {
+  if (typeof stateRoot !== 'string' || !path.isAbsolute(stateRoot)) fail('WorkBite state directory must be an absolute path');
+  const layout = stateLayout(path.resolve(stateRoot));
+  const command = clientCommand(installed, commands);
+  const chosen = workspace === undefined && workspaceUid === undefined
+    ? await selectedWorkspace(layout) : explicitWorkspace(workspace, workspaceUid);
+  const owner = await proveOwner(layout, chosen.workspace, chosen.uid);
+  const binding = Object.freeze({ workspace: chosen.workspace, workspaceUid: chosen.uid, endpoint: owner.record.endpoint,
+    stateRoot: layout.root });
+  bindings.set(binding, Object.freeze({ layout, command, environment: { ...environment }, digest: owner.digest,
+    launch: owner.record.launch, deadline: timeouts.agent || DEFAULT_DEADLINE }));
+  return binding;
+}
+
+// The bound owner must be the very same proven generation for every call.
+async function recheck(binding, state) {
+  const owner = await proveOwner(state.layout, binding.workspace, binding.workspaceUid);
+  if (owner.digest !== state.digest || owner.record.launch !== state.launch || owner.record.endpoint !== binding.endpoint) {
+    fail('The bound WorkBite Work Stack owner changed since binding; bind again (nothing was sent).');
+  }
+}
+
+const boundedLine = text => String(text).replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 300);
+// One request, one response, no retry. `write` decides how an uncertain outcome is reported.
+function rpc(command, { endpoint, uid, environment, argv, stdin, deadline, write }) {
+  const requestId = `workbite-agent-${randomBytes(8).toString('hex')}`;
+  const request = JSON.stringify({ version: 1, request_id: requestId, workspace_uid: uid, generation: 0,
+    method: 'cli.execute', params: { argv, stdin } }) + '\n';
+  const nativeTimeout = Math.max(1000, Math.min(300000, deadline));
+  const [file, ...prefix] = command;
+  const uncertain = what => ({ code: 1, stdout: '', stderr: write
+    ? `error: commit unknown (${what}); WorkBite did not replay it. Check: workbite agent operation-status --intent-id ID\n`
+    : `error: ${what}; nothing was retried\n` });
+  return new Promise(resolve => {
+    let child;
+    try {
+      child = spawn(file, [...prefix, '--endpoint', endpoint, '--workspace-uid', uid, '--timeout-ms', String(nativeTimeout),
+        '--read-retries', '0', 'rpc'], { env: cleanEnvironment(environment), shell: false, windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch { resolve({ code: 1, stdout: '', stderr: 'error: cannot start the verified Work Stack native client\n' }); return; }
+    const out = [], err = [];
+    let outSize = 0, errSize = 0, done = false, overflow = false, started = false;
+    const finish = result => { if (!done) { done = true; clearTimeout(timer); resolve(result); } };
+    const timer = setTimeout(() => { child.kill(); finish(uncertain('native client deadline exceeded')); }, nativeTimeout + 5000);
+    child.stdout.on('data', chunk => {
+      outSize += chunk.length;
+      if (outSize > MAX_STDOUT) { overflow = true; child.kill(); } else out.push(chunk);
+    });
+    child.stderr.on('data', chunk => { errSize += chunk.length; if (errSize <= MAX_STDERR) err.push(chunk); });
+    child.stdin.on('error', () => {});
+    child.once('spawn', () => { started = true; });
+    child.once('error', () => finish(started ? uncertain('native client failed')
+      : { code: 1, stdout: '', stderr: 'error: cannot start the verified Work Stack native client\n' }));
+    child.once('close', () => {
+      if (overflow) { finish(uncertain('native response exceeded its bound')); return; }
+      const lines = Buffer.concat(out).toString('utf8').split('\n').filter(line => line.trim());
+      let response = null;
+      try { response = lines.length === 1 ? JSON.parse(lines[0]) : null; } catch { response = null; }
+      if (response === null || typeof response !== 'object' || response.version !== 1 || response.request_id !== requestId) {
+        finish(uncertain('no valid native response')); return;
+      }
+      if (response.error) {
+        const code = typeof response.error.code === 'string' ? response.error.code.replace(/[^A-Za-z]/g, '').slice(0, 32) : 'Error';
+        if (code === 'UnknownCommit') { finish(uncertain('owner response was lost')); return; }
+        finish({ code: 1, stdout: '', stderr: `error: ${code}: ${boundedLine(response.error.message || 'native request failed')}\n` });
+        return;
+      }
+      const result = response.result;
+      if (result === null || typeof result !== 'object' || !Number.isInteger(result.exit_code)
+          || typeof result.stdout !== 'string' || typeof result.stderr !== 'string') { finish(uncertain('invalid native result')); return; }
+      finish({ code: result.exit_code, stdout: result.stdout, stderr: result.stderr });
+    });
+    child.stdin.end(request);
+  });
+}
+
+async function executeAgent(binding, argv, { stdin } = {}) {
+  const state = bindings.get(binding);
+  if (!state) fail('Not a WorkBite agent binding; use bindAgent');
+  const command = checkedArgv(argv, binding.workspaceUid);
+  const input = checkedStdin(stdin);
+  await recheck(binding, state);
+  return rpc(state.command, { endpoint: binding.endpoint, uid: binding.workspaceUid, environment: state.environment,
+    argv: [...argv], stdin: input, deadline: state.deadline, write: WRITE_COMMANDS.includes(command) });
+}
+
+// The static capability table needs no workspace authority; it never reaches an owner.
+async function agentCapabilities({ installed, commands, environment = process.env, argv = ['agent', 'capabilities'], timeouts = {} } = {}) {
+  if (checkedArgv(argv, NO_UID) !== 'capabilities') fail('Only agent capabilities is authority-free');
+  return rpc(clientCommand(installed, commands), { endpoint: NO_ENDPOINT, uid: NO_UID, environment, argv: [...argv], stdin: null,
+    deadline: timeouts.agent || DEFAULT_DEADLINE, write: false });
+}
+
+module.exports = { bindAgent, executeAgent, agentCapabilities, AGENT_COMMANDS, WRITE_COMMANDS, MAX_PACKET_BYTES, commandOf };

package/lib/cli.js

@@ -1,8 +1,9 @@
 'use strict';
 const path = require('node:path');
-const { fail } = require('./common');
+const { fail, readSmall } = require('./common');
 const { locations, releaseSpec, ensureInstalled, stageReporter, packageVersion } = require('./install');
 const { openSuite } = require('./runtime');
+const { bindAgent, executeAgent, agentCapabilities, WRITE_COMMANDS, MAX_PACKET_BYTES } = require('./agent');
 
 const HELP = `WorkBite ${packageVersion} - Work Stack organizes the work. StackBite gets it moving.
 
@@ -12,13 +13,32 @@ Usage:
   workbite open --workspace ABS [--init] [--no-ui]
                                          start or reuse this workspace's Work Stack owner and the
                                          StackBite backend, then run the Work Stack terminal UI
+  workbite [open] [--no-ui]              reopen the last workspace WorkBite opened successfully
+  workbite agent [--workspace ABS --workspace-uid UUID] COMMAND [--input-file FILE | --stdin] [flags]
+                                         curated Work Stack agent commands against the running,
+                                         WorkBite-owned owner (never starts one): capabilities, status,
+                                         tasks list|create|update, context, checkpoint, operation-status
+  workbite mcp [--workspace ABS --workspace-uid UUID]
+                                         WorkBite MCP server on stdio for the same agent commands
   workbite --version | --help
 
+agent:
+  Reads use the last workspace WorkBite opened unless --workspace and --workspace-uid name one.
+  Writes (tasks create, tasks update, checkpoint) always need --workspace ABS --workspace-uid UUID
+  and a packet from --input-file FILE or --stdin (UTF-8, at most 32768 bytes). An uncertain write
+  is never replayed; check it with agent operation-status --intent-id ID.
+
 open:
-  --workspace ABS  absolute workspace folder
-  --init           create a new Work Stack workspace in a new or empty folder
+  --workspace ABS  absolute workspace folder; always wins over the remembered one
+  --init           create a new Work Stack workspace in a new or empty folder (needs --workspace)
   --no-ui          start or reuse the backends, print one JSON summary and exit
 
+First time, name the workspace once:
+  workbite open --workspace /abs/path/new-folder --init
+  workbite open --workspace /abs/path/existing-workspace
+Afterwards just run:
+  workbite
+
 The Work Stack owner and StackBite backend keep running after the UI exits, so
 agents continue. WorkBite never auto-updates, installs dependencies, approves
 provider trust or stops processes it cannot prove are its own.
@@ -28,12 +48,98 @@ Locations (override with absolute WORKBITE_HOME / WORKBITE_STATE_DIR):
   Linux    $XDG_DATA_HOME/workbite/app/<version>  $XDG_STATE_HOME/workbite
 `;
 
+// Native flags each curated agent command accepts (value-taking unless listed in FLAGS_WITHOUT_VALUE).
+const AGENT_FLAGS = Object.freeze({
+  capabilities: ['--command', '--section'],
+  status: ['--workspace-revision'],
+  'tasks list': ['--status', '--limit', '--offset'],
+  'tasks create': ['--intent-id'],
+  'tasks update': ['--intent-id', '--task', '--expected-revision'],
+  context: ['--task', '--view', '--format', '--source', '--fingerprint', '--if-fingerprint'],
+  checkpoint: ['--intent-id'],
+  'operation-status': ['--intent-id'],
+});
+const FLAGS_WITHOUT_VALUE = new Set(['--workspace-revision', '--fingerprint']);
+const REPEATABLE = new Set(['--source']);
+const PACKET_COMMANDS = new Set(['tasks create', 'tasks update', 'checkpoint']);
+
+function parseBinding(options, argument, next) {
+  if (argument === '--workspace' && options.workspace === undefined && next !== undefined && !next.startsWith('--')) {
+    if (!path.isAbsolute(next)) fail('--workspace must be an absolute path');
+    options.workspace = next; return true;
+  }
+  if (argument === '--workspace-uid' && options.workspaceUid === undefined && next !== undefined && !next.startsWith('--')) {
+    options.workspaceUid = next; return true;
+  }
+  return false;
+}
+function pairedBinding(options) {
+  if ((options.workspace === undefined) !== (options.workspaceUid === undefined)) {
+    fail('--workspace and --workspace-uid must be given together');
+  }
+}
+
+function parseAgent(rest) {
+  // The binding pair may come before the command words, after them, or split around them;
+  // each flag is still accepted once, with its value, and nothing else may precede the words.
+  const options = { command: 'agent' };
+  while (rest.length && parseBinding(options, rest[0], rest[1])) rest.splice(0, 2);
+  if (rest.length && rest[0].startsWith('-')) {
+    fail(`Unknown or repeated agent option before the command: ${String(rest[0]).slice(0, 64)}. See workbite --help.`);
+  }
+  const words = [];
+  while (rest.length && !rest[0].startsWith('-')) words.push(rest.shift());
+  const name = words.join(' ');
+  if (!Object.hasOwn(AGENT_FLAGS, name)) {
+    fail(`Unknown agent command: ${name.slice(0, 64) || '(none)'}. Supported: ${Object.keys(AGENT_FLAGS).join(', ')}.`);
+  }
+  Object.assign(options, { name, native: ['agent', ...words] });
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index], next = rest[index + 1];
+    if (parseBinding(options, argument, next)) { index++; continue; }
+    if (argument === '--input-file' && options.inputFile === undefined && !options.stdin && next !== undefined
+        && !next.startsWith('--')) { options.inputFile = next; index++; continue; }
+    if (argument === '--stdin' && !options.stdin && options.inputFile === undefined) { options.stdin = true; continue; }
+    if (!AGENT_FLAGS[name].includes(argument) || (!REPEATABLE.has(argument) && options.native.includes(argument))) {
+      fail(`Unknown or repeated agent ${name} option: ${String(argument).slice(0, 64)}. See workbite --help.`);
+    }
+    options.native.push(argument);
+    if (FLAGS_WITHOUT_VALUE.has(argument)) continue;
+    if (next === undefined || next.startsWith('--')) fail(`${argument} needs a value`);
+    options.native.push(next); index++;
+  }
+  pairedBinding(options);
+  const packet = options.stdin || options.inputFile !== undefined;
+  if (PACKET_COMMANDS.has(name) !== packet) {
+    fail(PACKET_COMMANDS.has(name) ? `agent ${name} needs a packet from --input-file FILE or --stdin`
+      : `agent ${name} does not take --input-file or --stdin`);
+  }
+  if (WRITE_COMMANDS.includes(name) && options.workspace === undefined) {
+    fail(`agent ${name} changes Work Stack; name the workspace with --workspace ABS --workspace-uid UUID`);
+  }
+  if (packet) options.native.push('--stdin');
+  return options;
+}
+function parseMcp(rest) {
+  const options = { command: 'mcp' };
+  for (let index = 0; index < rest.length; index++) {
+    if (!parseBinding(options, rest[index], rest[index + 1])) {
+      fail(`Unknown or repeated mcp option: ${String(rest[index]).slice(0, 64)}. See workbite --help.`);
+    }
+    index++;
+  }
+  pairedBinding(options);
+  return options;
+}
+
 function parseArguments(argv) {
   if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) return { command: 'help' };
-  if (!argv.length) return { command: 'help' };
   if (argv.length === 1 && ['--version', '-v', 'version'].includes(argv[0])) return { command: 'version' };
-  const [command, ...rest] = argv;
+  // Bare `workbite` (or only open options) means `workbite open`.
+  const [command, ...rest] = argv.length && !argv[0].startsWith('--') ? argv : ['open', ...argv];
   if ((command === 'install' || command === 'check') && !rest.length) return { command };
+  if (command === 'agent') return parseAgent([...rest]);
+  if (command === 'mcp') return parseMcp(rest);
   if (command === 'open') {
     const options = { command, init: false, ui: true };
     for (let index = 0; index < rest.length; index++) {
@@ -44,13 +150,68 @@ function parseArguments(argv) {
           && !rest[index + 1].startsWith('--')) options.workspace = rest[++index];
       else fail(`Unknown or repeated open option: ${String(argument).slice(0, 64)}. See workbite --help.`);
     }
-    if (options.workspace === undefined) fail('workbite open needs --workspace ABS');
+    // Without --workspace the remembered workspace is reopened; --init never picks a folder by itself.
+    if (options.workspace === undefined) {
+      if (options.init) fail('--init needs --workspace ABS naming the new or empty folder');
+      return options;
+    }
     if (!path.isAbsolute(options.workspace)) fail('--workspace must be an absolute path');
     return options;
   }
   fail(`Unknown command: ${String(command).slice(0, 64)}. See workbite --help.`);
 }
 
+// A packet is bounded UTF-8 text handed to the native client as stdin; it never enters argv.
+function packetText(bytes) {
+  if (bytes.length > MAX_PACKET_BYTES) fail(`The agent packet exceeds ${MAX_PACKET_BYTES} bytes`);
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('The agent packet is not valid UTF-8'); }
+}
+async function readPacket(parsed, stdin) {
+  if (parsed.inputFile !== undefined) {
+    let bytes;
+    try { bytes = await readSmall(path.resolve(parsed.inputFile), MAX_PACKET_BYTES); } catch (error) {
+      fail(/oversized/.test(error.message) ? `The agent packet file is not a regular file of at most ${MAX_PACKET_BYTES} bytes`
+        : 'The agent packet file could not be read');
+    }
+    return packetText(bytes);
+  }
+  if (!parsed.stdin) return null;
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of stdin) {
+    size += chunk.length;
+    if (size > MAX_PACKET_BYTES) fail(`The agent packet exceeds ${MAX_PACKET_BYTES} bytes`);
+    chunks.push(Buffer.from(chunk));
+  }
+  return packetText(Buffer.concat(chunks));
+}
+
+async function runAgent(parsed, { installed, stateRoot, environment, commands, timeouts, stdout, stderr, stdin }) {
+  let result, binding = null;
+  if (parsed.name === 'capabilities' && parsed.workspace === undefined) {
+    result = await agentCapabilities({ installed, commands, environment, argv: parsed.native, timeouts });
+  } else {
+    binding = await bindAgent({ installed, stateRoot, environment, workspace: parsed.workspace,
+      workspaceUid: parsed.workspaceUid, commands, timeouts });
+    const packet = await readPacket(parsed, stdin || process.stdin);
+    result = await executeAgent(binding, parsed.native, { stdin: packet });
+  }
+  let output = result.stdout;
+  if (parsed.name === 'status' && result.code === 0) {
+    try {
+      const document = JSON.parse(output);
+      if (document !== null && typeof document === 'object' && !Array.isArray(document)) {
+        document.workbite = { schema: 'workbite.agent.binding.v1', workspace: binding.workspace,
+          workspace_uid: binding.workspaceUid, endpoint: binding.endpoint, state: binding.stateRoot };
+        output = JSON.stringify(document) + '\n';
+      }
+    } catch { /* not JSON: passed through unchanged */ }
+  }
+  if (output) stdout.write(output);
+  if (result.stderr) stderr.write(result.stderr);
+  return { code: result.code, signal: null };
+}
+
 async function main(argv = process.argv.slice(2), options = {}) {
   const stdout = options.stdout || process.stdout, stderr = options.stderr || process.stderr;
   const parsed = parseArguments(argv);
@@ -60,15 +221,23 @@ async function main(argv = process.argv.slice(2), options = {}) {
   const platform = options.platform || process.platform;
   const spec = releaseSpec(options.manifest || require('../release.json'), platform, options.arch || process.arch, options);
   const where = locations(environment, platform);
+  // agent and mcp only use an already installed, verified suite: nothing is downloaded or started.
   const installed = await ensureInstalled(spec, { ...options, apps: options.apps || where.apps,
-    checkOnly: parsed.command === 'check', progress: options.progress || stageReporter(stderr) });
+    checkOnly: ['check', 'agent', 'mcp'].includes(parsed.command), progress: options.progress || stageReporter(stderr) });
+  const stateRoot = options.stateRoot || where.state;
+  if (parsed.command === 'agent') return runAgent(parsed, { ...options, installed, stateRoot, environment, stdout, stderr });
+  if (parsed.command === 'mcp') {
+    return require('./mcp').runMcp({ installed, stateRoot, environment, workspace: parsed.workspace,
+      workspaceUid: parsed.workspaceUid, commands: options.commands, timeouts: options.timeouts,
+      stdin: options.stdin || process.stdin, stdout, stderr });
+  }
   if (parsed.command === 'install' || parsed.command === 'check') {
     stdout.write(JSON.stringify({ schema: 'workbite.install.v1', version: spec.version, target: spec.target,
-      home: installed.home, state: options.stateRoot || where.state }) + '\n');
+      home: installed.home, state: stateRoot }) + '\n');
     return { code: 0, signal: null };
   }
   return openSuite({ installed, commands: options.commands, workspace: parsed.workspace, init: parsed.init, ui: parsed.ui,
-    stateRoot: options.stateRoot || where.state, environment, spawnImpl: options.spawnImpl, stdout, timeouts: options.timeouts });
+    stateRoot, environment, spawnImpl: options.spawnImpl, stdout, timeouts: options.timeouts });
 }
 
 module.exports = { main, parseArguments, HELP };

package/lib/install.js

@@ -49,16 +49,25 @@ function platformTarget(platform = process.platform, arch = process.arch, runtim
   return target;
 }
 
-function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}) {
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function canonicalVersion(value) { return typeof value === 'string' && SEMVER.test(value); }
+
+// manifest.version names the sealed native artifact (asset, tag, URL, bundle, cache directory).
+// An explicit launcherVersion lets a launcher-only npm patch reuse that artifact unchanged;
+// without it the legacy binding (artifact version == package version) still applies.
+function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}, launcher = packageVersion) {
   const target = platformTarget(platform, arch, runtime);
-  if (manifest.schema !== 'workbite.release.v1' || manifest.product !== 'WorkBite' || manifest.version !== packageVersion
+  const bound = Object.hasOwn(manifest, 'launcherVersion')
+    ? canonicalVersion(manifest.launcherVersion) && manifest.launcherVersion === launcher
+    : manifest.version === launcher;
+  if (manifest.schema !== 'workbite.release.v1' || manifest.product !== 'WorkBite' || !canonicalVersion(manifest.version) || !bound
       || manifest.repository !== REPOSITORY || manifest.tag !== `v${manifest.version}`) fail('Invalid pinned WorkBite release identity');
   const spec = manifest.platforms?.[target];
   const asset = `workbite-${manifest.version}-${target}${platform === 'win32' ? '.zip' : '.tar.gz'}`;
   if (!spec || spec.asset !== asset
       || spec.url !== `https://github.com/${manifest.repository}/releases/download/${manifest.tag}/${asset}`) fail('Invalid pinned release asset');
   if (spec.sha256 === null || spec.size === null || spec.bundleSha256 === null) {
-    fail(`This workbite ${manifest.version} package has no sealed ${target} release artifact yet. Nothing was downloaded.`);
+    fail(`This workbite ${launcher} package has no sealed ${target} release artifact yet. Nothing was downloaded.`);
   }
   if (![spec.sha256, spec.bundleSha256].every(value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value))
       || !Number.isSafeInteger(spec.size) || spec.size <= 0 || spec.size > LIMITS.download) fail('Invalid pinned release asset');