workbite 0.1.0 → 0.1.2

package/lib/mcp.js

@@ -0,0 +1,501 @@
+'use strict';
+// `workbite mcp`: a minimal MCP stdio server (newline-delimited JSON-RPC 2.0) over the
+// WorkBite agent binding. The binding is resolved once per process and never retargets;
+// every tool call becomes exactly one executeAgent request, run one at a time, never
+// replayed. stdout carries protocol messages only; diagnostics go to stderr.
+//
+// Memory is bounded: at most LIMITS.queue complete lines (LIMITS.queueBytes in total) wait
+// behind the one message in flight, plus one partial line (LIMITS.message) and at most one
+// undelivered input chunk. When that is full stdin is paused (backpressure), never dropped;
+// the next response is not produced until stdout has drained.
+
+const SUPPORTED_VERSIONS = Object.freeze(['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']);
+const LATEST_VERSION = SUPPORTED_VERSIONS[0];
+// structuredContent, outputSchema and tool titles exist from 2025-06-18; annotations from 2025-03-26.
+const STRUCTURED_SINCE = '2025-06-18', ANNOTATIONS_SINCE = '2025-03-26';
+// Only the 2025-03-26 schema defines JSONRPCBatchRequest ("MUST support receiving JSON-RPC batches").
+// 2024-11-05 defines no batch message and 2025-06-18 removed them, so batches are refused there.
+const BATCH_VERSION = '2025-03-26';
+const LIMITS = Object.freeze({ message: 1024 * 1024, packet: 32768, stdout: 256 * 1024, stderr: 8 * 1024,
+  batch: 16, queue: 16, queueBytes: 4 * 1024 * 1024 });
+const MCP_CONTRACT = 'workbite.mcp.v1', CLI_CONTRACT = 'workstack.cli.v1';
+const WRITES = new Set(['agent.tasks.create', 'agent.tasks.update', 'agent.checkpoint']);
+// Owner error codes the native agent contract publishes; anything else is reported as internal_error.
+const KNOWN_ERRORS = new Set(['action_conflict', 'action_pending', 'backend_mismatch', 'capability_not_enabled',
+  'commit_unknown', 'context_too_large', 'generation_changed', 'idempotency_conflict', 'input_unreadable',
+  'internal_error', 'invalid_authority', 'invalid_body', 'invalid_receipt', 'invalid_response', 'journal_invalid',
+  'journal_unavailable', 'launcher_unavailable', 'not_configured', 'not_found', 'not_sent', 'offline',
+  'operation_refused', 'owner_disconnected', 'owner_unavailable', 'owner_upgrade_required', 'provider_unavailable',
+  'recovery_required', 'refused', 'rejected', 'request_conflict', 'review_pending', 'revision_conflict',
+  'room_mismatch', 'room_unavailable', 'selection_invalid', 'stale_task', 'store_sync_required', 'task_not_found',
+  'unauthorized', 'unknown_action', 'unknown_request', 'unsupported', 'wait_unsupported', 'workspace_mismatch']);
+const SECRET_KEY = /token|secret|password|passwd|authorization|cookie|csrf|credential|api[_-]?key/i;
+
+const MESSAGES = Object.freeze({
+  invalid_arguments: 'tool arguments violate the declared input schema; nothing was run',
+  workspace_mismatch: 'workspace_uid does not match the workspace this server is bound to; nothing was run',
+  binding_unavailable: 'no verified WorkBite workspace is bound to this server; open WorkBite and restart the MCP server',
+  not_sent: 'the request was refused before it reached the owner; nothing was written',
+  commit_unknown: 'the write may or may not be recorded; do not repeat it yet. First look up the SAME intent_id with '
+    + 'workbite_operation_status. committed: continue from that receipt. unknown with reason no_receipt: you may '
+    + 'resend once with the SAME intent_id and byte-identical arguments. Any other answer or reason: stop and '
+    + 'report it. Never switch to a new intent_id',
+  cli_output_invalid: 'the WorkBite agent answered without a valid bound envelope',
+  cli_usage_refused: 'the WorkBite agent refused the command line',
+  call_failed: 'the WorkBite agent call failed',
+});
+const INSTRUCTIONS = 'WorkBite tools act on the one WorkBite workspace bound when this server started; '
+  + 'changing the selected workspace later does not retarget them. Use workbite_status to see the bound '
+  + 'workspace and its workspace_uid. Create as many Tasks as the user asked for with workbite_tasks_create, one '
+  + 'call per Task, each with its own stable intent_id; no Task selection or extra confirmation is needed for '
+  + 'those. To read, update or checkpoint an EXISTING Task, list Tasks with workbite_tasks_list and act only on the '
+  + 'Task the user explicitly selected (workbite_context, workbite_tasks_update, workbite_checkpoint). Writes need '
+  + 'the bound workspace_uid and a caller-chosen intent_id that stays the SAME for the SAME change; updates also '
+  + 'need expected_revision from a fresh read. Calls run one at a time and are never retried automatically. After '
+  + 'commit_unknown, first look the SAME intent_id up with workbite_operation_status: continue from a committed '
+  + 'receipt; only unknown with reason no_receipt permits one resend with the SAME intent_id and byte-identical '
+  + 'arguments; on any other answer stop and report it.';
+
+const TASK_ID = { type: 'string', pattern: '^T-[0-9]{4,}$', maxLength: 64, description: 'Explicitly selected Task ID, for example T-0001' };
+const INTENT_ID = { type: 'string', pattern: '^[A-Za-z0-9._:-]{8,128}$',
+  description: 'Caller-chosen idempotency key, stable across retries of the SAME change' };
+const WORKSPACE_UID = { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$',
+  description: 'The bound workspace UID reported by workbite_status' };
+const ITEMS = { type: 'array', maxItems: 20, items: { type: 'string', maxLength: 1000 } };
+const object = (properties, required = []) => ({ type: 'object', additionalProperties: false, properties, required });
+const OUTPUT_SCHEMA = { type: 'object', required: ['contract', 'meta'], properties: {
+  contract: { type: 'string', enum: [CLI_CONTRACT, MCP_CONTRACT] }, data: { type: 'object' },
+  error: { type: 'object' }, meta: { type: 'object' }, workbite: { type: 'object' } } };
+
+const TOOLS = [
+  { name: 'workbite_status', command: 'agent.status', title: 'WorkBite status', readOnly: true,
+    description: 'Report whether the bound WorkBite workspace owner is ready, plus the bound workspace path and workspace_uid.',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID }) },
+  { name: 'workbite_tasks_list', command: 'agent.tasks.list', title: 'List WorkBite Tasks', readOnly: true,
+    description: 'List bounded Task metadata (id, title, status, revision) so the user can pick one Task. Never selects a Task.',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID,
+      status: { type: 'string', enum: ['active', 'all', 'open', 'started', 'done', 'dropped'], default: 'active' },
+      limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+      offset: { type: 'integer', minimum: 0, maximum: 1000000, default: 0 } }) },
+  { name: 'workbite_context', command: 'agent.context', title: 'Read one WorkBite Task context', readOnly: true,
+    description: 'Read the bounded context of one explicitly selected Task. view resume-v1 includes the latest checkpoint.',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID, task_id: TASK_ID,
+      view: { type: 'string', enum: ['core-v1', 'planning-v1', 'planning-v2', 'resume-v1'], default: 'core-v1' },
+      fingerprint: { type: 'boolean', default: false },
+      if_fingerprint: { type: 'string', pattern: '^v1:[0-9a-f]{64}$' } }, ['task_id']) },
+  { name: 'workbite_tasks_create', command: 'agent.tasks.create', title: 'Create one WorkBite Task', readOnly: false,
+    description: 'Create one Task. Durable per intent_id: the SAME intent_id with identical arguments replays the one created Task.',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID, intent_id: INTENT_ID,
+      title: { type: 'string', minLength: 1, maxLength: 32768 }, detail: { type: 'string', maxLength: 32768 },
+      follows_task_id: TASK_ID }, ['workspace_uid', 'intent_id', 'title']) },
+  { name: 'workbite_tasks_update', command: 'agent.tasks.update', title: 'Update one WorkBite Task', readOnly: false,
+    description: 'Change the detail and/or status of one Task read at expected_revision (compare-and-set). '
+      + 'A stale revision is revision_conflict and nothing is written.',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID, intent_id: INTENT_ID, task_id: TASK_ID,
+      expected_revision: { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+      changes: { type: 'object', additionalProperties: false, minProperties: 1, properties: {
+        detail: { type: 'string', maxLength: 32768 },
+        status: { type: 'string', enum: ['open', 'started', 'done', 'dropped'] } } } },
+    ['workspace_uid', 'intent_id', 'task_id', 'expected_revision', 'changes']) },
+  { name: 'workbite_checkpoint', command: 'agent.checkpoint', title: 'Append a WorkBite checkpoint', readOnly: false,
+    description: 'Append one Daily Review checkpoint to an explicitly selected Task. Idempotent per intent_id.',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID, intent_id: INTENT_ID, task_id: TASK_ID,
+      date: { type: 'string', pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$', description: 'ISO calendar date YYYY-MM-DD' },
+      done: ITEMS, next: ITEMS, blockers: ITEMS },
+    ['workspace_uid', 'intent_id', 'task_id', 'date', 'done', 'next', 'blockers']) },
+  { name: 'workbite_operation_status', command: 'agent.operation-status', title: 'Look up a WorkBite write receipt',
+    readOnly: true, description: 'Read-only lookup of the committed receipt of one intent_id. unknown never means "did not commit".',
+    inputSchema: object({ workspace_uid: WORKSPACE_UID, intent_id: INTENT_ID }, ['intent_id']) },
+];
+const BY_NAME = new Map(TOOLS.map(tool => [tool.name, tool]));
+const PACKET_KEYS = { 'agent.tasks.create': ['title', 'detail', 'follows_task_id'],
+  'agent.tasks.update': ['task_id', 'expected_revision', 'changes'],
+  'agent.checkpoint': ['task_id', 'date', 'done', 'next', 'blockers'] };
+
+const isPlain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+// The schema subset above, enforced server side; the first violation is reported.
+function violation(value, schema, where) {
+  switch (schema.type) {
+    case 'object': {
+      if (!isPlain(value)) return `${where} must be an object`;
+      for (const key of schema.required || []) if (!Object.hasOwn(value, key)) return `${where}.${key} is required`;
+      if (Object.keys(value).length < (schema.minProperties || 0)) return `${where} has too few properties`;
+      for (const [key, item] of Object.entries(value)) {
+        if (!Object.hasOwn(schema.properties, key)) return `${where} has unknown property ${JSON.stringify(key.slice(0, 64))}`;
+        const problem = violation(item, schema.properties[key], `${where}.${key}`);
+        if (problem) return problem;
+      }
+      return null;
+    }
+    case 'array': {
+      if (!Array.isArray(value)) return `${where} must be an array`;
+      if (value.length > schema.maxItems) return `${where} has too many items`;
+      for (let index = 0; index < value.length; index++) {
+        const problem = violation(value[index], schema.items, `${where}[${index}]`);
+        if (problem) return problem;
+      }
+      return null;
+    }
+    case 'integer':
+      if (!Number.isSafeInteger(value)) return `${where} must be an integer`;
+      if (value < schema.minimum || value > schema.maximum) return `${where} is out of range`;
+      return null;
+    case 'boolean': return typeof value === 'boolean' ? null : `${where} must be a boolean`;
+    case 'string': {
+      if (typeof value !== 'string') return `${where} must be a string`;
+      if (value.includes('\0') || value.isWellFormed?.() === false) return `${where} is not valid text`;
+      const length = [...value].length;
+      if (length < (schema.minLength || 0) || length > (schema.maxLength ?? Infinity)) return `${where} has an invalid length`;
+      if (schema.enum && !schema.enum.includes(value)) return `${where} is not an allowed value`;
+      if (schema.pattern && !new RegExp(schema.pattern).test(value)) return `${where} has an invalid format`;
+      return null;
+    }
+    default: return `${where} has an unsupported schema`;
+  }
+}
+
+// Native agent argv for the pinned workstack-native-client `cli.execute`; packets travel on stdin only.
+// The command words come immediately after `agent` (agent.js commandOf reads them up to the first flag);
+// the bound workspace UID follows them as an identity flag that the native parser checks position-free.
+function nativeRequest(tool, args, uid) {
+  const argv = ['agent', ...tool.command.split('.').slice(1), '--workspace-uid', uid];
+  let stdin;
+  switch (tool.command) {
+    case 'agent.status': break;
+    case 'agent.tasks.list':
+      argv.push(`--status=${args.status ?? 'active'}`, `--limit=${args.limit ?? 20}`, `--offset=${args.offset ?? 0}`);
+      break;
+    case 'agent.context':
+      argv.push(`--task=${args.task_id}`, `--view=${args.view ?? 'core-v1'}`, '--format=json');
+      if (args.fingerprint === true) argv.push('--fingerprint');
+      if (args.if_fingerprint !== undefined) argv.push(`--if-fingerprint=${args.if_fingerprint}`);
+      break;
+    case 'agent.operation-status': argv.push(`--intent-id=${args.intent_id}`); break;
+    default: {
+      argv.push(`--intent-id=${args.intent_id}`, '--stdin');
+      const packet = {};
+      for (const key of PACKET_KEYS[tool.command]) if (Object.hasOwn(args, key)) packet[key] = args[key];
+      stdin = JSON.stringify(packet);
+    }
+  }
+  return { argv, stdin };
+}
+
+function redact(value) {
+  if (Array.isArray(value)) return value.map(redact);
+  if (!isPlain(value)) return value;
+  const out = {};
+  for (const [key, item] of Object.entries(value)) out[key] = SECRET_KEY.test(key) ? '[redacted]' : redact(item);
+  return out;
+}
+function adapterError(command, code, args, extra = {}) {
+  const meta = { command };
+  if (args && typeof args.intent_id === 'string') meta.intent_id = args.intent_id;
+  if (args && typeof args.task_id === 'string') meta.task_id = args.task_id;
+  if (code === 'commit_unknown') meta.commit_state = 'unknown';
+  const error = { code, message: MESSAGES[code], retryable: false };
+  if (extra.reason) error.details = { reason: extra.reason };
+  return { contract: MCP_CONTRACT, error, meta };
+}
+function parseEnvelope(text) {
+  if (typeof text !== 'string' || Buffer.byteLength(text) > LIMITS.stdout || !text.endsWith('\n')
+      || text.indexOf('\n') !== text.length - 1) return null;
+  try { const value = JSON.parse(text); return isPlain(value) ? value : null; } catch { return null; }
+}
+// The envelope must answer this command for this workspace (and this intent when one was sent).
+function bound(envelope, tool, args, uid, success) {
+  const meta = envelope.meta;
+  if (envelope.contract !== CLI_CONTRACT || !isPlain(meta) || meta.command !== tool.command) return false;
+  if (meta.intent_id !== undefined && args.intent_id !== undefined && meta.intent_id !== args.intent_id) return false;
+  if (success) return isPlain(envelope.data) && envelope.error === undefined && meta.workspace_uid === uid;
+  return isPlain(envelope.error) && typeof envelope.error.code === 'string' && envelope.data === undefined
+    && (meta.workspace_uid === undefined || meta.workspace_uid === null || meta.workspace_uid === uid);
+}
+
+function createServer({ agent, bindOptions, stderr }) {
+  let initialized = false, version = LATEST_VERSION;
+  let binding;
+  const log = message => { try { stderr.write(`workbite mcp: ${message}\n`); } catch { /* stderr closed */ } };
+  // Resolved once per process; a later selection change cannot retarget this server.
+  const pinned = (async () => {
+    try {
+      const value = await agent().bindAgent({ ...bindOptions });
+      if (!value || typeof value.workspaceUid !== 'string' || typeof value.workspace !== 'string') throw new Error('invalid binding');
+      binding = Object.freeze(value);
+      return binding;
+    } catch (error) {
+      log(`no verified workspace binding (${errorCode(error)})`);
+      return null;
+    }
+  })();
+
+  function toolResult(envelope, isError) {
+    const clean = redact(envelope);
+    const result = { content: [{ type: 'text', text: JSON.stringify(clean) }], isError };
+    if (version >= STRUCTURED_SINCE) result.structuredContent = clean;
+    return result;
+  }
+  function describe(tool) {
+    const out = { name: tool.name, description: tool.description, inputSchema: tool.inputSchema };
+    if (version >= STRUCTURED_SINCE) { out.title = tool.title; out.outputSchema = OUTPUT_SCHEMA; }
+    if (version >= ANNOTATIONS_SINCE) {
+      out.annotations = { title: tool.title, readOnlyHint: tool.readOnly, destructiveHint: false,
+        idempotentHint: true, openWorldHint: false };
+    }
+    return out;
+  }
+
+  async function call(tool, args) {
+    const problem = violation(args, tool.inputSchema, 'arguments');
+    if (problem) return toolResult(adapterError(tool.command, 'invalid_arguments', null, { reason: problem }), true);
+    const target = await pinned;
+    if (!target) return toolResult(adapterError(tool.command, 'binding_unavailable', args), true);
+    if (args.workspace_uid !== undefined && args.workspace_uid !== target.workspaceUid) {
+      return toolResult(adapterError(tool.command, 'workspace_mismatch', args), true);
+    }
+    const request = nativeRequest(tool, args, target.workspaceUid);
+    if (request.stdin !== undefined && Buffer.byteLength(request.stdin) > LIMITS.packet) {
+      return toolResult(adapterError(tool.command, 'invalid_arguments', null,
+        { reason: `packet exceeds ${LIMITS.packet} bytes` }), true);
+    }
+    const write = WRITES.has(tool.command);
+    let native;
+    try {
+      native = await agent().executeAgent(target, request.argv, request.stdin === undefined ? {} : { stdin: request.stdin });
+    } catch (error) {
+      const code = errorCode(error);
+      log(`${tool.name} failed (${code})`);
+      // A write that may have been sent has an unknown outcome; it is never replayed here.
+      if (write && code !== 'not_sent' && error?.sent !== false) {
+        return toolResult(adapterError(tool.command, 'commit_unknown', args), true);
+      }
+      const reported = write ? 'not_sent' : (KNOWN_ERRORS.has(code) ? code : 'call_failed');
+      return toolResult({ contract: MCP_CONTRACT, error: { code: reported, message: MESSAGES[reported] || reported,
+        retryable: false }, meta: { command: tool.command, ...(args.intent_id ? { intent_id: args.intent_id } : {}) } }, true);
+    }
+    const invalid = () => toolResult(adapterError(tool.command, write ? 'commit_unknown' : 'cli_output_invalid', args), true);
+    if (!isPlain(native) || ![0, 1, 2].includes(native.code)) return invalid();
+    if (typeof native.stderr === 'string' && native.stderr && Buffer.byteLength(native.stderr) > LIMITS.stderr) return invalid();
+    const envelope = parseEnvelope(native.stdout);
+    if (!envelope) {
+      // Exit 2 without an envelope is a usage refusal before any request was admitted.
+      if (native.code === 2 && !native.stdout) return toolResult(adapterError(tool.command, 'cli_usage_refused', args), true);
+      return invalid();
+    }
+    if (!bound(envelope, tool, args, target.workspaceUid, native.code === 0)) return invalid();
+    if (native.code === 0) {
+      if (tool.command === 'agent.status') {
+        envelope.workbite = { workspace: target.workspace, workspace_uid: target.workspaceUid,
+          ...(typeof target.endpoint === 'string' ? { endpoint: target.endpoint } : {}) };
+      }
+      return toolResult(envelope, false);
+    }
+    if (!KNOWN_ERRORS.has(envelope.error.code)) envelope.error = { ...envelope.error, code: 'internal_error' };
+    return toolResult(envelope, true);
+  }
+
+  const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+  const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+  // One message, or one 2025-03-26 batch run element by element in order (never concurrently).
+  // A batch answers only its requests; a batch of notifications gets no response at all.
+  async function receive(message) {
+    if (!Array.isArray(message)) return answer(message, false);
+    if (!initialized || version !== BATCH_VERSION) {
+      return failure(null, -32600, `Invalid Request: JSON-RPC batches are accepted only under protocol ${BATCH_VERSION}`);
+    }
+    if (!message.length) return failure(null, -32600, 'Invalid Request: empty batch');
+    if (message.length > LIMITS.batch) return failure(null, -32600, `Invalid Request: batch exceeds ${LIMITS.batch} messages`);
+    const replies = [];
+    for (const item of message) {
+      const result = await answer(item, true);
+      if (result) replies.push(result);
+    }
+    return replies.length ? replies : null;
+  }
+  async function answer(message, batched) {
+    try { return await handle(message, batched); } catch (error) {
+      log(`internal error (${errorCode(error)})`);
+      return failure(isPlain(message) && (typeof message.id === 'string' || Number.isSafeInteger(message.id)) ? message.id : null,
+        -32603, 'Internal error');
+    }
+  }
+
+  async function handle(message, batched) {
+    if (!isPlain(message)) return failure(null, -32600, 'Invalid Request');
+    const hasId = Object.hasOwn(message, 'id');
+    const id = hasId ? message.id : null;
+    if (hasId && !(typeof id === 'string' || Number.isSafeInteger(id))) {
+      return failure(null, -32600, 'Invalid Request: id must be a string or integer');
+    }
+    if (message.jsonrpc !== '2.0') return failure(id, -32600, 'Invalid Request');
+    if (message.method === undefined && hasId && (Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error'))) return null;
+    if (typeof message.method !== 'string') return failure(id, -32600, 'Invalid Request');
+    if (!hasId) return null; // notifications (initialized, cancelled, …) need no answer; running calls are not cancelled
+    const params = message.params === undefined ? {} : message.params;
+    if (!isPlain(params)) return failure(id, -32602, 'Invalid params: params must be an object');
+    switch (message.method) {
+      case 'ping': return reply(id, {});
+      case 'initialize': {
+        if (batched) return failure(id, -32600, 'Invalid Request: initialize must not be part of a batch');
+        if (initialized) return failure(id, -32600, 'Invalid Request: already initialized');
+        if (typeof params.protocolVersion !== 'string' || !isPlain(params.capabilities) || !isPlain(params.clientInfo)) {
+          return failure(id, -32602, 'Invalid params: initialize');
+        }
+        version = SUPPORTED_VERSIONS.includes(params.protocolVersion) ? params.protocolVersion : LATEST_VERSION;
+        initialized = true;
+        return reply(id, { protocolVersion: version, capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'workbite', version: packageVersion() }, instructions: INSTRUCTIONS });
+      }
+      case 'tools/list':
+        if (!initialized) return failure(id, -32600, 'Invalid Request: server not initialized');
+        if (params.cursor !== undefined && params.cursor !== null && typeof params.cursor !== 'string') {
+          return failure(id, -32602, 'Invalid params: cursor');
+        }
+        return reply(id, { tools: TOOLS.map(describe) });
+      case 'tools/call': {
+        if (!initialized) return failure(id, -32600, 'Invalid Request: server not initialized');
+        const tool = typeof params.name === 'string' ? BY_NAME.get(params.name) : undefined;
+        if (!tool) return failure(id, -32602, 'Unknown tool');
+        const args = params.arguments === undefined ? {} : params.arguments;
+        if (!isPlain(args)) return failure(id, -32602, 'Invalid params: arguments must be an object');
+        return reply(id, await call(tool, args));
+      }
+      default: return failure(id, -32601, 'Method not found');
+    }
+  }
+  return { receive, pinned, log };
+}
+
+function errorCode(error) {
+  const code = error && typeof error.code === 'string' ? error.code : '';
+  return /^[a-z_]{1,64}$/.test(code) ? code : 'internal_error';
+}
+function packageVersion() {
+  try { return require('../package.json').version; } catch { return '0.0.0'; }
+}
+
+const tooLarge = id => ({ jsonrpc: '2.0', id: id ?? null, error: { code: -32603,
+  message: 'Internal error: response too large; look up any write with workbite_operation_status' } });
+// One output line of at most LIMITS.message bytes; an oversized batch reply shrinks element by element.
+function encode(message) {
+  const text = JSON.stringify(message);
+  if (Buffer.byteLength(text) + 1 <= LIMITS.message) return text;
+  if (!Array.isArray(message)) return JSON.stringify(tooLarge(message.id));
+  const parts = [];
+  let size = 3;
+  for (const item of message) {
+    let part = JSON.stringify(item);
+    if (size + Buffer.byteLength(part) + 1 > LIMITS.message) part = JSON.stringify(tooLarge(item.id));
+    parts.push(part); size += Buffer.byteLength(part) + 1;
+  }
+  return `[${parts.join(',')}]`;
+}
+
+// Serves until stdin ends, then finishes the queued messages. Always resolves {code:0, signal:null}.
+// options.metrics (optional object) receives queue high-water marks for tests.
+async function runMcp(options = {}) {
+  const stdin = options.stdin || process.stdin, stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const metrics = options.metrics && typeof options.metrics === 'object' ? options.metrics : {};
+  Object.assign(metrics, { queueHighWater: 0, queueBytesHighWater: 0, paused: 0 });
+  let module = options.agent;
+  const agent = () => module || (module = require('./agent'));
+  const bindOptions = {};
+  for (const key of ['installed', 'stateRoot', 'environment', 'workspace', 'workspaceUid']) {
+    if (options[key] !== undefined) bindOptions[key] = options[key];
+  }
+  const server = createServer({ agent, bindOptions, stderr });
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+
+  // Output: one response at a time; the next message is not processed until stdout drains.
+  let open = true, wake = null;
+  const closed = () => { open = false; if (wake) wake(); };
+  stdout.on?.('error', closed);
+  stdout.on?.('close', closed);
+  const send = async message => {
+    if (!open || !message) return;
+    let accepted;
+    try { accepted = stdout.write(`${encode(message)}\n`); } catch { open = false; return; }
+    if (accepted || !open) return;
+    await new Promise(resolve => {
+      wake = () => { stdout.removeListener('drain', wake); wake = null; resolve(); };
+      stdout.on('drain', wake);
+    });
+  };
+  const serve = async (bytes, oversize) => {
+    if (oversize) return send({ jsonrpc: '2.0', id: null,
+      error: { code: -32600, message: `Invalid Request: message exceeds ${LIMITS.message} bytes` } });
+    let text;
+    try { text = decoder.decode(bytes); } catch { return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); }
+    if (!text.trim()) return undefined;
+    let message;
+    try { message = JSON.parse(text); } catch { return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); }
+    return send(await server.receive(message));
+  };
+
+  // Input: complete lines wait in a bounded queue; when it is full the rest of the chunk is kept as
+  // `carry` and stdin is paused until the worker makes room. Nothing accepted is dropped.
+  const queue = [];
+  let queuedBytes = 0, carry = null, ended = false, working = false, skipped = 0, finish;
+  let pending = [], size = 0, oversize = false;
+  const done = new Promise(resolve => { finish = resolve; });
+  const room = length => queue.length === 0 || (queue.length < LIMITS.queue && queuedBytes + length <= LIMITS.queueBytes);
+  const consume = buffer => {
+    for (let index = buffer.indexOf(10); index !== -1; index = buffer.indexOf(10)) {
+      const part = buffer.subarray(0, index);
+      const over = oversize || size + part.length > LIMITS.message;
+      const length = over ? 0 : size + part.length;
+      if (!room(length)) return buffer;
+      let line = over ? null : Buffer.concat([...pending, part]);
+      if (line && line[line.length - 1] === 13) line = line.subarray(0, -1);
+      queue.push({ line, oversize: over, length });
+      queuedBytes += length;
+      metrics.queueHighWater = Math.max(metrics.queueHighWater, queue.length);
+      metrics.queueBytesHighWater = Math.max(metrics.queueBytesHighWater, queuedBytes);
+      pending = []; size = 0; oversize = false;
+      buffer = buffer.subarray(index + 1);
+    }
+    if (!buffer.length) return null;
+    if (oversize || size + buffer.length > LIMITS.message) { oversize = true; pending = []; size = 0; return null; }
+    pending.push(Buffer.from(buffer)); size += buffer.length;
+    return null;
+  };
+  const flow = () => {
+    if (carry) carry = consume(carry);
+    if (carry || queue.length >= LIMITS.queue) {
+      if (!stdin.isPaused?.()) { stdin.pause(); metrics.paused++; }
+    } else if (!ended) stdin.resume();
+  };
+  const work = async () => {
+    if (working) return;
+    working = true;
+    while (queue.length) {
+      const item = queue.shift();
+      queuedBytes -= item.length;
+      flow();
+      if (!open) { skipped++; continue; } // nobody can read the answer: queued work is not started
+      await serve(item.line, item.oversize);
+    }
+    working = false;
+    if (ended && !carry) finish();
+  };
+  stdin.on('data', chunk => {
+    const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+    carry = carry ? Buffer.concat([carry, buffer]) : buffer;
+    flow();
+    work();
+  });
+  const end = () => { ended = true; flow(); if (!working && !queue.length && !carry) finish(); else work(); };
+  stdin.on('end', end);
+  stdin.on('close', end);
+  stdin.on('error', error => { server.log(`stdin error (${errorCode(error)})`); end(); });
+  await done;
+  if (size || oversize) server.log('discarded an incomplete final line');
+  if (skipped) server.log(`stdout closed; ${skipped} queued message(s) were not run`);
+  if (wake) wake();
+  await server.pinned;
+  return { code: 0, signal: null };
+}
+
+module.exports = { runMcp, TOOLS, SUPPORTED_VERSIONS, LIMITS, nativeRequest, violation };

package/lib/runtime.js

@@ -17,6 +17,7 @@ const BACKEND_SCHEMA = 'stackbite.workstack-backend.v1';
 const CONNECTION_SCHEMA = 'workstack.helm-connection.v1';
 const OWNER_SCHEMA = 'workbite.owner.v2';
 const STACKBITE_SCHEMA = 'workbite.stackbite-backend.v2';
+const SELECTION_SCHEMA = 'workbite.workspace-selection.v1';
 const LOOPBACK = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/;
 // Ports of the existing official StackBite and its previews are never chosen.
 const RESERVED_PORTS = new Set([8089, 8090, 8091, 54036, 54039, 54236, 54239]);
@@ -46,7 +47,8 @@ function stateLayout(root) {
   return { root, stackbite: path.join(root, 'stackbite'), workstackRuntime: path.join(root, 'workstack-runtime'),
     journal: path.join(root, 'deploy-journal'), tuiState: path.join(root, 'workstack-tui'), owners: path.join(root, 'owners'),
     logs: path.join(root, 'logs'), dock: path.join(root, 'execution-dock.json'),
-    stackbiteRecord: path.join(root, 'stackbite-backend.json'), lock: path.join(root, 'open.lock') };
+    stackbiteRecord: path.join(root, 'stackbite-backend.json'), lock: path.join(root, 'open.lock'),
+    selection: path.join(root, 'last-workspace.json') };
 }
 async function prepareState(layout) {
   for (const directory of [layout.root, layout.stackbite, layout.workstackRuntime, layout.journal, layout.tuiState,
@@ -118,6 +120,58 @@ async function initializeWorkspace(commands, workspace, environment) {
   return uid;
 }
 
+// The workspace a bare `workbite` reopens: the last one opened successfully, or, for
+// state from 0.1.0 with no saved selection, the single owner record it holds. It is
+// never guessed (no CWD, mtime or default folder) and never silently replaced by
+// another workspace; the genuine workspace.json id must still match.
+const EXPLICIT = 'Open it once with: workbite open --workspace ABS';
+async function currentUid(workspace, what) {
+  try { return await readWorkspaceUid(workspace); } catch (error) {
+    fail(`The ${what} ${workspace} is missing, moved or no longer a valid Work Stack workspace (${error.message}) ${EXPLICIT}`);
+  }
+}
+async function rememberedWorkspace(layout) {
+  let saved;
+  try { saved = await readJson(layout.selection, 8192); } catch (error) {
+    if (error.code !== 'ENOENT') fail(`The saved workspace selection ${layout.selection} is unreadable. ${EXPLICIT}`);
+    return ownerWorkspace(layout);
+  }
+  if (saved === null || typeof saved !== 'object' || Array.isArray(saved) || Object.keys(saved).length !== 3
+      || saved.schema !== SELECTION_SCHEMA || typeof saved.workspace !== 'string' || !path.isAbsolute(saved.workspace)
+      || typeof saved.workspace_uid !== 'string' || !UUID.test(saved.workspace_uid)) {
+    fail(`The saved workspace selection ${layout.selection} is invalid. ${EXPLICIT}`);
+  }
+  if (await currentUid(saved.workspace, 'last opened workspace') !== saved.workspace_uid) {
+    fail(`The last opened workspace ${saved.workspace} was replaced (its workspace.json id changed); WorkBite does not open it silently. ${EXPLICIT}`);
+  }
+  return { workspace: saved.workspace, uid: saved.workspace_uid };
+}
+async function ownerWorkspace(layout) {
+  let names = [];
+  try { names = (await fs.readdir(layout.owners)).filter(name => /^[0-9a-f]{24}\.json$/.test(name)); } catch (error) {
+    if (error.code !== 'ENOENT') fail(`WorkBite owner records are unreadable. ${EXPLICIT}`);
+  }
+  if (!names.length) fail(`No workspace has been opened yet. ${EXPLICIT} (add --init for a new or empty folder).`);
+  if (names.length > 1) fail(`WorkBite has ${names.length} workspace owner records and will not guess which one to open. ${EXPLICIT}`);
+  const file = path.join(layout.owners, names[0]);
+  let record;
+  try { record = await readJson(file); } catch { fail(`The Work Stack owner record ${file} is unreadable. ${EXPLICIT}`); }
+  if (!isRecord(record) || record.schema !== OWNER_SCHEMA || typeof record.workspace !== 'string' || !path.isAbsolute(record.workspace)
+      || `${workspaceKey(record.workspace)}.json` !== names[0] || typeof record.workspace_uid !== 'string' || !UUID.test(record.workspace_uid)) {
+    fail(`The Work Stack owner record ${file} is not a valid owner record. ${EXPLICIT}`);
+  }
+  if (await currentUid(record.workspace, 'workspace recorded in the owner record') !== record.workspace_uid) {
+    fail(`The workspace recorded in ${file} was replaced (its workspace.json id changed); WorkBite does not open it silently. ${EXPLICIT}`);
+  }
+  return { workspace: record.workspace, uid: record.workspace_uid };
+}
+async function rememberWorkspace(layout, workspace, uid) {
+  const bytes = Buffer.from(JSON.stringify({ schema: SELECTION_SCHEMA, workspace, workspace_uid: uid }, null, 2) + '\n');
+  let current = null;
+  try { current = await readSmall(layout.selection, 8192); } catch { current = null; }
+  if (!current || !current.equals(bytes)) await writeAtomic(layout.selection, bytes);
+}
+
 function request(url, { method = 'GET', headers = {}, body, timeout = 5000 } = {}) {
   const match = LOOPBACK.exec(url.origin);
   if (!match) return Promise.reject(new Error('not a loopback origin'));
@@ -370,18 +424,27 @@ function runForeground(command, args, environment, { spawnImpl = spawn, signalSo
 // commands maps each bundle executable to its argv prefix; tests substitute fixtures.
 async function openSuite({ installed, commands, workspace, init = false, stateRoot, environment = process.env,
   ui = true, spawnImpl = spawn, stdout = process.stdout, timeouts = {} }) {
-  workspace = checkedWorkspace(workspace);
+  if (workspace !== undefined) workspace = checkedWorkspace(workspace);
+  else if (init) fail('--init needs --workspace ABS naming the new or empty folder');
   commands = commands || Object.fromEntries(Object.entries(installed.executables).map(([name, file]) => [name, [file]]));
   const layout = stateLayout(path.resolve(stateRoot));
   await prepareState(layout);
   const base = cleanEnvironment(environment);
   const engineEnvironment = { ...base, WORK_STACK_RUNTIME: layout.workstackRuntime };
   const session = await withLock(layout.lock, async () => {
+    let remembered = null;
+    if (workspace === undefined) {
+      remembered = await rememberedWorkspace(layout);
+      workspace = checkedWorkspace(remembered.workspace);
+    }
     const uid = init ? await initializeWorkspace(commands, workspace, engineEnvironment) : await readWorkspaceUid(workspace);
+    if (remembered && uid !== remembered.uid) fail(`The workspace ${workspace} changed while opening. ${EXPLICIT}`);
     const backendId = await ensureBackendId(layout);
     const engine = await ensureEngine({ commands, workspace, uid, layout, environment: engineEnvironment, spawnImpl, timeout: timeouts.engine });
     const stackbite = await ensureStackbite({ commands, layout, backendId, environment: base, spawnImpl, timeout: timeouts.stackbite });
     await writeDockConfig(layout, stackbite.url);
+    // Only after the owner, StackBite and dock config are proven ready, and before the UI.
+    await rememberWorkspace(layout, workspace, uid);
     return { uid, backendId, engine, stackbite };
   });
   const summary = { schema: 'workbite.open.v1', workspace, workspace_uid: session.uid, endpoint: session.engine.endpoint,
@@ -399,4 +462,4 @@ async function openSuite({ installed, commands, workspace, init = false, stateRo
 
 module.exports = { cleanEnvironment, stateLayout, prepareState, ensureBackendId, workspaceKey, readWorkspaceUid,
   initializeWorkspace, engineIdentity, stackbiteIdentity, freePort, ensureEngine, ensureStackbite, writeDockConfig,
-  withLock, uiEnvironment, openSuite, RESERVED_PORTS };
+  withLock, uiEnvironment, openSuite, rememberedWorkspace, RESERVED_PORTS, SELECTION_SCHEMA };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workbite",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WorkBite (Work Stack + StackBite) verified native suite installer and launcher",
   "license": "UNLICENSED",
   "engines": {
@@ -19,6 +19,7 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     "release.json",
     "README.md"
   ],

package/release.json

@@ -2,6 +2,7 @@
   "schema": "workbite.release.v1",
   "product": "WorkBite",
   "version": "0.1.0",
+  "launcherVersion": "0.1.2",
   "repository": "Shinick-Han/WorkBite-releases",
   "tag": "v0.1.0",
   "platforms": {