@ryuenn3123/agentic-senior-core 4.1.0 → 4.2.1

package/lib/cli/ascx/lexer.mjs

@@ -0,0 +1,129 @@
+const SHELL_OPERATOR_TOKENS = new Set([
+  '|',
+  '||',
+  '&',
+  '&&',
+  ';',
+  '>',
+  '>>',
+  '<',
+  '2>',
+  '2>>',
+]);
+
+function isEnvironmentAssignment(argumentValue) {
+  return /^[A-Za-z_][A-Za-z0-9_]*=.+$/u.test(argumentValue);
+}
+
+function hasCommandSubstitution(argumentValue) {
+  return argumentValue.includes('$(') || argumentValue.includes('`');
+}
+
+function hasRedirectToken(argumentValue) {
+  return /^(?:[12]?>|[12]?>>|<)/u.test(argumentValue);
+}
+
+export function parseAscxCommand(commandArguments = []) {
+  const rawArguments = commandArguments.map((argumentValue) => String(argumentValue));
+  const unsafeTokens = rawArguments.filter((argumentValue) => {
+    return SHELL_OPERATOR_TOKENS.has(argumentValue)
+      || hasCommandSubstitution(argumentValue)
+      || hasRedirectToken(argumentValue);
+  });
+  const environment = [];
+  let executableIndex = 0;
+
+  while (
+    executableIndex < rawArguments.length
+    && isEnvironmentAssignment(rawArguments[executableIndex])
+  ) {
+    environment.push(rawArguments[executableIndex]);
+    executableIndex += 1;
+  }
+
+  const executable = rawArguments[executableIndex] || '';
+  const args = executable ? rawArguments.slice(executableIndex + 1) : [];
+
+  return {
+    rawArguments,
+    commandText: rawArguments.join(' '),
+    environment,
+    executable,
+    args,
+    unsafeTokens,
+    hasShellSyntax: unsafeTokens.length > 0,
+    hasEnvironmentPrefix: environment.length > 0,
+  };
+}
+
+export function classifyAscxInvocation(parsedCommand) {
+  if (!parsedCommand.executable) {
+    return {
+      kind: 'passthrough',
+      adapterName: null,
+      reason: 'missing executable',
+    };
+  }
+
+  if (parsedCommand.hasShellSyntax) {
+    return {
+      kind: 'unsafe-for-compression',
+      adapterName: null,
+      reason: `shell syntax detected: ${parsedCommand.unsafeTokens.join(', ')}`,
+    };
+  }
+
+  if (parsedCommand.hasEnvironmentPrefix) {
+    return {
+      kind: 'passthrough',
+      adapterName: null,
+      reason: 'environment prefix detected',
+    };
+  }
+
+  if (parsedCommand.executable === 'git' && parsedCommand.args[0] === 'status') {
+    return {
+      kind: 'compressible',
+      adapterName: 'git-status',
+      reason: 'supported git status adapter',
+    };
+  }
+
+  if (parsedCommand.executable === 'git' && parsedCommand.args[0] === 'diff') {
+    return {
+      kind: 'compressible',
+      adapterName: 'git-diff',
+      reason: 'supported git diff adapter',
+    };
+  }
+
+  if (parsedCommand.executable === 'npm' && parsedCommand.args[0] === 'test') {
+    return {
+      kind: 'compressible',
+      adapterName: 'npm-test',
+      reason: 'supported npm test adapter',
+    };
+  }
+
+  if (parsedCommand.executable === 'npm' && parsedCommand.args[0] === 'run' && parsedCommand.args[1] === 'build') {
+    return {
+      kind: 'compressible',
+      adapterName: 'npm-run-build',
+      reason: 'supported npm run build adapter',
+    };
+  }
+
+  if (parsedCommand.executable === 'rg') {
+    return {
+      kind: 'compressible',
+      adapterName: 'rg',
+      reason: 'supported rg (ripgrep) adapter',
+    };
+  }
+
+  return {
+    kind: 'passthrough',
+    adapterName: null,
+    reason: 'unsupported command',
+  };
+}

package/lib/cli/ascx/runtime.mjs

@@ -0,0 +1,192 @@
+import { spawn } from 'node:child_process';
+
+import { compressGitDiffOutput } from './adapters/git-diff.mjs';
+import { compressGitStatusOutput } from './adapters/git-status.mjs';
+import { compressNpmTestOutput } from './adapters/npm-test.mjs';
+import { compressNpmRunBuildOutput } from './adapters/npm-run-build.mjs';
+import { compressRgOutput } from './adapters/rg.mjs';
+import { buildAscxFooter, shouldWriteSafetyTee } from './formatter.mjs';
+import { classifyAscxInvocation, parseAscxCommand } from './lexer.mjs';
+import { writeRawTeeFile } from './tee-writer.mjs';
+
+const ADAPTERS = {
+  'git-diff': compressGitDiffOutput,
+  'git-status': compressGitStatusOutput,
+  'npm-test': compressNpmTestOutput,
+  'npm-run-build': compressNpmRunBuildOutput,
+  'rg': compressRgOutput,
+};
+
+function buildCommandEnvironment(baseEnvironment, parsedCommand) {
+  const commandEnvironment = { ...baseEnvironment };
+
+  for (const assignment of parsedCommand.environment) {
+    const separatorIndex = assignment.indexOf('=');
+    const variableName = assignment.slice(0, separatorIndex);
+    const variableValue = assignment.slice(separatorIndex + 1);
+
+    commandEnvironment[variableName] = variableValue;
+  }
+
+  return commandEnvironment;
+}
+
+function runSpawnedCommand(parsedCommand, options = {}) {
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    shell = false,
+  } = options;
+
+  return new Promise((resolve) => {
+    const useWindowsNpmShell = process.platform === 'win32'
+      && parsedCommand.executable === 'npm'
+      && shell === false;
+    const executable = shell
+      ? parsedCommand.commandText
+      : parsedCommand.executable;
+    const args = shell ? [] : parsedCommand.args;
+    const childProcess = spawn(executable, args, {
+      cwd,
+      env: buildCommandEnvironment(env, parsedCommand),
+      shell: shell || useWindowsNpmShell,
+      windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+
+    childProcess.stdout?.setEncoding('utf8');
+    childProcess.stderr?.setEncoding('utf8');
+    childProcess.stdout?.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    childProcess.stderr?.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    childProcess.on('error', (error) => {
+      stderr += `${error.name}: ${error.message}\n`;
+    });
+    childProcess.on('close', (exitCode) => {
+      resolve({
+        stdout,
+        stderr,
+        exitCode: typeof exitCode === 'number' ? exitCode : 1,
+      });
+    });
+  });
+}
+
+function combineOutput(stdout, stderr) {
+  return [stdout, stderr].filter(Boolean).join('\n');
+}
+
+async function formatCompressedResult({
+  adapterResult,
+  capture,
+  classification,
+  commandText,
+  cwd,
+  teeDirectoryPath,
+}) {
+  const rawOutput = combineOutput(capture.stdout, capture.stderr);
+  const preliminaryFooter = buildAscxFooter({
+    classification: classification.kind,
+    commandText,
+    compactOutput: adapterResult.output,
+    exitCode: capture.exitCode,
+    filterName: adapterResult.filterName,
+    rawOutput,
+    rawTeePath: null,
+  });
+  const rawTeePath = shouldWriteSafetyTee({
+    adapterResult,
+    exitCode: capture.exitCode,
+    reductionPercent: preliminaryFooter.reductionPercent,
+  })
+    ? await writeRawTeeFile({
+      commandText,
+      cwd,
+      exitCode: capture.exitCode,
+      rawOutput,
+      teeDirectoryPath,
+    })
+    : null;
+  const footer = buildAscxFooter({
+    classification: classification.kind,
+    commandText,
+    compactOutput: adapterResult.output,
+    exitCode: capture.exitCode,
+    filterName: adapterResult.filterName,
+    rawOutput,
+    rawTeePath,
+  });
+
+  return {
+    stdout: `${adapterResult.output}\n\n${footer.text}\n`,
+    stderr: '',
+    exitCode: capture.exitCode,
+    compressed: adapterResult.confident === true,
+    rawTeePath,
+    footer,
+    adapterResult,
+  };
+}
+
+export async function runAscx(commandArguments, options = {}) {
+  const {
+    cwd = process.cwd(),
+    executeCommand = runSpawnedCommand,
+    teeDirectoryPath,
+  } = options;
+  const parsedCommand = parseAscxCommand(commandArguments);
+  const classification = classifyAscxInvocation(parsedCommand);
+
+  if (!parsedCommand.executable) {
+    return {
+      stdout: '',
+      stderr: 'ascx: command is required\n',
+      exitCode: 1,
+      parsedCommand,
+      classification,
+      compressed: false,
+      rawTeePath: null,
+    };
+  }
+
+  const capture = await executeCommand(parsedCommand, {
+    cwd,
+    shell: classification.kind === 'unsafe-for-compression',
+  });
+
+  if (classification.kind !== 'compressible') {
+    return {
+      stdout: capture.stdout,
+      stderr: capture.stderr,
+      exitCode: capture.exitCode,
+      parsedCommand,
+      classification,
+      compressed: false,
+      rawTeePath: null,
+    };
+  }
+
+  const adapter = ADAPTERS[classification.adapterName];
+  const adapterResult = adapter({
+    stdout: capture.stdout,
+    stderr: capture.stderr,
+    exitCode: capture.exitCode,
+  });
+
+  return {
+    ...await formatCompressedResult({
+      adapterResult,
+      capture,
+      classification,
+      commandText: parsedCommand.commandText,
+      cwd,
+      teeDirectoryPath,
+    }),
+    parsedCommand,
+    classification,
+  };
+}

package/lib/cli/ascx/tee-writer.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const MAX_TEE_FILES = 20;
+
+function sanitizeFileNamePart(rawValue) {
+  return String(rawValue || 'command')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'command';
+}
+
+export function getDefaultTeeDirectory(cwd = process.cwd()) {
+  return path.resolve(cwd, '.agent-context', 'state', 'token-saver', 'tee');
+}
+
+async function sweepOldTeeFiles(directoryPath, maxFiles = MAX_TEE_FILES) {
+  let entries;
+
+  try {
+    entries = await fs.readdir(directoryPath);
+  } catch {
+    return;
+  }
+
+  const logFiles = entries.filter((name) => name.endsWith('.log')).sort();
+  const excess = logFiles.length - maxFiles;
+
+  for (let i = 0; i < excess; i++) {
+    try {
+      await fs.unlink(path.join(directoryPath, logFiles[i]));
+    } catch {
+      // Best-effort cleanup; do not fail the write path.
+    }
+  }
+}
+
+export async function writeRawTeeFile({
+  commandText,
+  cwd = process.cwd(),
+  exitCode,
+  rawOutput,
+  teeDirectoryPath = getDefaultTeeDirectory(cwd),
+}) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const commandName = sanitizeFileNamePart(commandText);
+  const teeFilePath = path.resolve(teeDirectoryPath, `${timestamp}-${commandName}.log`);
+  const fileContent = [
+    `[ascx raw output]`,
+    `command: ${commandText}`,
+    `exit: ${exitCode}`,
+    '',
+    rawOutput,
+  ].join('\n');
+
+  await fs.mkdir(path.dirname(teeFilePath), { recursive: true });
+  await fs.writeFile(teeFilePath, fileContent, 'utf8');
+  await sweepOldTeeFiles(teeDirectoryPath);
+
+  return teeFilePath;
+}
+

package/lib/cli/ascx/token-estimate.mjs

@@ -0,0 +1,15 @@
+export const ASCX_TOKEN_ESTIMATE_METHOD = 'chars-div-4-local-estimate';
+
+export function estimateOutputTokens(outputText) {
+  const textLength = String(outputText || '').length;
+  return Math.max(0, Math.ceil(textLength / 4));
+}
+
+export function calculateReductionPercent(rawTokens, compactTokens) {
+  if (rawTokens <= 0) {
+    return 0;
+  }
+
+  const reducedTokens = Math.max(0, rawTokens - compactTokens);
+  return Number(((reducedTokens / rawTokens) * 100).toFixed(2));
+}

package/lib/cli/backup.mjs

@@ -6,6 +6,11 @@ import { entryPointFiles, BACKUP_DIR_NAME } from './constants.mjs';
 
 const BACKUP_GITIGNORE_ENTRY = `${BACKUP_DIR_NAME}/`;
 const BACKUP_GITIGNORE_COMMENT = '# agentic-senior-core: local backup artifacts';
+const RUNTIME_ARTIFACT_GITIGNORE_ENTRIES = [
+  '.agent-context/state/token-saver/',
+  '.agent-context/state/token-optimization-report.json',
+];
+const RUNTIME_ARTIFACT_GITIGNORE_COMMENT = '# agentic-senior-core: local runtime artifacts';
 
 /**
  * Calculates a SHA-256 hash of a file's contents.
@@ -127,18 +132,23 @@ export async function createBackup(targetDirectoryPath) {
   };
 }
 
-export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+async function ensureGitignoreEntries(targetDirectoryPath, { comment, entries, aliasesByEntry = {} }) {
   const gitignorePath = path.join(targetDirectoryPath, '.gitignore');
   const existingContent = await pathExists(gitignorePath)
     ? await fs.readFile(gitignorePath, 'utf8')
     : '';
   const existingLines = existingContent.split(/\r?\n/).map((line) => line.trim());
+  const missingEntries = entries.filter((entry) => {
+    const equivalentEntries = [entry, ...(aliasesByEntry[entry] || [])];
+    return !equivalentEntries.some((equivalentEntry) => existingLines.includes(equivalentEntry));
+  });
 
-  if (existingLines.includes(BACKUP_GITIGNORE_ENTRY) || existingLines.includes(BACKUP_DIR_NAME)) {
+  if (missingEntries.length === 0) {
     return {
       status: 'unchanged',
       gitignorePath,
-      entry: BACKUP_GITIGNORE_ENTRY,
+      entries,
+      addedEntries: [],
     };
   }
 
@@ -149,13 +159,36 @@ export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
   if (nextContent.length > 0 && !nextContent.endsWith('\n\n')) {
     nextContent += '\n';
   }
-  nextContent += `${BACKUP_GITIGNORE_COMMENT}\n${BACKUP_GITIGNORE_ENTRY}\n`;
+  nextContent += `${comment}\n${missingEntries.join('\n')}\n`;
 
   await fs.writeFile(gitignorePath, nextContent, 'utf8');
 
   return {
     status: existingContent ? 'updated' : 'created',
     gitignorePath,
+    entries,
+    addedEntries: missingEntries,
+  };
+}
+
+export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+  const result = await ensureGitignoreEntries(targetDirectoryPath, {
+    comment: BACKUP_GITIGNORE_COMMENT,
+    entries: [BACKUP_GITIGNORE_ENTRY],
+    aliasesByEntry: {
+      [BACKUP_GITIGNORE_ENTRY]: [BACKUP_DIR_NAME],
+    },
+  });
+
+  return {
+    ...result,
     entry: BACKUP_GITIGNORE_ENTRY,
   };
 }
+
+export async function ensureRuntimeArtifactGitignoreEntries(targetDirectoryPath) {
+  return ensureGitignoreEntries(targetDirectoryPath, {
+    comment: RUNTIME_ARTIFACT_GITIGNORE_COMMENT,
+    entries: RUNTIME_ARTIFACT_GITIGNORE_ENTRIES,
+  });
+}

package/lib/cli/commands/context.mjs

@@ -0,0 +1,140 @@
+import { stdin } from 'node:process';
+
+import { buildSelectedContextManifest } from '../adaptive-context.mjs';
+
+export function parseContextArguments(commandArguments) {
+  const parsedOptions = {
+    requestId: 'adhoc-request',
+    requestText: '',
+    contextFiles: [],
+    json: false,
+    readStdin: false,
+  };
+  const requestParts = [];
+
+  for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
+    const currentArgument = commandArguments[argumentIndex];
+
+    if (currentArgument === '--json') {
+      parsedOptions.json = true;
+      continue;
+    }
+
+    if (currentArgument === '--stdin') {
+      parsedOptions.readStdin = true;
+      continue;
+    }
+
+    if (currentArgument === '--file') {
+      const contextFilePath = commandArguments[argumentIndex + 1];
+      if (!contextFilePath || contextFilePath.startsWith('--')) {
+        throw new Error('Missing value for --file');
+      }
+
+      parsedOptions.contextFiles.push(contextFilePath);
+      argumentIndex++;
+      continue;
+    }
+
+    if (currentArgument === '--files') {
+      const contextFileList = commandArguments[argumentIndex + 1];
+      if (!contextFileList || contextFileList.startsWith('--')) {
+        throw new Error('Missing value for --files');
+      }
+
+      parsedOptions.contextFiles.push(
+        ...contextFileList
+          .split(',')
+          .map((contextFilePath) => contextFilePath.trim())
+          .filter(Boolean)
+      );
+      argumentIndex++;
+      continue;
+    }
+
+    if (currentArgument === '--request-id') {
+      const requestId = commandArguments[argumentIndex + 1];
+      if (!requestId || requestId.startsWith('--')) {
+        throw new Error('Missing value for --request-id');
+      }
+
+      parsedOptions.requestId = requestId;
+      argumentIndex++;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--')) {
+      throw new Error(`Unknown option: ${currentArgument}`);
+    }
+
+    requestParts.push(currentArgument);
+  }
+
+  parsedOptions.requestText = requestParts.join(' ').trim();
+  return parsedOptions;
+}
+
+function readRequestFromStdin() {
+  return new Promise((resolve, reject) => {
+    let requestText = '';
+
+    stdin.setEncoding('utf8');
+    stdin.on('data', (chunk) => {
+      requestText += chunk;
+    });
+    stdin.on('error', reject);
+    stdin.on('end', () => {
+      resolve(requestText.trim());
+    });
+  });
+}
+
+function formatList(label, values) {
+  if (values.length === 0) {
+    return [`${label}: none`];
+  }
+
+  return [
+    `${label}:`,
+    ...values.map((value) => `- ${value}`),
+  ];
+}
+
+function formatManifestText(manifest) {
+  return [
+    'Adaptive Context',
+    `requestId: ${manifest.requestId}`,
+    `labels: ${manifest.labels.length > 0 ? manifest.labels.join(', ') : 'none'}`,
+    `uncertainty: ${manifest.uncertainty}`,
+    `budget: ${manifest.budget.status} (${manifest.budget.selectedRuleCount}/${manifest.budget.maxRecommendedRuleCount} recommended rules)`,
+    `fallbackRequired: ${manifest.fallbackRequired}`,
+    ...formatList('contextFiles', manifest.contextFiles),
+    ...formatList('selectedRules', manifest.selectedRules),
+    ...formatList('selectedPrompts', manifest.selectedPrompts),
+    ...formatList('selectedDocs', manifest.selectedDocs),
+  ].join('\n');
+}
+
+export async function runContextCommand(commandArguments) {
+  const contextOptions = parseContextArguments(commandArguments);
+  const requestText = contextOptions.readStdin
+    ? await readRequestFromStdin()
+    : contextOptions.requestText;
+
+  if (!requestText) {
+    throw new Error('Context request text is required. Pass text as arguments or use --stdin.');
+  }
+
+  const manifest = buildSelectedContextManifest({
+    contextFiles: contextOptions.contextFiles,
+    requestId: contextOptions.requestId,
+    requestText,
+  });
+
+  if (contextOptions.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+
+  console.log(formatManifestText(manifest));
+}

package/lib/cli/commands/init.mjs

@@ -45,7 +45,11 @@ import {
   resolveDetectedSetupDecision,
 } from '../init-detection-flow.mjs';
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
+import {
+  createBackup,
+  ensureBackupGitignoreEntry,
+  ensureRuntimeArtifactGitignoreEntries,
+} from '../backup.mjs';
 import {
   runProjectDiscovery,
   generateProjectDocumentation,
@@ -373,6 +377,12 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     if (backupGitignoreResult.status !== 'unchanged') {
       console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
     }
+    const runtimeArtifactGitignoreResult = await ensureRuntimeArtifactGitignoreEntries(resolvedTargetDirectoryPath);
+    if (runtimeArtifactGitignoreResult.status !== 'unchanged') {
+      console.log(
+        `Local runtime artifacts ignored in .gitignore (${runtimeArtifactGitignoreResult.addedEntries.join(', ')}).`
+      );
+    }
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,
@@ -565,6 +575,8 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- Review thresholds: ${formatBlockingSeverities(selectedPolicyProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
     console.log('- Generated files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
+    console.log('- Default activation cues: Adaptive Context bootstrap, ASCX command wrappers, Compact Natural final replies');
+    console.log('- Default response mode: Compact Natural Mode enabled (.agent-context/prompts/compact-natural-mode.md)');
     if (scaffoldingResult?.bootstrapMode === 'ai-synthesis') {
       console.log(`- Bootstrap prompts: ${(scaffoldingResult.generatedPromptFileNames || []).length} files generated in .agent-context/prompts/`);
       if ((scaffoldingResult.materializedFileNames || []).length > 0) {
@@ -587,7 +599,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('- Memory continuity policy: disabled (--no-memory-continuity)');
     }
     if (isTokenOptimizationEnabled) {
-      console.log(`- Token optimization policy: enabled for ${selectedTokenAgentName}`);
+      console.log(`- Token optimization policy: enabled for ${selectedTokenAgentName} (ASCX command guidance on)`);
     } else {
       console.log('- Token optimization policy: disabled (--no-token-optimize)');
     }