@jaimevalasek/aioson 1.7.2 → 1.8.0

package/src/agents.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const { AGENT_DEFINITIONS } = require('./constants');
-const { getLocalizedAgentPath } = require('./locales');
 
 function normalizeAgentName(input) {
   return String(input || '')
@@ -23,18 +22,37 @@ function listAgentDefinitions() {
 }
 
 function resolveInstructionPath(agent, locale) {
-  if (!locale) return agent.path;
-  return getLocalizedAgentPath(agent.id, locale);
+  return agent.path;
 }
 
 function buildAgentPrompt(agent, tool, options = {}) {
   const safeTool = String(tool || 'codex').toLowerCase();
   const instructionPath = options.instructionPath || agent.path;
   const targetDir = options.targetDir ? String(options.targetDir) : '.';
+  const interactionLanguage = String(options.interactionLanguage || 'en');
+  const autonomyMode = String(options.autonomyMode || '').trim();
+  const capabilitySummary = String(options.capabilitySummary || '').trim();
+  const activationContext = String(options.activationContext || '').trim();
   const dependencyText =
     agent.dependsOn.length > 0
       ? `Check required context files first: ${agent.dependsOn.join(', ')}.`
       : 'No prerequisite context files are required.';
+  const activationBlock = activationContext
+    ? [
+      '',
+      '## Activation Context',
+      '',
+      activationContext
+    ].join('\n')
+    : '';
+
+  const autonomyBlock = [
+    '',
+    '## Autonomy Contract',
+    '',
+    `**Autonomy mode:** ${autonomyMode || 'guarded'}. Respect this as the maximum automation level allowed for this activation.`,
+    capabilitySummary ? `**Capability summary:** ${capabilitySummary}` : '**Capability summary:** No manifest declared for this agent in the current workspace.'
+  ].join('\n');
 
   const lifecycleBlock = [
     '',
@@ -45,22 +63,24 @@ function buildAgentPrompt(agent, tool, options = {}) {
     '',
     '> If the user needs dashboard-visible tracked execution in an external client, they must enter through `aioson workflow:next` or `aioson agent:prompt` before continuing.',
     '',
+    `**Language boundary:** Agent instructions are canonical in English. All user-facing communication must be in ${interactionLanguage}.`,
+    '',
     `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.`,
   ].join('\n');
 
   if (safeTool === 'claude') {
-    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText} Write output to ${agent.output}.${lifecycleBlock}`;
+    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock} Write output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
   }
 
   if (safeTool === 'gemini') {
-    return `Run the Gemini command mapped to ${instructionPath} and execute ${agent.command}. ${dependencyText} Save result to ${agent.output}.${lifecycleBlock}`;
+    return `Run the Gemini command mapped to ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock} Save result to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
   }
 
   if (safeTool === 'opencode') {
-    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText} Save output to ${agent.output}.${lifecycleBlock}`;
+    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock} Save output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
   }
 
-  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText} Save output to ${agent.output}.${lifecycleBlock}`;
+  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock} Save output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
 }
 
 module.exports = {

package/src/autonomy-policy.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { exists } = require('./utils');
+
+const AUTONOMY_PROTOCOL_RELATIVE_PATH = '.aioson/config/autonomy-protocol.json';
+const MODES = ['guarded', 'trusted', 'headless'];
+
+function buildDefaultProtocol() {
+  return {
+    version: '1.0',
+    global_mode: 'guarded',
+    tools: {},
+    agents: {}
+  };
+}
+
+function normalizeMode(mode, fallback = 'guarded') {
+  const safe = String(mode || '').trim().toLowerCase();
+  return MODES.includes(safe) ? safe : fallback;
+}
+
+async function readAutonomyProtocol(targetDir) {
+  const protocolPath = path.join(targetDir, AUTONOMY_PROTOCOL_RELATIVE_PATH);
+  if (!(await exists(protocolPath))) return buildDefaultProtocol();
+
+  try {
+    const raw = await fs.readFile(protocolPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      ...buildDefaultProtocol(),
+      ...parsed,
+      global_mode: normalizeMode(parsed.global_mode, 'guarded'),
+      tools: parsed.tools && typeof parsed.tools === 'object' ? parsed.tools : {},
+      agents: parsed.agents && typeof parsed.agents === 'object' ? parsed.agents : {}
+    };
+  } catch {
+    return buildDefaultProtocol();
+  }
+}
+
+function getToolPolicy(protocol, tool) {
+  const safeTool = String(tool || 'codex').trim().toLowerCase();
+  const policy = protocol && protocol.tools && typeof protocol.tools === 'object'
+    ? protocol.tools[safeTool]
+    : null;
+  const rawFallbackMode = String(policy && policy.fallback_mode ? policy.fallback_mode : 'guarded').trim().toLowerCase();
+
+  return {
+    mode: normalizeMode(policy && policy.mode, protocol && protocol.global_mode ? protocol.global_mode : 'guarded'),
+    fallback_mode: ['guarded', 'headless', 'abort'].includes(rawFallbackMode) ? rawFallbackMode : 'guarded',
+    shell_whitelist: Array.isArray(policy && policy.shell_whitelist) ? policy.shell_whitelist : [],
+    shell_blacklist: Array.isArray(policy && policy.shell_blacklist) ? policy.shell_blacklist : [],
+    aioson_whitelist: Array.isArray(policy && policy.aioson_whitelist) ? policy.aioson_whitelist : [],
+    requires_tty: policy && Object.prototype.hasOwnProperty.call(policy, 'requires_tty')
+      ? Boolean(policy.requires_tty)
+      : true,
+    max_auto_retries: Number.isInteger(policy && policy.max_auto_retries) ? policy.max_auto_retries : 3
+  };
+}
+
+function getAgentPolicy(protocol, agentId) {
+  if (!protocol || !protocol.agents || typeof protocol.agents !== 'object') return {};
+  return protocol.agents[String(agentId || '').trim()] || {};
+}
+
+function getMostPermissiveMode(modes, fallback = 'guarded') {
+  if (!Array.isArray(modes) || modes.length === 0) return fallback;
+  let bestIndex = MODES.indexOf(normalizeMode(fallback, 'guarded'));
+  for (const mode of modes) {
+    const index = MODES.indexOf(normalizeMode(mode, fallback));
+    if (index > bestIndex) bestIndex = index;
+  }
+  return MODES[bestIndex];
+}
+
+function getAgentMaxMode(protocol, agentId, manifest = null) {
+  const agentPolicy = getAgentPolicy(protocol, agentId);
+  if (agentPolicy && agentPolicy.max_mode) {
+    return normalizeMode(agentPolicy.max_mode, 'guarded');
+  }
+  if (manifest && Array.isArray(manifest.autonomy_modes) && manifest.autonomy_modes.length > 0) {
+    return getMostPermissiveMode(manifest.autonomy_modes, 'guarded');
+  }
+  return normalizeMode(protocol && protocol.global_mode, 'guarded');
+}
+
+function resolveEffectiveMode({ protocol, tool, agentId, manifest = null, requestedMode = null }) {
+  const toolPolicy = getToolPolicy(protocol || buildDefaultProtocol(), tool);
+  const toolMode = normalizeMode(toolPolicy.mode, 'guarded');
+  const agentMode = getAgentMaxMode(protocol || buildDefaultProtocol(), agentId, manifest);
+
+  const toolIndex = MODES.indexOf(toolMode);
+  const agentIndex = MODES.indexOf(agentMode);
+  const baseIndex = Math.min(toolIndex, agentIndex);
+
+  if (!requestedMode) return MODES[baseIndex];
+
+  const requestedIndex = MODES.indexOf(normalizeMode(requestedMode, 'guarded'));
+  return MODES[Math.min(baseIndex, requestedIndex)];
+}
+
+function matchPattern(value, pattern) {
+  const escaped = String(pattern || '')
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`, 'i').test(String(value || ''));
+}
+
+function isCommandAllowed(policy, commandType, commandString) {
+  if (!policy) return false;
+  const safeType = String(commandType || '').trim().toLowerCase();
+  const whitelist = Array.isArray(policy[`${safeType}_whitelist`]) ? policy[`${safeType}_whitelist`] : [];
+  const blacklist = Array.isArray(policy[`${safeType}_blacklist`]) ? policy[`${safeType}_blacklist`] : [];
+
+  for (const pattern of blacklist) {
+    if (matchPattern(commandString, pattern)) return false;
+  }
+
+  if (whitelist.length === 0) return true;
+  return whitelist.some((pattern) => matchPattern(commandString, pattern));
+}
+
+function canRunHeadless(policy) {
+  return Boolean(policy) && policy.requires_tty === false;
+}
+
+module.exports = {
+  AUTONOMY_PROTOCOL_RELATIVE_PATH,
+  MODES,
+  readAutonomyProtocol,
+  getToolPolicy,
+  getAgentPolicy,
+  getAgentMaxMode,
+  resolveEffectiveMode,
+  isCommandAllowed,
+  canRunHeadless
+};

package/src/brain-query.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+function splitCsv(value) {
+  return String(value || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function normalizeBrainPath(targetDir, brainPath) {
+  const raw = String(brainPath || '').trim();
+  if (!raw) return null;
+  if (path.isAbsolute(raw)) return raw;
+  if (raw.startsWith('.aioson/brains/')) return path.join(targetDir, raw);
+  return path.join(targetDir, '.aioson', 'brains', raw);
+}
+
+async function readJsonFile(filePath) {
+  const content = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(content);
+}
+
+function brainMatches({ brain, tags, agent }) {
+  if (agent) {
+    const agents = Array.isArray(brain.agents) ? brain.agents : [];
+    if (!agents.includes(agent)) return false;
+  }
+  if (tags.length > 0) {
+    const brainTags = Array.isArray(brain.tags) ? brain.tags : [];
+    if (!tags.some((tag) => brainTags.includes(tag))) return false;
+  }
+  return true;
+}
+
+function nodeMatches({ node, tags, matchMode, minQuality, verdicts, ids, avoidOnly }) {
+  if (ids.length > 0) return ids.includes(node.id);
+
+  const nodeTags = Array.isArray(node.tags) ? node.tags : [];
+  if (tags.length > 0) {
+    const ok = matchMode === 'all'
+      ? tags.every((tag) => nodeTags.includes(tag))
+      : tags.some((tag) => nodeTags.includes(tag));
+    if (!ok) return false;
+  }
+
+  if (minQuality > 0 && Number(node.q || 0) < minQuality) return false;
+
+  if (verdicts.length > 0) {
+    const verdict = String(node.v || '').toUpperCase();
+    if (!verdicts.includes(verdict)) return false;
+  }
+
+  if (avoidOnly) {
+    const verdict = String(node.v || '').toUpperCase();
+    if (verdict !== 'AVOID' && verdict !== 'BROKEN') return false;
+  }
+
+  return true;
+}
+
+async function queryBrains({
+  targetDir,
+  tags = [],
+  matchMode = 'any',
+  minQuality = 0,
+  agent = '',
+  verdicts = [],
+  ids = [],
+  avoidOnly = false
+}) {
+  const brainsDir = path.join(targetDir, '.aioson', 'brains');
+  const indexPath = path.join(brainsDir, '_index.json');
+
+  let index;
+  try {
+    index = await readJsonFile(indexPath);
+  } catch {
+    return {
+      ok: false,
+      reason: 'missing_index',
+      indexPath,
+      brainFiles: [],
+      nodes: [],
+      warnings: [`No _index.json found at ${indexPath}`]
+    };
+  }
+
+  const requestedTags = Array.isArray(tags) ? tags : splitCsv(tags);
+  const requestedVerdicts = (Array.isArray(verdicts) ? verdicts : splitCsv(verdicts))
+    .map((verdict) => verdict.toUpperCase());
+  const requestedIds = Array.isArray(ids) ? ids : splitCsv(ids);
+  const requestedAgent = String(agent || '').replace(/^@/, '').trim();
+  const normalizedMatchMode = matchMode === 'all' ? 'all' : 'any';
+  const minQ = Number(minQuality || 0);
+
+  const indexedBrains = Array.isArray(index.brains) ? index.brains : [];
+  const selectedBrains = indexedBrains.filter((brain) => brainMatches({
+    brain,
+    tags: requestedTags,
+    agent: requestedAgent
+  }));
+
+  const warnings = [];
+  const nodes = [];
+
+  for (const brain of selectedBrains) {
+    const brainPath = normalizeBrainPath(targetDir, brain.path);
+    if (!brainPath) {
+      warnings.push(`Brain ${brain.id || '(unknown)'} has no path`);
+      continue;
+    }
+
+    let data;
+    try {
+      data = await readJsonFile(brainPath);
+    } catch {
+      warnings.push(`Brain file not found or invalid: ${brainPath}`);
+      continue;
+    }
+
+    const brainNodes = Array.isArray(data.nodes) ? data.nodes : [];
+    for (const node of brainNodes) {
+      if (nodeMatches({
+        node,
+        tags: requestedTags,
+        matchMode: normalizedMatchMode,
+        minQuality: minQ,
+        verdicts: requestedVerdicts,
+        ids: requestedIds,
+        avoidOnly
+      })) {
+        nodes.push({ ...node, _brain: brain.id || null, _brain_path: brain.path || null });
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    indexPath,
+    brainFiles: selectedBrains.map((brain) => brain.path),
+    nodes,
+    warnings
+  };
+}
+
+function formatBrainNodesCompact(nodes) {
+  if (!nodes || nodes.length === 0) return '(no matches)';
+  return nodes
+    .map((node) => `[${node.q || 0}* ${node.v || 'UNKNOWN'}] ${node.id} - ${node.title}\n  ${node.s || ''}`.trimEnd())
+    .join('\n\n');
+}
+
+module.exports = {
+  splitCsv,
+  normalizeBrainPath,
+  queryBrains,
+  formatBrainNodesCompact
+};