@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/agent-clients/config.ts

@@ -0,0 +1,323 @@
+import {
+  AGENT_CLIENT_IDS,
+  isAgentClientId
+} from './types.ts';
+import type {
+  AgentClientConfig,
+  AgentClientId,
+  AgentClientsConfig,
+  AgentClientState,
+  OrchestrationModelPolicy
+} from './types.ts';
+
+type AgentClientConfigInput = Readonly<{
+  agentClients?: unknown;
+  tuis?: unknown;
+  sandbox?: unknown;
+  customTUIs?: unknown;
+}>;
+
+type AgentClientDiagnosticCode =
+  | 'INVALID_AGENT_CLIENTS'
+  | 'DUPLICATE_AGENT_CLIENT'
+  | 'MISSING_AGENT_CLIENT'
+  | 'UNKNOWN_AGENT_CLIENT'
+  | 'LEGACY_CONFLICT'
+  | 'LEGACY_VALUE_IGNORED';
+
+type AgentClientDiagnostic = Readonly<{
+  code: AgentClientDiagnosticCode;
+  path: string;
+}>;
+
+type NormalizeAgentClientsResult = Readonly<{
+  source: 'canonical' | 'legacy';
+  state: AgentClientState;
+  canonical: AgentClientsConfig;
+  remainingSandboxTools: readonly string[] | undefined;
+  removeLegacyTuis: boolean;
+  changed: boolean;
+  diagnostics: readonly AgentClientDiagnostic[];
+}>;
+
+class AgentClientConfigError extends Error {
+  readonly code: AgentClientDiagnosticCode;
+  readonly path: string;
+  readonly diagnostics: readonly AgentClientDiagnostic[];
+
+  constructor(diagnostic: AgentClientDiagnostic) {
+    super(`${diagnostic.code} at ${diagnostic.path}`);
+    this.name = 'AgentClientConfigError';
+    this.code = diagnostic.code;
+    this.path = diagnostic.path;
+    this.diagnostics = [diagnostic];
+  }
+}
+
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function fail(code: AgentClientDiagnosticCode, path: string): never {
+  throw new AgentClientConfigError({ code, path });
+}
+
+function parseExactText(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.length === 0 || value.trim() !== value) {
+    fail('INVALID_AGENT_CLIENTS', path);
+  }
+  return value;
+}
+
+function parseOrchestrationPolicy(value: unknown, path: string): OrchestrationModelPolicy {
+  if (!isRecord(value)) fail('INVALID_AGENT_CLIENTS', path);
+  const keys = Object.keys(value);
+  if (
+    keys.length !== 2
+    || !hasOwn(value, 'executor')
+    || !hasOwn(value, 'reviewer')
+  ) {
+    fail('INVALID_AGENT_CLIENTS', path);
+  }
+  const parseRole = (candidate: unknown, rolePath: string) => {
+    if (
+      !isRecord(candidate)
+      || Object.keys(candidate).length !== 2
+      || !hasOwn(candidate, 'model')
+      || !hasOwn(candidate, 'reasoningEffort')
+    ) {
+      fail('INVALID_AGENT_CLIENTS', rolePath);
+    }
+    return Object.freeze({
+      model: parseExactText(candidate.model, `${rolePath}.model`),
+      reasoningEffort: parseExactText(candidate.reasoningEffort, `${rolePath}.reasoningEffort`)
+    });
+  };
+  const executor = parseRole(value.executor, `${path}.executor`);
+  const reviewer = parseRole(value.reviewer, `${path}.reviewer`);
+  return Object.freeze({ executor, reviewer });
+}
+
+function parseCanonical(value: unknown): AgentClientState {
+  if (!Array.isArray(value)) fail('INVALID_AGENT_CLIENTS', 'agentClients');
+
+  const entries = new Map<AgentClientId, Readonly<{
+    enabled: boolean;
+    installInSandbox: boolean;
+    orchestration?: OrchestrationModelPolicy;
+  }>>();
+
+  for (const [index, candidate] of value.entries()) {
+    const path = `agentClients[${index}]`;
+    if (!isRecord(candidate)) fail('INVALID_AGENT_CLIENTS', path);
+
+    const keys = Object.keys(candidate);
+    if (
+      (keys.length !== 3 && keys.length !== 4)
+      || !hasOwn(candidate, 'id')
+      || !hasOwn(candidate, 'enabled')
+      || !hasOwn(candidate, 'installInSandbox')
+      || (keys.length === 4 && !hasOwn(candidate, 'orchestration'))
+    ) {
+      fail('INVALID_AGENT_CLIENTS', path);
+    }
+    if (!isAgentClientId(candidate.id)) {
+      fail('UNKNOWN_AGENT_CLIENT', `${path}.id`);
+    }
+    if (entries.has(candidate.id)) {
+      fail('DUPLICATE_AGENT_CLIENT', `${path}.id`);
+    }
+    if (
+      typeof candidate.enabled !== 'boolean'
+      || typeof candidate.installInSandbox !== 'boolean'
+    ) {
+      fail('INVALID_AGENT_CLIENTS', path);
+    }
+    entries.set(candidate.id, {
+      enabled: candidate.enabled,
+      installInSandbox: candidate.installInSandbox,
+      ...(hasOwn(candidate, 'orchestration')
+        ? { orchestration: parseOrchestrationPolicy(candidate.orchestration, `${path}.orchestration`) }
+        : {})
+    });
+  }
+
+  for (const id of AGENT_CLIENT_IDS) {
+    if (!entries.has(id)) fail('MISSING_AGENT_CLIENT', 'agentClients');
+  }
+
+  return Object.fromEntries(
+    AGENT_CLIENT_IDS.map((id) => [id, entries.get(id)!])
+  ) as AgentClientState;
+}
+
+function serializeAgentClients(state: AgentClientState): AgentClientsConfig {
+  return AGENT_CLIENT_IDS.map((id): AgentClientConfig => ({
+    id,
+    enabled: state[id].enabled,
+    installInSandbox: state[id].installInSandbox,
+    ...(state[id].orchestration
+      ? { orchestration: structuredClone(state[id].orchestration) }
+      : {})
+  }));
+}
+
+function projectLegacyTuis(
+  value: unknown,
+  diagnostics: AgentClientDiagnostic[]
+): Readonly<Record<AgentClientId, boolean>> {
+  if (!Array.isArray(value)) {
+    return Object.fromEntries(
+      AGENT_CLIENT_IDS.map((id) => [id, true])
+    ) as Readonly<Record<AgentClientId, boolean>>;
+  }
+
+  const enabled = new Set<AgentClientId>();
+  for (const [index, candidate] of value.entries()) {
+    if (isAgentClientId(candidate)) {
+      enabled.add(candidate);
+    } else {
+      diagnostics.push({
+        code: 'LEGACY_VALUE_IGNORED',
+        path: `tuis[${index}]`
+      });
+    }
+  }
+  return Object.fromEntries(
+    AGENT_CLIENT_IDS.map((id) => [id, enabled.has(id)])
+  ) as Readonly<Record<AgentClientId, boolean>>;
+}
+
+type SandboxProjection = Readonly<{
+  installed: Readonly<Record<AgentClientId, boolean>>;
+  clientSignals: ReadonlySet<AgentClientId>;
+  remainingTools: readonly string[] | undefined;
+}>;
+
+function projectLegacySandbox(
+  value: unknown,
+  diagnostics: AgentClientDiagnostic[]
+): SandboxProjection {
+  if (!Array.isArray(value) || value.length === 0) {
+    return {
+      installed: Object.fromEntries(
+        AGENT_CLIENT_IDS.map((id) => [id, true])
+      ) as Readonly<Record<AgentClientId, boolean>>,
+      clientSignals: new Set<AgentClientId>(),
+      remainingTools: Array.isArray(value) ? [] : undefined
+    };
+  }
+
+  const installed = new Set<AgentClientId>();
+  const remainingTools: string[] = [];
+  for (const [index, candidate] of value.entries()) {
+    if (isAgentClientId(candidate)) {
+      installed.add(candidate);
+    } else if (typeof candidate === 'string') {
+      remainingTools.push(candidate);
+    } else {
+      diagnostics.push({
+        code: 'LEGACY_VALUE_IGNORED',
+        path: `sandbox.tools[${index}]`
+      });
+    }
+  }
+  return {
+    installed: Object.fromEntries(
+      AGENT_CLIENT_IDS.map((id) => [id, installed.has(id)])
+    ) as Readonly<Record<AgentClientId, boolean>>,
+    clientSignals: installed,
+    remainingTools
+  };
+}
+
+function stateFromLegacy(
+  enabled: Readonly<Record<AgentClientId, boolean>>,
+  installed: Readonly<Record<AgentClientId, boolean>>
+): AgentClientState {
+  return Object.fromEntries(
+    AGENT_CLIENT_IDS.map((id) => [
+      id,
+      {
+        enabled: enabled[id],
+        installInSandbox: installed[id]
+      }
+    ])
+  ) as AgentClientState;
+}
+
+function sameCanonicalOrder(value: unknown): boolean {
+  return Array.isArray(value)
+    && value.every((entry, index) => isRecord(entry) && entry.id === AGENT_CLIENT_IDS[index]);
+}
+
+function normalizeAgentClients(
+  input: AgentClientConfigInput
+): NormalizeAgentClientsResult {
+  const diagnostics: AgentClientDiagnostic[] = [];
+  const hasCanonical = hasOwn(input, 'agentClients');
+  const hasLegacyTuis = hasOwn(input, 'tuis');
+  const sandbox = isRecord(input.sandbox) ? input.sandbox : undefined;
+  const hasLegacySandboxTools = sandbox !== undefined && hasOwn(sandbox, 'tools');
+  const tuiProjection = projectLegacyTuis(input.tuis, diagnostics);
+  const sandboxProjection = projectLegacySandbox(sandbox?.tools, diagnostics);
+
+  if (!hasCanonical) {
+    const state = stateFromLegacy(tuiProjection, sandboxProjection.installed);
+    return {
+      source: 'legacy',
+      state,
+      canonical: serializeAgentClients(state),
+      remainingSandboxTools: sandboxProjection.remainingTools,
+      removeLegacyTuis: hasLegacyTuis,
+      changed: true,
+      diagnostics
+    };
+  }
+
+  const state = parseCanonical(input.agentClients);
+  if (hasLegacyTuis) {
+    for (const id of AGENT_CLIENT_IDS) {
+      if (state[id].enabled !== tuiProjection[id]) {
+        fail('LEGACY_CONFLICT', 'tuis');
+      }
+    }
+  }
+  if (hasLegacySandboxTools) {
+    for (const id of sandboxProjection.clientSignals) {
+      if (!state[id].installInSandbox) {
+        fail('LEGACY_CONFLICT', 'sandbox.tools');
+      }
+    }
+  }
+
+  return {
+    source: 'canonical',
+    state,
+    canonical: serializeAgentClients(state),
+    remainingSandboxTools: hasLegacySandboxTools
+      ? sandboxProjection.remainingTools
+      : undefined,
+    removeLegacyTuis: hasLegacyTuis,
+    changed: hasLegacyTuis
+      || sandboxProjection.clientSignals.size > 0
+      || !sameCanonicalOrder(input.agentClients),
+    diagnostics
+  };
+}
+
+export {
+  AgentClientConfigError,
+  normalizeAgentClients,
+  serializeAgentClients
+};
+export type {
+  AgentClientConfigInput,
+  AgentClientDiagnostic,
+  AgentClientDiagnosticCode,
+  NormalizeAgentClientsResult
+};

package/lib/agent-clients/custom-tuis.ts

@@ -0,0 +1,149 @@
+import path from 'node:path';
+
+type CustomTUI = Readonly<{
+  name: string;
+  dir: string;
+  invocation: string;
+}>;
+
+type CustomTUIDiagnosticCode =
+  | 'INVALID_CUSTOM_TUIS'
+  | 'INVALID_CUSTOM_TUI'
+  | 'INVALID_CUSTOM_TUI_PLACEHOLDER';
+
+type CustomTUIDiagnostic = Readonly<{
+  code: CustomTUIDiagnosticCode;
+  path: string;
+}>;
+
+type NormalizeCustomTUIsResult = Readonly<{
+  items: readonly CustomTUI[];
+  diagnostics: readonly CustomTUIDiagnostic[];
+}>;
+
+const CUSTOM_TUI_CONTRACT = Object.freeze({
+  requiredFields: Object.freeze(['name', 'dir', 'invoke']),
+  allowedPlaceholders: Object.freeze(['skillName', 'projectName'])
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptySingleLine(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.trim() !== ''
+    && !/[\r\n]/.test(value);
+}
+
+function normalizeDir(projectRoot: string, value: unknown): string | null {
+  if (
+    !isNonEmptySingleLine(value)
+    || value.includes('\\')
+    || path.isAbsolute(value)
+    || /^[a-zA-Z]:/.test(value)
+  ) {
+    return null;
+  }
+  const normalized = path.posix.normalize(value);
+  if (
+    normalized === '.'
+    || normalized === '..'
+    || normalized.startsWith('../')
+    || normalized.split('/').includes('..')
+  ) {
+    return null;
+  }
+  const relative = path.relative(
+    path.resolve(projectRoot),
+    path.resolve(projectRoot, normalized)
+  );
+  return relative === ''
+    || path.isAbsolute(relative)
+    || relative === '..'
+    || relative.startsWith(`..${path.sep}`)
+    ? null
+    : normalized;
+}
+
+function hasValidPlaceholders(invocation: string): boolean {
+  const placeholders = [
+    ...invocation.matchAll(/\$\{([^}]+)\}/g)
+  ].map((match) => match[1]!);
+  return placeholders.includes('skillName')
+    && placeholders.every((placeholder) =>
+      CUSTOM_TUI_CONTRACT.allowedPlaceholders.includes(placeholder)
+    )
+    && !invocation
+      .replaceAll('${skillName}', '')
+      .replaceAll('${projectName}', '')
+      .includes('${');
+}
+
+function normalizeCustomTUIs(
+  projectRoot: string,
+  input: unknown
+): NormalizeCustomTUIsResult {
+  const items: CustomTUI[] = [];
+  const diagnostics: CustomTUIDiagnostic[] = [];
+
+  if (!Array.isArray(input)) {
+    return Object.freeze({
+      items: Object.freeze([]),
+      diagnostics: Object.freeze([
+        Object.freeze({
+          code: 'INVALID_CUSTOM_TUIS' as const,
+          path: 'customTUIs'
+        })
+      ])
+    });
+  }
+
+  for (const [index, candidate] of input.entries()) {
+    const base = `customTUIs[${index}]`;
+    if (!isRecord(candidate)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TUI', path: base });
+      continue;
+    }
+    if (!isNonEmptySingleLine(candidate.name)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TUI', path: `${base}.name` });
+      continue;
+    }
+    const dir = normalizeDir(projectRoot, candidate.dir);
+    if (!dir) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TUI', path: `${base}.dir` });
+      continue;
+    }
+    if (!isNonEmptySingleLine(candidate.invoke)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TUI', path: `${base}.invoke` });
+      continue;
+    }
+    if (!hasValidPlaceholders(candidate.invoke)) {
+      diagnostics.push({
+        code: 'INVALID_CUSTOM_TUI_PLACEHOLDER',
+        path: `${base}.invoke`
+      });
+      continue;
+    }
+    items.push(Object.freeze({
+      name: candidate.name,
+      dir,
+      invocation: candidate.invoke
+    }));
+  }
+
+  return Object.freeze({
+    items: Object.freeze(items),
+    diagnostics: Object.freeze(
+      diagnostics.map((diagnostic) => Object.freeze(diagnostic))
+    )
+  });
+}
+
+export { CUSTOM_TUI_CONTRACT, normalizeCustomTUIs };
+export type {
+  CustomTUI,
+  CustomTUIDiagnostic,
+  CustomTUIDiagnosticCode,
+  NormalizeCustomTUIsResult
+};

package/lib/agent-clients/invocation.ts

@@ -0,0 +1,19 @@
+type AgentClientInvocationInput = Readonly<{
+  skillName: string;
+  projectName?: string;
+  args?: readonly string[];
+}>;
+
+function renderAgentClientInvocation(
+  template: string,
+  input: AgentClientInvocationInput
+): string {
+  let command = template.replaceAll('${skillName}', input.skillName);
+  if (input.projectName !== undefined) {
+    command = command.replaceAll('${projectName}', input.projectName);
+  }
+  return [command, ...(input.args ?? [])].join(' ').trim();
+}
+
+export { renderAgentClientInvocation };
+export type { AgentClientInvocationInput };

package/lib/agent-clients/next-steps.ts

@@ -0,0 +1,85 @@
+import { listEnabledAgentClientAdapters } from './registry.ts';
+import { renderAgentClientInvocation } from './invocation.ts';
+import semver from 'semver';
+import type { CustomTUI } from './custom-tuis.ts';
+import type { AgentClientId, AgentClientState } from './types.ts';
+
+type NextStepCommand = Readonly<{
+  source: 'builtin' | 'custom';
+  clientId?: AgentClientId;
+  displayName: string;
+  command: string;
+}>;
+
+type RenderNextStepsInput = Readonly<{
+  projectName: string;
+  state: AgentClientState;
+  customTUIs: readonly CustomTUI[];
+  skillName: string;
+  taskRef?: string;
+  version?: string;
+}>;
+
+const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const SAFE_TASK_REF = /^(?:\d+|TASK-\d{8}-\d{6})$/;
+
+function requireSafeName(value: string, field: string): void {
+  if (!SAFE_NAME.test(value)) {
+    throw new Error(`Invalid ${field}`);
+  }
+}
+
+function renderNextStepCommands(
+  input: RenderNextStepsInput
+): readonly NextStepCommand[] {
+  requireSafeName(input.projectName, 'project name');
+  requireSafeName(input.skillName, 'skill name');
+  if (input.taskRef !== undefined && !SAFE_TASK_REF.test(input.taskRef)) {
+    throw new Error('Invalid task ref');
+  }
+  if (
+    input.version !== undefined
+    && (!/^[0-9]/.test(input.version) || semver.valid(input.version) !== input.version)
+  ) {
+    throw new Error('Invalid version');
+  }
+
+  const args = [
+    ...(input.taskRef === undefined ? [] : [input.taskRef]),
+    ...(input.version === undefined ? [] : [input.version])
+  ];
+
+  const builtins = listEnabledAgentClientAdapters(input.state).map(
+    (adapter): NextStepCommand => Object.freeze({
+      source: 'builtin',
+      clientId: adapter.id,
+      displayName: adapter.displayName,
+      command: renderAgentClientInvocation(
+        adapter.invocation,
+        {
+          projectName: input.projectName,
+          skillName: input.skillName,
+          args
+        }
+      )
+    })
+  );
+  const custom = input.customTUIs.map(
+    (tool): NextStepCommand => Object.freeze({
+      source: 'custom',
+      displayName: tool.name,
+      command: renderAgentClientInvocation(
+        tool.invocation,
+        {
+          projectName: input.projectName,
+          skillName: input.skillName,
+          args
+        }
+      )
+    })
+  );
+  return Object.freeze([...builtins, ...custom]);
+}
+
+export { renderNextStepCommands };
+export type { NextStepCommand, RenderNextStepsInput };

package/lib/agent-clients/project-assets.ts

@@ -0,0 +1,96 @@
+import type { AgentClientAdapter } from './adapter.ts';
+
+type ProjectFileRegistry = Readonly<{
+  managed: readonly string[];
+  merged: readonly string[];
+  ejected: readonly string[];
+}>;
+
+type AgentClientProjectAssetPlan = Readonly<{
+  registry: ProjectFileRegistry;
+  enabledManaged: readonly string[];
+  enabledMerged: readonly string[];
+  enabledEjected: readonly string[];
+  disabledManaged: readonly string[];
+}>;
+
+function unique(values: readonly string[]): readonly string[] {
+  return Object.freeze([...new Set(values)]);
+}
+
+function planAgentClientProjectAssets(input: Readonly<{
+  current: ProjectFileRegistry;
+  sharedDefaults: ProjectFileRegistry;
+  enabledAdapters: readonly AgentClientAdapter[];
+  allAdapters: readonly AgentClientAdapter[];
+}>): AgentClientProjectAssetPlan {
+  const enabledIds = new Set(input.enabledAdapters.map((adapter) => adapter.id));
+  const enabledAdapters = input.allAdapters.filter((adapter) =>
+    enabledIds.has(adapter.id)
+  );
+  const disabledAdapters = input.allAdapters.filter((adapter) =>
+    !enabledIds.has(adapter.id)
+  );
+
+  const enabledManaged = unique(
+    enabledAdapters.flatMap((adapter) => adapter.project.managed)
+  );
+  const enabledMerged = unique(
+    enabledAdapters.flatMap((adapter) => adapter.project.merged)
+  );
+  const enabledEjected = unique(
+    enabledAdapters.flatMap((adapter) => adapter.project.ejected)
+  );
+  const disabledManaged = unique(
+    disabledAdapters.flatMap((adapter) => adapter.project.managed)
+  );
+
+  const allAdapterAssets = new Set(
+    input.allAdapters.flatMap((adapter) => [
+      ...adapter.project.managed,
+      ...adapter.project.merged,
+      ...adapter.project.ejected
+    ])
+  );
+  const ejected = unique([
+    ...input.current.ejected,
+    ...enabledEjected,
+    ...input.sharedDefaults.ejected
+  ]);
+  const ejectedSet = new Set(ejected);
+
+  const preserveCurrent = (
+    values: readonly string[],
+    enabledValues: readonly string[]
+  ) => values.filter((entry) =>
+    !ejectedSet.has(entry)
+    && (!allAdapterAssets.has(entry) || enabledValues.includes(entry))
+  );
+
+  const managed = unique([
+    ...preserveCurrent(input.current.managed, enabledManaged),
+    ...enabledManaged.filter((entry) => !ejectedSet.has(entry)),
+    ...input.sharedDefaults.managed.filter((entry) => !ejectedSet.has(entry))
+  ]);
+  const managedSet = new Set(managed);
+  const merged = unique([
+    ...preserveCurrent(input.current.merged, enabledMerged),
+    ...enabledMerged.filter((entry) =>
+      !ejectedSet.has(entry) && !managedSet.has(entry)
+    ),
+    ...input.sharedDefaults.merged.filter((entry) =>
+      !ejectedSet.has(entry) && !managedSet.has(entry)
+    )
+  ]);
+
+  return Object.freeze({
+    registry: Object.freeze({ managed, merged, ejected }),
+    enabledManaged,
+    enabledMerged,
+    enabledEjected,
+    disabledManaged
+  });
+}
+
+export { planAgentClientProjectAssets };
+export type { AgentClientProjectAssetPlan, ProjectFileRegistry };