@aifabrix/builder 2.59.0 → 2.61.2

package/docs/builder-help/resource-type-catalog.json

@@ -0,0 +1,402 @@
+{
+  "schemaVersion": "1.0.0",
+  "source": "baseline-resourcetypes.json",
+  "lastSynced": "2026-08-22",
+  "minimumSystemKeys": [
+    "customer",
+    "contact",
+    "employee",
+    "project",
+    "task",
+    "meeting",
+    "document",
+    "approval",
+    "contract",
+    "invoice",
+    "deal",
+    "ticket",
+    "message",
+    "channel",
+    "workspace",
+    "knowledge",
+    "event"
+  ],
+  "resourceTypes": [
+    {
+      "key": "approval",
+      "displayName": "Approval",
+      "description": "Approval request, decision, review process, or authorization workflow item.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "asset",
+      "displayName": "Asset",
+      "description": "Managed physical, digital, financial, or operational business asset.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "attachment",
+      "displayName": "Attachment",
+      "description": "File attachment, uploaded content, supporting artifact, or binary business asset.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "balance",
+      "displayName": "Balance",
+      "description": "Leave, absence, or accrued time-off balance for a person.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "budget",
+      "displayName": "Budget",
+      "description": "Budget allocation, financial plan, spending target, or funding record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "case",
+      "displayName": "Case",
+      "description": "Support request, incident, issue, service ticket, or customer problem record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "channel",
+      "displayName": "Channel",
+      "description": "Collaboration channel, team space, or communication group.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "contact",
+      "displayName": "Contact",
+      "description": "Individual person associated with a customer, supplier, partner, or other business entity.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "contract",
+      "displayName": "Contract",
+      "description": "Formal agreement, legal commitment, or business contract between parties.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "customer",
+      "displayName": "Customer",
+      "description": "Organization, account, client, or business entity that purchases, receives, or is associated with products or services.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "deal",
+      "displayName": "Deal",
+      "description": "Commercial deal, sales opportunity, or revenue pursuit in the sales pipeline.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "decision",
+      "displayName": "Decision",
+      "description": "Business decision, resolution, approved action, or governance outcome.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "department",
+      "displayName": "Department",
+      "description": "Organizational unit, business function, or department.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "document",
+      "displayName": "Document",
+      "description": "Business document, file, presentation, contract, or knowledge artifact.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "folder",
+      "displayName": "Folder",
+      "description": "Container or directory for documents and files.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "hr-report",
+      "displayName": "HR Report",
+      "description": "People and HR report, workforce analytics rollup, or period summary. Distinct from Document.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "email",
+      "displayName": "Email",
+      "description": "Email message, conversation, or business communication record.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "employee",
+      "displayName": "Employee",
+      "description": "Internal worker, staff member, contractor, or workforce resource.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "event",
+      "displayName": "Event",
+      "description": "Business event, calendar event, milestone, or scheduled activity.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "expense",
+      "displayName": "Expense",
+      "description": "Expense claim, cost record, reimbursement, or financial expenditure.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "finance-report",
+      "displayName": "Finance Report",
+      "description": "Financial report, analytics rollup, or period summary over finance records. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "invoice",
+      "displayName": "Invoice",
+      "description": "Billing document, payment request, or financial charge record.",
+      "category": "business",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "knowledge",
+      "displayName": "Knowledge",
+      "description": "Knowledge article, FAQ, guidance, procedure, or reference content.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "llm",
+      "displayName": "LLM",
+      "description": "Large language model provider capability surface for chat completion and embedding operations.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "meeting",
+      "displayName": "Meeting",
+      "description": "Scheduled interaction, discussion, workshop, or business event involving participants.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "message",
+      "displayName": "Message",
+      "description": "Chat, Teams message, discussion, or conversational communication record.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "note",
+      "displayName": "Note",
+      "description": "Business note, comment, activity note, CRM note, or user-generated contextual information.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "objective",
+      "displayName": "Objective",
+      "description": "Strategic goal, business objective, target outcome, or organizational priority.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "opportunity",
+      "displayName": "Opportunity",
+      "description": "Potential sales, revenue, business development, or commercial opportunity.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "operations-report",
+      "displayName": "Operations Report",
+      "description": "Operations report, operational analytics rollup, or period summary. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "order",
+      "displayName": "Order",
+      "description": "Customer order, purchase request, sales order, or transaction record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "organization",
+      "displayName": "Organization",
+      "description": "Internal organizational entity, subsidiary, legal entity, or business unit.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "owner",
+      "displayName": "Owner",
+      "description": "Individual user or account responsible for ownership, stewardship, or accountability of a record or business object.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "partner",
+      "displayName": "Partner",
+      "description": "External organization participating in business collaboration, delivery, sales, or strategic activities.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "payment",
+      "displayName": "Payment",
+      "description": "Payment transaction, settlement, receipt, or financial payment record.",
+      "category": "business",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "policy",
+      "displayName": "Policy",
+      "description": "Policy, guideline, compliance rule, or governance document.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "position",
+      "displayName": "Position",
+      "description": "Job role, position, title, or workforce assignment.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "product",
+      "displayName": "Product",
+      "description": "Product, service offering, subscription, or item available for sale or delivery.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "project",
+      "displayName": "Project",
+      "description": "Temporary initiative or work effort with defined objectives, timelines, resources, and deliverables.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "repository",
+      "displayName": "Repository",
+      "description": "Version-controlled source repository for integration manifests, CIP pipelines, and workspace sync.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "risk",
+      "displayName": "Risk",
+      "description": "Potential business, operational, compliance, security, or financial risk.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "sales-report",
+      "displayName": "Sales Report",
+      "description": "Sales report, pipeline analytics rollup, or commercial period summary. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "supplier",
+      "displayName": "Supplier",
+      "description": "Organization providing products, services, materials, or external resources.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "task",
+      "displayName": "Task",
+      "description": "Work item, action, assignment, or activity that can be completed by an individual or team.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "template",
+      "displayName": "Template",
+      "description": "Integration workspace template used to materialize local Builder workspaces.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "ticket",
+      "displayName": "Ticket",
+      "description": "Support ticket, service request, incident, or customer issue record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "workspace",
+      "displayName": "Workspace",
+      "description": "Shared workspace, site, or collaboration area for teams and content.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    }
+  ]
+}

package/lib/agent-kit/git-identity.js

@@ -0,0 +1,180 @@
+/**
+ * Git commit identity for onboarding and Agent Kit GitHub work.
+ *
+ * Resolution order:
+ *   1. Existing `git config` — never rewritten, because it is the user's own setting.
+ *   2. The AI Fabrix login token's claims, offered as editable defaults.
+ *   3. The prompt answer, written to git config.
+ *
+ * The GitHub token is deliberately not used for the address: `gh api user` returns null whenever
+ * the account keeps its email private, and reading `user/emails` would demand the broader `user`
+ * scope for a value the login token already holds.
+ *
+ * @fileoverview Resolve and persist git user.name / user.email
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const logger = require('../utils/logger');
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * @param {Function} exec - execFileSync
+ * @param {string} key - Config key
+ * @param {boolean} global - Read the global scope only
+ * @returns {string} Trimmed value or ''
+ */
+function readConfig(exec, key, global) {
+  try {
+    const args = global ? ['config', '--global', '--get', key] : ['config', '--get', key];
+    return String(exec('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Current identity, preferring any effective value (local or global) over none.
+ * @param {Object} [options] - `execFileSync`
+ * @returns {{ name: string, email: string, complete: boolean }}
+ */
+function readGitIdentity(options = {}) {
+  const exec = options.execFileSync || execFileSync;
+  const name = readConfig(exec, 'user.name', false);
+  const email = readConfig(exec, 'user.email', false);
+  return { name, email, complete: Boolean(name && email) };
+}
+
+function decodeJwtClaims(token) {
+  const raw = String(token || '');
+  const parts = raw.split('.');
+  if (parts.length < 2) return null;
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Name and email from the AI Fabrix login token, used as prompt defaults.
+ * @param {Object} [options] - `config` and `controller` overrides for tests
+ * @returns {Promise<{ name: string, email: string }>} Empty strings when unavailable
+ */
+async function identityFromLoginToken(options = {}) {
+  const config = options.config || require('../core/config');
+  try {
+    const controller = options.controller || (await config.getControllerUrl());
+    if (!controller) return { name: '', email: '' };
+    const entry = await config.getDeviceToken(controller);
+    const claims = decodeJwtClaims(entry && (entry.token || entry.accessToken));
+    if (!claims) return { name: '', email: '' };
+    return {
+      name: String(claims.name || '').trim(),
+      email: String(claims.email || claims.preferred_username || '').trim()
+    };
+  } catch {
+    return { name: '', email: '' };
+  }
+}
+
+/**
+ * @param {Object} [options] - `config`
+ * @returns {Promise<string>} adminEmail from config.yaml, or ''
+ */
+async function emailFromConfig(options = {}) {
+  const config = options.config || require('../core/config');
+  try {
+    const cfg = await config.getConfig();
+    return String((cfg && cfg.adminEmail) || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {string} value - Candidate address
+ * @returns {boolean|string} true, or the reason it is rejected
+ */
+function validateEmail(value) {
+  return EMAIL_RE.test(String(value || '').trim()) || 'Enter an email address, for example name@example.com';
+}
+
+function validateName(value) {
+  return String(value || '').trim().length > 0 || 'Enter the name to record on commits';
+}
+
+async function promptIdentity(defaults, deps) {
+  const inquirer = deps.inquirer || require('inquirer');
+  return inquirer.prompt([
+    {
+      type: 'input',
+      name: 'name',
+      message: 'Name for git commits',
+      default: defaults.name || undefined,
+      validate: validateName
+    },
+    {
+      type: 'input',
+      name: 'email',
+      message: 'Email for git commits',
+      default: defaults.email || undefined,
+      validate: validateEmail
+    }
+  ]);
+}
+
+function writeGitIdentity(identity, options) {
+  const exec = options.execFileSync || execFileSync;
+  exec('git', ['config', '--global', 'user.name', identity.name], { stdio: 'ignore' });
+  exec('git', ['config', '--global', 'user.email', identity.email], { stdio: 'ignore' });
+}
+
+function missingIdentityError(defaults) {
+  const name = defaults.name || 'Your Name';
+  const email = defaults.email || 'you@example.com';
+  return new Error(
+    'Git commit identity is not configured. Run:\n' +
+    `  git config --global user.name ${JSON.stringify(name)}\n` +
+    `  git config --global user.email ${email}`
+  );
+}
+
+/**
+ * Ensures git has a commit identity, asking only when one is missing.
+ * @param {Object} [options] - `interactive`, `execFileSync`, `inquirer`, `config`
+ * @returns {Promise<{ name: string, email: string, source: 'git'|'prompt' }>}
+ */
+async function ensureGitIdentity(options = {}) {
+  const current = readGitIdentity(options);
+  if (current.complete) {
+    return { name: current.name, email: current.email, source: 'git' };
+  }
+  const token = await identityFromLoginToken(options);
+  const defaults = {
+    name: current.name || token.name,
+    email: current.email || token.email || (await emailFromConfig(options))
+  };
+  if (!options.interactive) {
+    throw missingIdentityError(defaults);
+  }
+  logger.log('Git commit identity is not set. Defaults come from your AI Fabrix login; edit if needed.');
+  const answers = await promptIdentity(defaults, options);
+  const identity = { name: String(answers.name).trim(), email: String(answers.email).trim() };
+  writeGitIdentity(identity, options);
+  logger.log(`Git identity set to ${identity.name} <${identity.email}>`);
+  return { ...identity, source: 'prompt' };
+}
+
+module.exports = {
+  readGitIdentity,
+  identityFromLoginToken,
+  emailFromConfig,
+  ensureGitIdentity,
+  validateEmail,
+  validateName
+};

package/lib/agent-kit/setup.js

@@ -8,6 +8,7 @@ const { auditLog } = require('../core/audit-logger');
 const { normalizeSetup, preflight, resolveWork } = require('./setup-context');
 const { acquireWorkspace } = require('./setup-state');
 const { ensureController, ensureGithubLogin, ensureProvider } = require('./setup-auth');
+const { ensureGitIdentity } = require('./git-identity');
 const { prepareWorkspace, validateExisting } = require('./setup-workspace');
 const { prepareSession, attachSession } = require('./setup-session');
 const { managedSetupOptions } = require('./setup-managed');
@@ -19,6 +20,8 @@ async function authenticate(context, options, setPhase) {
   if (context.fullName) {
     setPhase('github-login');
     ensureGithubLogin(options);
+    // Commits need an author. The login token supplies the default; the user can change it.
+    await ensureGitIdentity({ ...options, interactive: options.interactive !== false });
   }
   if (context.code === 'cursor') return null;
   setPhase('agent-login');

package/lib/agent-kit/start.js

@@ -116,6 +116,27 @@ function claudeInnerArgs(p) {
   ]);
 }
 
+/**
+ * POSIX single-quote escaping for a value sent to a shell via tmux send-keys.
+ * @param {string} value - Raw value
+ * @returns {string} Quoted value
+ */
+function shellQuote(value) {
+  const escaped = String(value).split('\'').join('\'\\\'\'');
+  return `'${escaped}'`;
+}
+
+/**
+ * Codex authenticates inside the session, not in the window that launched it. Running it as the
+ * tmux session command makes the session end with the sign-in process, so the shell owns the
+ * window and codex is started inside it with send-keys.
+ * @param {object} p - Start parameters
+ * @returns {string} Shell command to run inside the session
+ */
+function codexStartCommand(p) {
+  return p.binary ? `exec ${shellQuote(p.binary)}` : 'exec codex';
+}
+
 /**
  * @param {object} p
  * @returns {object}
@@ -127,12 +148,17 @@ function buildTmuxSpec(p) {
     ? ['new-session', '-d', '-s', p.session, '-c', p.cwd]
     : ['new-session', '-s', p.session, '-c', p.cwd];
   const remote = p.app === 'claude' && p.remoteControl;
+  // codex: shell owns the window, codex starts inside it (see codexStartCommand).
+  const launchArgs = p.app === 'codex'
+    ? [...mode]
+    : [...mode, ...(p.binary ? ['env', p.binary] : [spec.bin]), ...extra];
   return {
     bin: 'tmux',
-    args: [...mode, ...(p.binary ? ['env', p.binary] : [spec.bin]), ...extra],
+    args: launchArgs,
     session: p.session,
     appBin: spec.bin,
     needTmux: true,
+    innerCommand: p.app === 'codex' ? codexStartCommand(p) : undefined,
     remoteControlName: remote ? p.remoteControlName : undefined,
     remoteControlPrefix: remote ? p.remoteControlPrefix : undefined
   };
@@ -333,6 +359,22 @@ function executeStart(options, context, execute) {
     startCodexRemote(options, context.remoteSpec);
   }
   spawnLaunch(options, context.spec);
+  sendInnerCommand(options, context.spec);
+}
+
+/**
+ * Starts the agent inside an existing session window. Only codex uses this; the session must exist
+ * first, which is why it runs after the launch.
+ * @param {object} options - Start options
+ * @param {object} spec - Launch spec
+ * @returns {void}
+ */
+function sendInnerCommand(options, spec) {
+  if (!spec.innerCommand) {
+    return;
+  }
+  const exec = options.execFileSync || execFileSync;
+  exec('tmux', ['send-keys', '-t', `=${spec.session}`, spec.innerCommand, 'Enter'], { stdio: 'inherit' });
 }
 
 /**
@@ -363,6 +405,8 @@ function runStart(options) {
 
 module.exports = {
   START_APPS,
+  codexStartCommand,
+  sendInnerCommand,
   normalizeStartApp,
   sanitizeSessionName,
   resolveSessionName,