iranti 0.2.7 → 0.2.8

package/README.md

@@ -354,6 +354,19 @@ Use `--agent`, `--provider`, and `--model` to pin the session identity and model
 The chat surface now includes slash commands for fact history, relationships, conflict-resolution handoff, and confidence updates in addition to memory search/write operations.
 Guide: [`docs/guides/chat.md`](docs/guides/chat.md)
 
+### Manual Attendant Inspection
+
+For debugging and operator visibility, Iranti also exposes manual Attendant commands:
+
+```bash
+iranti handshake --task "Working on ProofScript repo"
+iranti attend "What did we decide about the parser?" --context-file transcript.txt
+```
+
+Both commands accept `--json`.
+They are useful for verifying what the Attendant would load or inject for a given agent and project binding.
+They are not a replacement for Claude Code hooks or MCP tools in normal use.
+
 ---
 
 ## Install Strategy (Double Layer)

package/dist/scripts/iranti-cli.js

@@ -16,9 +16,11 @@ const net_1 = __importDefault(require("net"));
 const client_1 = require("../src/library/client");
 const apiKeys_1 = require("../src/security/apiKeys");
 const escalationPaths_1 = require("../src/lib/escalationPaths");
+const runtimeEnv_1 = require("../src/lib/runtimeEnv");
 const resolutionist_1 = require("../src/resolutionist");
 const chat_1 = require("../src/chat");
 const backends_1 = require("../src/library/backends");
+const sdk_1 = require("../src/sdk");
 const PROVIDER_ENV_KEYS = {
     mock: null,
     ollama: null,
@@ -650,28 +652,216 @@ function makeIrantiMcpServerConfig() {
         args: ['mcp'],
     };
 }
-function makeClaudeHookSettings(projectEnvPath) {
-    const hookArgs = (event) => {
-        const args = ['claude-hook', '--event', event];
-        if (projectEnvPath) {
-            args.push('--project-env', projectEnvPath);
-        }
-        return args;
+function applyEnvMap(vars) {
+    for (const [key, value] of Object.entries(vars)) {
+        process.env[key] = value;
+    }
+}
+async function resolveAttendantCliTarget(args) {
+    const explicitAgent = getFlag(args, 'agent')?.trim();
+    const explicitProjectEnv = getFlag(args, 'project-env');
+    const instanceName = getFlag(args, 'instance');
+    let envSource = 'project';
+    let envFile = null;
+    let projectEnvFile;
+    let instanceEnvFile;
+    if (instanceName) {
+        const scope = normalizeScope(getFlag(args, 'scope'));
+        const root = resolveInstallRoot(args, scope);
+        const loaded = await loadInstanceEnv(root, instanceName);
+        applyEnvMap(loaded.env);
+        envSource = `instance:${instanceName}`;
+        envFile = loaded.envFile;
+        instanceEnvFile = loaded.envFile;
+    }
+    else {
+        const cwd = path_1.default.resolve(getFlag(args, 'project') ?? process.cwd());
+        const loaded = (0, runtimeEnv_1.loadRuntimeEnv)({
+            cwd,
+            projectEnvFile: explicitProjectEnv ? path_1.default.resolve(explicitProjectEnv) : undefined,
+        });
+        envSource = loaded.projectEnvFile ? 'project-binding' : 'environment';
+        envFile = loaded.projectEnvFile ?? loaded.instanceEnvFile ?? null;
+        projectEnvFile = loaded.projectEnvFile;
+        instanceEnvFile = loaded.instanceEnvFile;
+    }
+    const connectionString = process.env.DATABASE_URL?.trim();
+    if (!connectionString) {
+        throw new Error('DATABASE_URL is required. Run from a bound project, pass --instance <name>, or set DATABASE_URL first.');
+    }
+    const agentId = explicitAgent
+        || process.env.IRANTI_AGENT_ID?.trim()
+        || process.env.IRANTI_CLAUDE_AGENT_ID?.trim()
+        || 'iranti_cli';
+    return {
+        envSource,
+        envFile,
+        projectEnvFile,
+        instanceEnvFile,
+        agentId,
+        iranti: new sdk_1.Iranti({ connectionString }),
+    };
+}
+function truncateText(value, limit) {
+    return value.length <= limit ? value : `${value.slice(0, limit - 3)}...`;
+}
+function resolveRecentMessages(args) {
+    const inline = getFlag(args, 'recent');
+    const file = getFlag(args, 'recent-file');
+    if (inline) {
+        return inline
+            .split('||')
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    if (file) {
+        const content = fs_1.default.readFileSync(path_1.default.resolve(file), 'utf-8');
+        return content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    return [];
+}
+function parsePositiveInteger(raw, label) {
+    if (!raw)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return parsed;
+}
+function resolveContextText(args) {
+    const inline = getFlag(args, 'context');
+    if (inline)
+        return inline;
+    const file = getFlag(args, 'context-file');
+    if (file) {
+        return fs_1.default.readFileSync(path_1.default.resolve(file), 'utf-8');
+    }
+    return '';
+}
+function resolveAttendMessage(args) {
+    const fromFlag = getFlag(args, 'message');
+    if (fromFlag?.trim())
+        return fromFlag.trim();
+    const fromPositionals = args.positionals.join(' ').trim();
+    if (fromPositionals)
+        return fromPositionals;
+    throw new Error('Missing latest message. Usage: iranti attend [message] [--message <text>] [--context <text>] [--json]');
+}
+function printHandshakeResult(target, task, result) {
+    console.log(bold('Iranti handshake'));
+    console.log(`  agent         ${target.agentId}`);
+    console.log(`  env source    ${target.envSource}`);
+    if (target.envFile)
+        console.log(`  env file      ${target.envFile}`);
+    console.log(`  task          ${task}`);
+    console.log(`  inferred task ${result.inferredTaskType}`);
+    console.log(`  memory facts  ${result.workingMemory.length}`);
+    console.log(`  generated     ${result.briefGeneratedAt}`);
+    console.log('');
+    console.log(`Rules: ${truncateText(result.operatingRules, 160)}`);
+    if (result.workingMemory.length === 0) {
+        console.log('');
+        console.log('No working memory entries loaded.');
+        return;
+    }
+    console.log('');
+    for (const entry of result.workingMemory) {
+        console.log(`- ${entry.entityKey} | ${entry.summary} | ${entry.confidence} | ${entry.source}`);
+    }
+}
+function printAttendResult(target, latestMessage, result) {
+    console.log(bold('Iranti attend'));
+    console.log(`  agent         ${target.agentId}`);
+    console.log(`  env source    ${target.envSource}`);
+    if (target.envFile)
+        console.log(`  env file      ${target.envFile}`);
+    console.log(`  message       ${truncateText(latestMessage, 120)}`);
+    console.log(`  inject        ${result.shouldInject ? 'yes' : 'no'}`);
+    console.log(`  reason        ${result.reason}`);
+    console.log(`  method        ${result.decision.method}`);
+    console.log(`  confidence    ${result.decision.confidence}`);
+    console.log(`  explanation   ${result.decision.explanation}`);
+    console.log(`  facts         ${result.facts.length}`);
+    if (result.facts.length === 0) {
+        console.log('');
+        console.log('No facts selected for injection.');
+        return;
+    }
+    console.log('');
+    for (const fact of result.facts) {
+        console.log(`- ${fact.entityKey} | ${fact.summary} | ${fact.confidence} | ${fact.source}`);
+    }
+}
+function quoteClaudeHookArg(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/(["\\])/g, '\\$1')}"`;
+}
+function makeClaudeHookCommand(event, projectEnvPath) {
+    const parts = ['iranti', 'claude-hook', '--event', event];
+    if (projectEnvPath) {
+        parts.push('--project-env', quoteClaudeHookArg(projectEnvPath));
+    }
+    return parts.join(' ');
+}
+function makeClaudeHookEntry(event, projectEnvPath) {
+    return {
+        matcher: '',
+        hooks: [
+            {
+                type: 'command',
+                command: makeClaudeHookCommand(event, projectEnvPath),
+            },
+        ],
     };
+}
+function isClaudeHooksObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isLegacyIrantiClaudeHookEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const entry = value;
+    return entry.command === 'iranti'
+        && Array.isArray(entry.args)
+        && entry.args[0] === 'claude-hook';
+}
+function needsClaudeHookSettingsUpgrade(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const settings = value;
+    const hooks = isClaudeHooksObject(settings.hooks) ? settings.hooks : null;
+    if (!hooks) {
+        return false;
+    }
+    for (const event of ['SessionStart', 'UserPromptSubmit']) {
+        const entries = hooks[event];
+        if (!Array.isArray(entries) || entries.length === 0) {
+            continue;
+        }
+        if (entries.some((entry) => isLegacyIrantiClaudeHookEntry(entry))) {
+            return true;
+        }
+    }
+    return false;
+}
+function makeClaudeHookSettings(projectEnvPath, existing) {
+    const existingHooks = existing && isClaudeHooksObject(existing.hooks)
+        ? existing.hooks
+        : {};
     return {
+        ...(existing ?? {}),
         hooks: {
-            SessionStart: [
-                {
-                    command: 'iranti',
-                    args: hookArgs('SessionStart'),
-                },
-            ],
-            UserPromptSubmit: [
-                {
-                    command: 'iranti',
-                    args: hookArgs('UserPromptSubmit'),
-                },
-            ],
+            ...existingHooks,
+            SessionStart: [makeClaudeHookEntry('SessionStart', projectEnvPath)],
+            UserPromptSubmit: [makeClaudeHookEntry('UserPromptSubmit', projectEnvPath)],
         },
     };
 }
@@ -725,9 +915,18 @@ async function writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force =
         await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
         settingsStatus = 'created';
     }
-    else if (force) {
-        await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
-        settingsStatus = 'updated';
+    else {
+        const existingSettings = readJsonFile(settingsFile);
+        if (existingSettings && typeof existingSettings === 'object' && !Array.isArray(existingSettings)) {
+            if (force || needsClaudeHookSettingsUpgrade(existingSettings)) {
+                await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath, existingSettings), null, 2)}\n`);
+                settingsStatus = 'updated';
+            }
+        }
+        else if (force) {
+            await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
+            settingsStatus = 'updated';
+        }
     }
     return {
         mcp: mcpStatus,
@@ -1189,6 +1388,73 @@ function isPathInside(parentDir, childDir) {
     const child = normalizePathForCompare(childDir);
     return child === parent || child.startsWith(`${parent}/`);
 }
+function hasCommandInstalled(command) {
+    try {
+        const proc = process.platform === 'win32'
+            ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', `${command} --version`], { stdio: 'ignore' })
+            : (0, child_process_1.spawnSync)(command, ['--version'], { stdio: 'ignore' });
+        return proc.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function canConnectTcp(port, host = '127.0.0.1', timeoutMs = 800) {
+    return await new Promise((resolve) => {
+        const socket = net_1.default.createConnection({ port, host });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.on('connect', () => finish(true));
+        socket.on('timeout', () => finish(false));
+        socket.on('error', () => finish(false));
+    });
+}
+async function collectDependencyChecks() {
+    const docker = hasDockerInstalled();
+    const psql = hasCommandInstalled('psql');
+    const pgIsReady = hasCommandInstalled('pg_isready');
+    const postgresPort = await canConnectTcp(5432);
+    const checks = [
+        {
+            name: 'docker',
+            status: docker ? 'pass' : 'warn',
+            detail: docker ? 'Docker is installed.' : 'Docker is not installed or not on PATH.',
+        },
+        {
+            name: 'psql',
+            status: psql ? 'pass' : 'warn',
+            detail: psql ? 'psql is installed.' : 'psql is not installed or not on PATH.',
+        },
+        {
+            name: 'pg_isready',
+            status: pgIsReady ? 'pass' : 'warn',
+            detail: pgIsReady ? 'pg_isready is installed.' : 'pg_isready is not installed or not on PATH.',
+        },
+        {
+            name: 'localhost:5432',
+            status: postgresPort ? 'pass' : 'warn',
+            detail: postgresPort ? 'A PostgreSQL listener appears reachable on localhost:5432.' : 'Nothing is reachable on localhost:5432 right now.',
+        },
+    ];
+    return checks;
+}
+function printDependencyChecks(checks) {
+    console.log(bold('Dependency check'));
+    for (const check of checks) {
+        const marker = check.status === 'pass' ? okLabel('PASS') : warnLabel('WARN');
+        console.log(`${marker} ${check.name} — ${check.detail}`);
+    }
+    if (checks.every((check) => check.status === 'warn')) {
+        console.log(`${warnLabel()} No PostgreSQL tooling or reachable local Postgres was detected. You can still continue if you plan to use managed Postgres, but local setup will be rough until you install PostgreSQL tooling or Docker.`);
+    }
+}
 function quoteForCmd(arg) {
     if (arg.length === 0)
         return '""';
@@ -1732,6 +1998,9 @@ async function setupCommand(args) {
         throw new Error('Use either --config <file> or --defaults, not both.');
     }
     if (configPath || useDefaults) {
+        const dependencyChecks = await collectDependencyChecks();
+        printDependencyChecks(dependencyChecks);
+        console.log('');
         const plan = configPath ? parseSetupConfig(configPath) : defaultsSetupPlan(args);
         const result = await executeSetupPlan(plan);
         console.log(bold('Setup complete'));
@@ -1763,6 +2032,8 @@ async function setupCommand(args) {
     console.log(bold('Iranti setup'));
     console.log('This wizard will get Iranti set up: install a runtime, create or update an instance, connect provider keys, create a usable Iranti API key, and optionally bind one or more project folders.');
     console.log('');
+    printDependencyChecks(await collectDependencyChecks());
+    console.log('');
     let result = null;
     await withPromptSession(async (prompt) => {
         let setupMode = 'shared';
@@ -2368,6 +2639,7 @@ async function upgradeCommand(args) {
 async function installCommand(args) {
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
+    const dependencyChecks = await collectDependencyChecks();
     await ensureDir(root);
     await ensureDir(path_1.default.join(root, 'instances'));
     await ensureDir(path_1.default.join(root, 'logs'));
@@ -2382,6 +2654,8 @@ async function installCommand(args) {
     console.log(`${okLabel()} Iranti runtime initialized`);
     console.log(`  scope: ${scope}`);
     console.log(`  root : ${root}`);
+    console.log('');
+    printDependencyChecks(dependencyChecks);
     console.log(`Next: iranti instance create local --port 3001`);
 }
 async function createInstanceCommand(args) {
@@ -2809,6 +3083,67 @@ async function resolveCommand(args) {
     const escalationDir = explicitDir ? path_1.default.resolve(explicitDir) : (0, escalationPaths_1.getEscalationPaths)().root;
     await (0, resolutionist_1.resolveInteractive)(escalationDir);
 }
+async function handshakeCommand(args) {
+    const json = hasFlag(args, 'json');
+    const target = await resolveAttendantCliTarget(args);
+    const task = getFlag(args, 'task')?.trim() || 'CLI handshake';
+    const recentMessages = resolveRecentMessages(args);
+    const result = await target.iranti.handshake({
+        agent: target.agentId,
+        task,
+        recentMessages,
+    });
+    if (json) {
+        console.log(JSON.stringify({
+            agent: target.agentId,
+            envSource: target.envSource,
+            envFile: target.envFile,
+            task,
+            recentMessages,
+            result,
+        }, null, 2));
+        return;
+    }
+    printHandshakeResult(target, task, result);
+    console.log('');
+    console.log(`${infoLabel()} This is a manual Attendant inspection tool. Claude Code should still use hooks + MCP in normal operation.`);
+}
+async function attendCommand(args) {
+    const json = hasFlag(args, 'json');
+    const target = await resolveAttendantCliTarget(args);
+    const latestMessage = resolveAttendMessage(args);
+    const currentContext = resolveContextText(args);
+    const maxFacts = parsePositiveInteger(getFlag(args, 'max-facts'), 'max-facts');
+    const entityHint = getFlag(args, 'entity-hint')?.trim();
+    if (entityHint && !entityHint.includes('/')) {
+        throw new Error('entity-hint must use entityType/entityId format.');
+    }
+    const result = await target.iranti.attend({
+        agent: target.agentId,
+        currentContext,
+        latestMessage,
+        forceInject: hasFlag(args, 'force'),
+        maxFacts,
+        entityHints: entityHint ? [entityHint] : undefined,
+    });
+    if (json) {
+        console.log(JSON.stringify({
+            agent: target.agentId,
+            envSource: target.envSource,
+            envFile: target.envFile,
+            latestMessage,
+            currentContext,
+            maxFacts: maxFacts ?? null,
+            entityHints: entityHint ? [entityHint] : [],
+            forceInject: hasFlag(args, 'force'),
+            result,
+        }, null, 2));
+        return;
+    }
+    printAttendResult(target, latestMessage, result);
+    console.log('');
+    console.log(`${infoLabel()} This is a manual Attendant inspection tool. Claude Code should still use hooks + MCP in normal operation.`);
+}
 function printClaudeSetupHelp() {
     console.log([
         'Scaffold Claude Code MCP and hook files for the current project.',
@@ -3001,6 +3336,8 @@ Project-level:
     iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json]
     iranti status [--scope user|system] [--json]
     iranti upgrade [--check] [--dry-run] [--yes] [--all] [--target auto|npm-global|npm-repo|python[,python]] [--json]
+    iranti handshake [--instance <name> | --project-env <file>] [--agent <id>] [--task <text>] [--recent <msg1||msg2>] [--recent-file <path>] [--json]
+    iranti attend [message] [--instance <name> | --project-env <file>] [--agent <id>] [--context <text> | --context-file <path>] [--entity-hint <entity>] [--force] [--max-facts <n>] [--json]
     iranti chat [--agent <agent-id>] [--provider <provider>] [--model <model>]
     iranti resolve [--dir <escalation-dir>]
 
@@ -3106,6 +3443,14 @@ async function main() {
         await upgradeCommand(args);
         return;
     }
+    if (args.command === 'handshake') {
+        await handshakeCommand(args);
+        return;
+    }
+    if (args.command === 'attend') {
+        await attendCommand(args);
+        return;
+    }
     if (args.command === 'chat') {
         await chatCommand(args);
         return;

package/dist/scripts/iranti-mcp.js

@@ -144,7 +144,7 @@ async function main() {
     await ensureDefaultAgent(iranti);
     const server = new mcp_js_1.McpServer({
         name: 'iranti-mcp',
-        version: '0.2.7',
+        version: '0.2.8',
     });
     server.registerTool('iranti_handshake', {
         description: `Initialize or refresh an agent's working-memory brief for the current task.

package/dist/scripts/seed.js

@@ -15,7 +15,7 @@ const STAFF_ENTRIES = [
         entityId: 'librarian',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             rules: [
                 'All writes from external agents go through the Librarian — never directly to the database',
                 'Check for existing entries before every write',
@@ -39,7 +39,7 @@ const STAFF_ENTRIES = [
         entityId: 'attendant',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             rules: [
                 'Assigned one-per-external-agent — serve the agent, not the user',
                 'On handshake: read AGENTS.md and MCP config, query Librarian for relevant rules and task context',
@@ -61,7 +61,7 @@ const STAFF_ENTRIES = [
         entityId: 'archivist',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             rules: [
                 'Run on schedule or when conflict flags exceed threshold — not on every write',
                 'Scan for expired, low-confidence, flagged, and duplicate entries',
@@ -82,7 +82,7 @@ const STAFF_ENTRIES = [
         entityType: 'system',
         entityId: 'library',
         key: 'schema_version',
-        valueRaw: { version: '0.2.7' },
+        valueRaw: { version: '0.2.8' },
         valueSummary: 'Current Library schema version.',
         confidence: 100,
         source: 'seed',
@@ -95,7 +95,7 @@ const STAFF_ENTRIES = [
         key: 'initialization_log',
         valueRaw: {
             initializedAt: new Date().toISOString(),
-            seedVersion: '0.2.7',
+            seedVersion: '0.2.8',
         },
         valueSummary: 'Record of when and how this Library was initialized.',
         confidence: 100,
@@ -108,7 +108,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'core_schema',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             states: ['candidate', 'provisional', 'canonical'],
             coreEntityTypes: [
                 'person',
@@ -156,7 +156,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'extension_registry',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             terms: [],
         },
         valueSummary: 'Staging area for ontology terms detected repeatedly but not yet promoted.',
@@ -201,7 +201,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'promotion_policy',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             candidateToProvisional: {
                 minSeenCount: 3,
                 minDistinctAgents: 2,
@@ -237,7 +237,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'change_log',
         valueRaw: {
-            version: '0.2.7',
+            version: '0.2.8',
             events: [
                 {
                     at: new Date().toISOString(),

package/dist/src/api/server.js

@@ -69,7 +69,7 @@ app.use(express_1.default.json({ limit: process.env.IRANTI_MAX_BODY_BYTES ?? '25
 app.get(ROUTES.health, (_req, res) => {
     res.json({
         status: 'ok',
-        version: '0.2.7',
+        version: '0.2.8',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iranti",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Memory infrastructure for multi-agent AI systems",
   "main": "dist/src/sdk/index.js",
   "files": [