@borgee/agents-host 0.2.33 → 0.2.44

package/skills/borgee-agent/scripts/borgee-agent.mjs

@@ -0,0 +1,553 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+
+const MANUAL = `borgee-agent — read the Borgee channel this turn runs in, and act on its tasks.
+
+Usage:
+  borgee-agent --gateway <absolute path> <command> [arguments]
+  borgee-agent --help
+
+Commands:
+  health
+      Gateway reachability.
+  bootstrap
+      Channel bootstrap snapshot.
+  whoami
+      This agent's identity in this channel.
+  history [--limit <n>] [--before <n>] [--after <n>]
+      Recent messages in this channel.
+  users
+      Participants visible in this channel.
+  draft --turn-execution-id <id>
+      This turn's host-private in-flight draft.
+  send --body <text> --turn-execution-id <id> (--reply-to <message-id> | --mention <user-id>)...
+      Post a short auxiliary message. It must address someone.
+  mention <user-id> --body <text> --turn-execution-id <id> [--reply-to <message-id>]
+      Post a short auxiliary message addressed to one participant.
+  task list
+      Tasks in this channel. Parent channel only.
+  task create --title <text> [--description <text>] [--assignee-id <user-id>]
+      Create a task. Parent channel only.
+  task get [<task-id>]
+      One task with its properties.
+  task update [<task-id>] [--status <open|in_progress|in_review|done|cancelled>] [--title <text>] [--description <text>] [--assignee-id <user-id>]
+      Update the task. At least one field is required.
+  task history <task-id> [--limit <n>] [--before <n>] [--after <n>]
+      Messages in that task's thread.
+  task set-property [<task-id>] --key <key> --value <value>
+      Set one task property.
+  task delete-property [<task-id>] --key <key>
+      Remove one task property.
+
+Inside a task thread every task command with an optional task id acts on this thread's own task when the id is omitted, and task list / task create are refused there. In a parent channel the task id is required.
+
+Exit codes: 0 success, 1 gateway failure, 2 usage error.
+
+The full manual, including the task property registry and the error table, is SKILL.md in this skill directory.`;
+
+// A window value outside the IEEE-754 safe integer range does not survive this CLI: it parses the
+// value to a number and re-stringifies it into the query string, so `1000000000000000000000`
+// leaves as `1e+21` and the gateway's `Number.parseInt(value, 10)` reads it back as `1` — a
+// different page, silently. Both packaged CLIs accept exactly this grammar.
+const INTEGER_ARGUMENT_PATTERN = /^[+-]?[0-9]+$/;
+
+// Spelled out instead of `\s` because the Python CLI must trim arguments and append the mention
+// separator on exactly the same inputs, and the two languages disagree on U+00A0, U+3000, U+FEFF
+// and U+001C…U+001F.
+const PORTABLE_WHITESPACE = ' \t\n\r\f\v';
+
+function trimArgument(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && PORTABLE_WHITESPACE.includes(value[start])) {
+    start += 1;
+  }
+  while (end > start && PORTABLE_WHITESPACE.includes(value[end - 1])) {
+    end -= 1;
+  }
+  return value.slice(start, end);
+}
+
+const COMMANDS = new Set([
+  'health',
+  'bootstrap',
+  'whoami',
+  'history',
+  'users',
+  'draft',
+  'send',
+  'mention',
+  'task',
+]);
+
+const TASK_COMMANDS = new Set([
+  'list',
+  'create',
+  'get',
+  'update',
+  'history',
+  'set-property',
+  'delete-property',
+]);
+
+class UsageError extends Error {}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && trimArgument(value).length > 0;
+}
+
+function parseArgs(argv) {
+  const positionals = [];
+  const mentions = [];
+  let gatewayCredentialPath;
+  let turnExecutionId;
+  let limit;
+  let before;
+  let after;
+  let body;
+  let replyToId;
+  let title;
+  let description;
+  let assigneeId;
+  let status;
+  let propertyKey;
+  let propertyValue;
+  let index = 0;
+
+  const takeValue = (flag) => {
+    index += 1;
+    if (index >= argv.length) {
+      throw new UsageError(`Missing value after ${flag}`);
+    }
+    return argv[index];
+  };
+
+  const takeInteger = (flag) => {
+    const value = takeValue(flag);
+    if (!INTEGER_ARGUMENT_PATTERN.test(value)) {
+      throw new UsageError(`Invalid integer for ${flag}: ${value}`);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+      throw new UsageError(`Integer out of range for ${flag}: ${value}`);
+    }
+    return parsed;
+  };
+
+  for (; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      return { help: true };
+    }
+    if (!arg.startsWith('-')) {
+      positionals.push(arg);
+      continue;
+    }
+    switch (arg) {
+      case '--gateway':
+        gatewayCredentialPath = takeValue(arg);
+        break;
+      case '--turn-execution-id':
+        turnExecutionId = trimArgument(takeValue(arg));
+        break;
+      case '--limit':
+        limit = takeInteger(arg);
+        break;
+      case '--before':
+        before = takeInteger(arg);
+        break;
+      case '--after':
+        after = takeInteger(arg);
+        break;
+      case '--body':
+        body = takeValue(arg);
+        break;
+      case '--reply-to':
+        replyToId = takeValue(arg);
+        break;
+      case '--mention': {
+        const mention = trimArgument(takeValue(arg));
+        if (mention.length === 0) {
+          throw new UsageError('Missing value after --mention');
+        }
+        mentions.push(mention);
+        break;
+      }
+      case '--title':
+        title = takeValue(arg);
+        break;
+      case '--description':
+        description = takeValue(arg);
+        break;
+      case '--assignee-id':
+        assigneeId = takeValue(arg);
+        break;
+      case '--status':
+        status = takeValue(arg);
+        break;
+      case '--key':
+        propertyKey = trimArgument(takeValue(arg));
+        break;
+      case '--value':
+        propertyValue = takeValue(arg);
+        break;
+      default:
+        throw new UsageError(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (positionals.length === 0) {
+    return { help: false, command: null };
+  }
+  const command = positionals[0];
+  if (!COMMANDS.has(command)) {
+    throw new UsageError(`Unknown command: ${command}`);
+  }
+
+  let taskCommand = null;
+  let taskId = null;
+  let mentionTargetId = null;
+  let consumed = 1;
+  if (command === 'task') {
+    if (positionals.length < 2) {
+      throw new UsageError(
+        'Missing task command; expected one of list, create, get, update, history, set-property, delete-property',
+      );
+    }
+    taskCommand = positionals[1];
+    if (!TASK_COMMANDS.has(taskCommand)) {
+      throw new UsageError(`Unknown task command: ${taskCommand}`);
+    }
+    consumed = 2;
+    if (taskCommand !== 'list' && taskCommand !== 'create' && positionals.length > consumed) {
+      taskId = trimArgument(positionals[consumed]);
+      // Only an absent positional may mean the thread's own task. Treating an empty one as absent
+      // would send a write the caller meant for a named task to whatever task the thread resolves.
+      if (taskId.length === 0) {
+        throw new UsageError(
+          `Empty task id for "task ${taskCommand}"; pass a task id or omit the argument entirely`,
+        );
+      }
+      consumed += 1;
+    }
+  } else if (command === 'mention' && positionals.length > consumed) {
+    mentionTargetId = trimArgument(positionals[consumed]);
+    consumed += 1;
+  }
+  if (positionals.length > consumed) {
+    throw new UsageError(`Unexpected argument: ${positionals[consumed]}`);
+  }
+
+  if (gatewayCredentialPath === undefined) {
+    throw new UsageError('Missing required --gateway <path> argument');
+  }
+  if (!isAbsolute(gatewayCredentialPath)) {
+    throw new UsageError(`--gateway requires an absolute path: ${gatewayCredentialPath}`);
+  }
+
+  return {
+    help: false,
+    command,
+    taskCommand,
+    taskId,
+    mentionTargetId,
+    gatewayCredentialPath,
+    turnExecutionId,
+    limit,
+    before,
+    after,
+    body,
+    replyToId,
+    mentions,
+    title,
+    description,
+    assigneeId,
+    status,
+    propertyKey,
+    propertyValue,
+  };
+}
+
+function commandLabel(parsed) {
+  return parsed.command === 'task' ? `task ${parsed.taskCommand}` : parsed.command;
+}
+
+function requireText(value, flag, label) {
+  if (!isNonEmptyString(value)) {
+    throw new UsageError(`Missing required ${flag} <value> for "${label}"`);
+  }
+}
+
+function validateCommand(parsed) {
+  const label = commandLabel(parsed);
+  if (parsed.command === 'draft') {
+    requireText(parsed.turnExecutionId, '--turn-execution-id', label);
+    return;
+  }
+  if (parsed.command === 'send') {
+    requireText(parsed.body, '--body', label);
+    requireText(parsed.turnExecutionId, '--turn-execution-id', label);
+    return;
+  }
+  if (parsed.command === 'mention') {
+    if (!isNonEmptyString(parsed.mentionTargetId)) {
+      throw new UsageError('Missing required user id for "mention"');
+    }
+    if (parsed.mentions.length > 0) {
+      throw new UsageError('Do not combine the mention command with --mention flags');
+    }
+    requireText(parsed.body, '--body', label);
+    requireText(parsed.turnExecutionId, '--turn-execution-id', label);
+    return;
+  }
+  if (parsed.command !== 'task') {
+    return;
+  }
+  if (parsed.taskCommand === 'create') {
+    requireText(parsed.title, '--title', label);
+    return;
+  }
+  if (parsed.taskCommand === 'update') {
+    const updated = [parsed.status, parsed.title, parsed.description, parsed.assigneeId];
+    if (updated.every((value) => value === undefined)) {
+      throw new UsageError(
+        'At least one of --status, --title, --description or --assignee-id is required for "task update"',
+      );
+    }
+    return;
+  }
+  if (parsed.taskCommand === 'history') {
+    if (parsed.taskId === null) {
+      throw new UsageError('Missing required task id for "task history"');
+    }
+    return;
+  }
+  if (parsed.taskCommand === 'set-property') {
+    requireText(parsed.propertyKey, '--key', label);
+    // An empty property value is a legitimate string, so presence of the flag is the requirement.
+    if (parsed.propertyValue === undefined) {
+      throw new UsageError('Missing required --value <value> for "task set-property"');
+    }
+    return;
+  }
+  if (parsed.taskCommand === 'delete-property') {
+    requireText(parsed.propertyKey, '--key', label);
+  }
+}
+
+// The credential path is used exactly as handed over: no walk-up, no glob, no environment lookup.
+// Task workspaces live inside the git repository and are not gitignored, so any search would
+// traverse attacker-influenceable directories where a planted file could redirect the gateway base
+// URL or point at another channel's credentials.
+async function readGatewayCredential(gatewayCredentialPath) {
+  let bytes;
+  try {
+    bytes = await readFile(gatewayCredentialPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new UsageError(`Gateway credential file not found: ${gatewayCredentialPath}`);
+    }
+    throw error;
+  }
+  let payload;
+  try {
+    // Decoded strictly: a lone replacement character would silently mangle the channel id the
+    // request is issued against, and the Python CLI refuses the same bytes.
+    payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  } catch {
+    throw new UsageError(`${gatewayCredentialPath} is not a Borgee gateway credential`);
+  }
+  const channelId = payload?.channelId;
+  const baseUrl = payload?.localhostGateway?.baseUrl;
+  const token = payload?.localhostGateway?.token;
+  if (!isNonEmptyString(channelId) || !isNonEmptyString(baseUrl) || !isNonEmptyString(token)) {
+    throw new UsageError(`${gatewayCredentialPath} is not a Borgee gateway credential`);
+  }
+  return { channelId, baseUrl: baseUrl.replace(/\/+$/u, ''), token };
+}
+
+function ensureVisibleMention(body, participantId) {
+  if (body.includes(`<@${participantId}>`)) {
+    return body;
+  }
+  const lastCharacter = body.slice(-1);
+  const separator = PORTABLE_WHITESPACE.includes(lastCharacter) ? '' : ' ';
+  return `${body}${separator}<@${participantId}>`;
+}
+
+function ensureVisibleMentions(body, participantIds) {
+  return participantIds.reduce(
+    (nextBody, participantId) => ensureVisibleMention(nextBody, participantId),
+    body,
+  );
+}
+
+function buildQuery(entries) {
+  const parts = entries
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`);
+  return parts.length > 0 ? `?${parts.join('&')}` : '';
+}
+
+function historyQuery(parsed) {
+  return buildQuery([
+    ['limit', parsed.limit],
+    ['before', parsed.before],
+    ['after', parsed.after],
+  ]);
+}
+
+function buildMessageBody(parsed) {
+  const mentions = parsed.command === 'mention' ? [parsed.mentionTargetId] : parsed.mentions;
+  const requestBody = {
+    body: mentions.length > 0 ? ensureVisibleMentions(parsed.body, mentions) : parsed.body,
+    turnExecutionId: parsed.turnExecutionId,
+  };
+  const replyToId = typeof parsed.replyToId === 'string' ? trimArgument(parsed.replyToId) : '';
+  if (replyToId.length > 0) {
+    requestBody.replyToId = replyToId;
+  }
+  return requestBody;
+}
+
+function buildTaskCreateBody(parsed) {
+  return {
+    title: parsed.title,
+    ...(parsed.description !== undefined ? { description: parsed.description } : {}),
+    ...(parsed.assigneeId !== undefined ? { assigneeId: parsed.assigneeId } : {}),
+  };
+}
+
+function buildTaskUpdateBody(parsed) {
+  return {
+    ...(parsed.status !== undefined ? { status: parsed.status } : {}),
+    ...(parsed.title !== undefined ? { title: parsed.title } : {}),
+    ...(parsed.description !== undefined ? { description: parsed.description } : {}),
+    ...(parsed.assigneeId !== undefined ? { assigneeId: parsed.assigneeId } : {}),
+  };
+}
+
+// Which task a bare `task` verb addresses is the gateway's decision, taken from the token binding:
+// in a task thread `current-task` resolves that thread's task, and in a parent channel it answers
+// not_found. The CLI therefore never inspects the turn's task assignment state.
+function resolveTaskRequest(parsed, baseUrl, channel) {
+  if (parsed.taskCommand === 'list') {
+    return { url: `${baseUrl}/v1/channels/${channel}/tasks`, method: 'GET', body: null };
+  }
+  if (parsed.taskCommand === 'create') {
+    return {
+      url: `${baseUrl}/v1/channels/${channel}/tasks`,
+      method: 'POST',
+      body: buildTaskCreateBody(parsed),
+    };
+  }
+  if (parsed.taskCommand === 'history') {
+    return {
+      url: `${baseUrl}/v1/tasks/${encodeURIComponent(parsed.taskId)}/history${historyQuery(parsed)}`,
+      method: 'GET',
+      body: null,
+    };
+  }
+  const taskUrl =
+    parsed.taskId === null
+      ? `${baseUrl}/v1/channels/${channel}/current-task`
+      : `${baseUrl}/v1/tasks/${encodeURIComponent(parsed.taskId)}`;
+  if (parsed.taskCommand === 'get') {
+    return { url: taskUrl, method: 'GET', body: null };
+  }
+  if (parsed.taskCommand === 'update') {
+    return { url: taskUrl, method: 'PATCH', body: buildTaskUpdateBody(parsed) };
+  }
+  const propertyUrl = `${taskUrl}/properties/${encodeURIComponent(parsed.propertyKey)}`;
+  if (parsed.taskCommand === 'set-property') {
+    return { url: propertyUrl, method: 'PUT', body: { value: parsed.propertyValue } };
+  }
+  return { url: propertyUrl, method: 'DELETE', body: null };
+}
+
+function resolveRequest(credential, parsed) {
+  const baseUrl = credential.baseUrl;
+  const channel = encodeURIComponent(credential.channelId);
+  if (parsed.command === 'health') {
+    return { url: `${baseUrl}/health`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'bootstrap') {
+    return { url: `${baseUrl}/v1/channels/${channel}/bootstrap`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'whoami') {
+    return { url: `${baseUrl}/v1/channels/${channel}/me`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'history') {
+    return {
+      url: `${baseUrl}/v1/channels/${channel}/history${historyQuery(parsed)}`,
+      method: 'GET',
+      body: null,
+    };
+  }
+  if (parsed.command === 'users') {
+    return { url: `${baseUrl}/v1/channels/${channel}/users`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'draft') {
+    const query = buildQuery([['turnExecutionId', parsed.turnExecutionId]]);
+    return { url: `${baseUrl}/v1/channels/${channel}/draft${query}`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'send' || parsed.command === 'mention') {
+    return {
+      url: `${baseUrl}/v1/channels/${channel}/messages`,
+      method: 'POST',
+      body: buildMessageBody(parsed),
+    };
+  }
+  return resolveTaskRequest(parsed, baseUrl, channel);
+}
+
+async function callGateway(credential, request) {
+  const headers = { authorization: `Bearer ${credential.token}` };
+  // The gateway has no redirect routes, so a 3xx means something other than the gateway answered.
+  // Following it would carry the channel token off the loopback address, so it is reported instead.
+  const httpRequest = { method: request.method, headers, redirect: 'manual' };
+  if (request.body !== null) {
+    headers['content-type'] = 'application/json; charset=utf-8';
+    httpRequest.body = JSON.stringify(request.body);
+  }
+  let response;
+  try {
+    response = await fetch(request.url, httpRequest);
+  } catch (error) {
+    throw new Error(
+      `Cannot reach the localhost gateway at ${credential.baseUrl}: ${error.cause?.message ?? error.message}`,
+    );
+  }
+  const bodyText = await response.text();
+  const responseBody = bodyText.length > 0 ? JSON.parse(bodyText) : null;
+  if (!response.ok) {
+    throw new Error(`Gateway request failed with ${response.status}: ${JSON.stringify(responseBody)}`);
+  }
+  return responseBody;
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help === true) {
+    process.stdout.write(`${MANUAL}\n`);
+    return 0;
+  }
+  if (parsed.command === null) {
+    process.stderr.write(`${MANUAL}\n`);
+    return 2;
+  }
+  validateCommand(parsed);
+  const credential = await readGatewayCredential(parsed.gatewayCredentialPath);
+  const result = await callGateway(credential, resolveRequest(credential, parsed));
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  process.stderr.write(`error: ${error.message}\n`);
+  process.exitCode = error instanceof UsageError ? 2 : 1;
+}