nexarch 0.1.11 → 0.1.13

package/dist/commands/agent-identify.js

@@ -0,0 +1,151 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const value = args[idx + 1];
+    if (!value || value.startsWith("--"))
+        return null;
+    return value;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+function getDefaultAgentId() {
+    const osUser = process.env.USERNAME || process.env.USER || "unknown";
+    const host = process.env.HOSTNAME || "unknown-host";
+    return `nexarch-cli:${osUser}@${host}`;
+}
+function parseCsv(value) {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+export async function agentIdentify(args) {
+    const asJson = parseFlag(args, "--json");
+    const agentId = parseOptionValue(args, "--agent-id") ?? getDefaultAgentId();
+    const provider = parseOptionValue(args, "--provider");
+    const model = parseOptionValue(args, "--model");
+    const client = parseOptionValue(args, "--client");
+    const sessionId = parseOptionValue(args, "--session-id");
+    const framework = parseOptionValue(args, "--framework");
+    const toolVersion = parseOptionValue(args, "--tool-version");
+    const capabilities = parseCsv(parseOptionValue(args, "--capabilities"));
+    const notes = parseOptionValue(args, "--notes");
+    if (!provider || !model || !client) {
+        throw new Error("agent-identify requires --provider, --model, and --client");
+    }
+    const creds = requireCredentials();
+    await mcpInitialize({ companyId: creds.companyId });
+    const tools = await mcpListTools({ companyId: creds.companyId });
+    const toolNames = new Set(tools.map((t) => t.name));
+    const required = ["nexarch_upsert_entities"];
+    const missing = required.filter((name) => !toolNames.has(name));
+    if (missing.length) {
+        throw new Error(`missing required MCP tools: ${missing.join(", ")}`);
+    }
+    let policyBundleHash = null;
+    if (toolNames.has("nexarch_get_applied_policies")) {
+        try {
+            const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {}, { companyId: creds.companyId });
+            const policies = parseToolText(policiesRaw);
+            policyBundleHash = policies.policyBundleHash ?? null;
+        }
+        catch {
+            policyBundleHash = null;
+        }
+    }
+    const nowIso = new Date().toISOString();
+    const upsertRaw = await callMcpTool("nexarch_upsert_entities", {
+        entities: [
+            {
+                externalKey: `agent:${agentId}`,
+                entityTypeCode: "agent",
+                name: `Agent ${agentId}`,
+                confidence: 1,
+                attributes: {
+                    identity: {
+                        source: "nexarch agent identify",
+                        capturedAt: nowIso,
+                        provider,
+                        model,
+                        client,
+                        sessionId,
+                        framework,
+                        toolVersion,
+                        capabilities,
+                        notes,
+                    },
+                },
+            },
+        ],
+        agentContext: {
+            agentId,
+            agentRunId: `agent-identify-${Date.now()}`,
+            repoRef: "nexarch-cli/agent-identify",
+            observedAt: nowIso,
+            source: "nexarch-cli",
+            model,
+            provider,
+        },
+        policyContext: policyBundleHash
+            ? {
+                policyBundleHash,
+                alignmentSummary: {
+                    score: 1,
+                    violations: [],
+                    waivers: [],
+                },
+            }
+            : undefined,
+        dryRun: false,
+    }, { companyId: creds.companyId });
+    const upsert = parseToolText(upsertRaw);
+    const failed = Number(upsert.summary?.failed ?? 0) > 0;
+    const firstResult = upsert.results?.[0];
+    const output = {
+        ok: !failed,
+        detail: failed ? `failed (${upsert.errors?.[0]?.error ?? "unknown"})` : `agent ${firstResult?.action ?? "updated"}`,
+        agentId,
+        graphEntityId: firstResult?.graphEntityId ?? null,
+        identity: {
+            provider,
+            model,
+            client,
+            sessionId,
+            framework,
+            toolVersion,
+            capabilities,
+            notes,
+            capturedAt: nowIso,
+        },
+    };
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        if (!output.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (output.ok) {
+        console.log("✅ Agent identity captured.");
+        console.log(`Agent: ${agentId}`);
+        console.log(`Provider/Model: ${provider} / ${model}`);
+        console.log(`Client: ${client}`);
+        if (framework)
+            console.log(`Framework: ${framework}`);
+    }
+    else {
+        console.log("⚠ Agent identity capture failed.");
+        console.log(output.detail);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/init-agent.js

@@ -1,8 +1,10 @@
-import { arch, hostname, platform, release, type as osType, userInfo } from "os";
+import { arch, homedir, hostname, platform, release, type as osType, userInfo } from "os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
 import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
-const CLI_VERSION = "0.1.11";
+const CLI_VERSION = "0.1.13";
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {
@@ -86,6 +88,92 @@ async function emitInitObservation(params) {
         // non-fatal telemetry path
     }
 }
+function writeAgentBootstrap(params) {
+    const dir = join(homedir(), ".nexarch");
+    mkdirSync(dir, { recursive: true });
+    const filePath = join(dir, "agent-bootstrap.md");
+    const identifyCmd = [
+        `npx nexarch agent identify`,
+        `--agent-id "${params.agentId}"`,
+        `--provider "<anthropic|openai|google|other>"`,
+        `--model "<model-id e.g. claude-sonnet-4-6>"`,
+        `--client "<claude-code|cursor|copilot|other>"`,
+        `--framework "<openclaw|n8n|m365-agent-framework|other>"`,
+        `--session-id "<your current session id if known, otherwise omit>"`,
+        `--tool-version "<run claude --version to get this, e.g. 1.2.3>"`,
+        `--capabilities "<comma,separated,capabilities>"`,
+        `--json`,
+    ].join(" \\\n  ");
+    const content = `# Nexarch Agent Bootstrap
+
+This file was written by \`nexarch init-agent\` on ${new Date().toISOString()}.
+It contains instructions for a Claude Code agent to complete its Nexarch registration.
+
+## What has already been registered
+
+The following entities are now in the architecture graph:
+
+| Entity | Name | Type |
+|--------|------|------|
+| Agent | \`${params.agentId}\` | agent |
+| Host | \`Host ${params.hostname}\` | tech_compute |
+| OS | \`${params.osPlatform} ${params.osRelease}\` | tech_operating_system |
+| Runtime | \`Node.js ${params.nodeVersion}\` | tech_runtime |
+
+## Your task
+
+Run the command below, substituting your own values for the placeholders.
+Return ONLY the completed command (no markdown, no explanation) — it will be executed directly.
+
+\`\`\`
+${identifyCmd}
+\`\`\`
+
+Fill in:
+- **provider** — your AI provider (e.g. \`anthropic\`)
+- **model** — the exact model ID you are running as (e.g. \`claude-sonnet-4-6\`)
+- **client** — the tool you are running inside (e.g. \`claude-code\`)
+- **framework** — the agent framework in use (e.g. \`openclaw\`)
+- **session-id** — your current session ID if available
+- **tool-version** — the version of the client tool you are running inside; run \`claude --version\` (or equivalent) to get it and use the version number only (e.g. \`1.2.3\`)
+- **capabilities** — comma-separated list of your capabilities (e.g. \`code,files,bash,web\`)
+
+Omit any flag whose value you genuinely do not know rather than guessing.
+
+After running, confirm \`"ok": true\` in the JSON output. No further action is needed.
+`;
+    writeFileSync(filePath, content, "utf8");
+    return filePath;
+}
+const CLAUDE_MD_SECTION_MARKER = "## Nexarch Agent Registration";
+const CLAUDE_MD_SECTION = `
+## Nexarch Agent Registration
+
+When a human has run \`nexarch login\` and \`nexarch init-agent\`, they will tell you to run \`npx nexarch agent prompt\`. Do so, read the output, and follow the instructions — it contains a pre-filled \`npx nexarch agent identify\` command for you to complete with your own provider, model, client, and capability values, then execute. Confirm \`"ok": true\` in the JSON output.
+`;
+function injectAgentConfigs() {
+    const candidateNames = [
+        "CLAUDE.md", "claude.md", "Claude.md", // Claude Code
+        "AGENTS.md", "agents.md", // OpenAI Codex CLI
+        ".github/copilot-instructions.md", // GitHub Copilot
+        ".cursorrules", // Cursor (legacy)
+    ];
+    const results = [];
+    for (const name of candidateNames) {
+        const filePath = join(process.cwd(), name);
+        if (!existsSync(filePath))
+            continue;
+        const existing = readFileSync(filePath, "utf8");
+        if (existing.includes(CLAUDE_MD_SECTION_MARKER)) {
+            results.push({ path: filePath, status: "already_present" });
+            continue;
+        }
+        const separator = existing.endsWith("\n") ? "" : "\n";
+        writeFileSync(filePath, existing + separator + CLAUDE_MD_SECTION, "utf8");
+        results.push({ path: filePath, status: "injected" });
+    }
+    return results;
+}
 export async function initAgent(args) {
     const asJson = parseFlag(args, "--json");
     const strict = parseFlag(args, "--strict");
@@ -481,6 +569,29 @@ export async function initAgent(args) {
             }
         }
     }
+    let bootstrapFilePath = null;
+    let agentConfigResults = [];
+    if (registration.ok) {
+        try {
+            bootstrapFilePath = writeAgentBootstrap({
+                agentId,
+                hostname: runtime.hostname,
+                osPlatform: runtime.osPlatform,
+                osRelease: runtime.osRelease,
+                nodeVersion: runtime.nodeVersion,
+                arch: runtime.arch,
+            });
+        }
+        catch {
+            // non-fatal
+        }
+        try {
+            agentConfigResults = injectAgentConfigs();
+        }
+        catch {
+            // non-fatal
+        }
+    }
     checks.push({
         name: "agent.registration",
         ok: registration.ok,
@@ -504,11 +615,17 @@ export async function initAgent(args) {
         });
     }
     const allPassed = checks.every((c) => c.ok);
+    const identifyPrompt = [
+        "Please identify your runtime so the workspace can register richer metadata.",
+        "Return ONLY the completed command below with real values (no markdown):",
+        `nexarch agent identify --agent-id \"${agentId}\" --provider \"<provider>\" --model \"<model>\" --client \"<client>\" --framework \"<openclaw|n8n|m365-agent-framework|other>\" --session-id \"<session-id>\" --tool-version \"<tool-version>\" --capabilities \"<capability1,capability2>\" --notes \"<optional notes>\" --json`,
+    ].join("\n");
     if (asJson) {
         const output = {
             ok: strict ? allPassed : true,
             passed: allPassed,
             strict,
+            status: allPassed ? "needs_agent_identity_followup" : "handshake_completed_with_issues",
             checks,
             summary: {
                 total: checks.length,
@@ -525,7 +642,16 @@ export async function initAgent(args) {
                 relationships: techRelationships,
             },
             binding,
+            followUp: {
+                required: allPassed,
+                type: "agent_identity",
+                detail: "Prompt the coding agent to self-identify and submit via nexarch agent identify",
+                prompt: identifyPrompt,
+                submitCommandTemplate: `nexarch agent identify --agent-id \"${agentId}\" --provider \"<provider>\" --model \"<model>\" --client \"<client>\" --framework \"<openclaw|n8n|m365-agent-framework|other>\" --session-id \"<session-id>\" --tool-version \"<tool-version>\" --capabilities \"<capability1,capability2>\" --notes \"<optional notes>\" --json`,
+            },
             companyId: creds.companyId,
+            bootstrapFile: bootstrapFilePath,
+            agentConfigs: agentConfigResults,
         };
         process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
         if (strict && !allPassed)
@@ -547,6 +673,15 @@ export async function initAgent(args) {
     console.log("");
     if (allPassed) {
         console.log("✅ Agent handshake + registration completed.");
+        if (bootstrapFilePath) {
+            console.log(`\n📋 Bootstrap instructions written to: ${bootstrapFilePath}`);
+        }
+        for (const r of agentConfigResults) {
+            if (r.status === "injected") {
+                console.log(`📝 Nexarch registration instructions added to: ${r.path}`);
+            }
+        }
+        console.log("\n   Tell Claude: \"run npx nexarch agent prompt and follow the instructions\"");
     }
     else {
         console.log("⚠ Handshake/registration completed with issues.");

package/dist/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { homedir } from "os";
+import { readFileSync } from "fs";
+import { join } from "path";
 import { login } from "./commands/login.js";
 import { logout } from "./commands/logout.js";
 import { status } from "./commands/status.js";
@@ -6,6 +9,7 @@ import { setup } from "./commands/setup.js";
 import { mcpConfig } from "./commands/mcp-config.js";
 import { mcpProxy } from "./commands/mcp-proxy.js";
 import { initAgent } from "./commands/init-agent.js";
+import { agentIdentify } from "./commands/agent-identify.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -15,8 +19,27 @@ const commands = {
     "mcp-config": mcpConfig,
     "mcp-proxy": mcpProxy,
     "init-agent": initAgent,
+    "agent-identify": agentIdentify,
 };
 async function main() {
+    if (command === "agent") {
+        const [subcommand, ...subArgs] = args;
+        if (subcommand === "identify") {
+            await agentIdentify(subArgs);
+            return;
+        }
+        if (subcommand === "prompt") {
+            const filePath = join(homedir(), ".nexarch", "agent-bootstrap.md");
+            try {
+                process.stdout.write(readFileSync(filePath, "utf8") + "\n");
+            }
+            catch {
+                console.error("No bootstrap file found. Run 'nexarch init-agent' first.");
+                process.exit(1);
+            }
+            return;
+        }
+    }
     const handler = commands[command ?? ""];
     if (!handler) {
         console.log(`
@@ -34,6 +57,18 @@ Usage:
                         Options: --agent-id <id> --bind-to-external-key <key>
                                  --bind-relationship-type <code> --redact-hostname
                                  --json --strict
+  nexarch agent prompt
+                      Print bootstrap instructions for a Claude Code agent to complete
+                      its registration (written by init-agent). Tell Claude:
+                      "run npx nexarch agent prompt and follow the instructions"
+  nexarch agent identify
+                      Capture richer coding-agent identity metadata
+                      Options: --agent-id <id> --provider <provider> --model <model>
+                               --client <name> [--framework <name>] [--session-id <id>]
+                               [--tool-version <v>] [--capabilities <csv>]
+                               [--notes <text>] [--json]
+  nexarch agent-identify
+                      Alias of 'nexarch agent identify'
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Connect AI coding tools to your Nexarch architecture workspace",
   "keywords": [
     "nexarch",