nexarch 0.1.4 → 0.1.6

package/README.md

@@ -19,6 +19,8 @@ npx nexarch setup
 | `nexarch setup` | Auto-configure detected MCP clients |
 | `nexarch mcp-config [client]` | Print config block for manual setup (`claude-desktop`, `cursor`, `windsurf`) |
 | `nexarch mcp-proxy` | stdio→HTTP bridge used internally by MCP clients |
+| `nexarch init-agent [--json] [--strict] [--agent-id <id>]` | Run onboarding handshake and mandatory `agent` entity registration in graph |
+| `nexarch init-agent --bind-to-external-key <key> [--bind-relationship-type <code>]` | Optionally bind the agent node to an existing graph external key |
 
 ## Requirements
 

package/dist/commands/init-agent.js

@@ -0,0 +1,305 @@
+import { hostname, userInfo } from "os";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
+const CLI_VERSION = "0.1.6";
+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 || userInfo().username || "unknown";
+    const host = hostname() || "unknown-host";
+    return `nexarch-cli:${osUser}@${host}`;
+}
+async function emitInitObservation(params) {
+    if (!params.policyBundleHash)
+        return;
+    const nowIso = new Date().toISOString();
+    try {
+        await callMcpTool("nexarch_emit_observations", {
+            observations: [
+                {
+                    kind: "entity",
+                    externalKey: `agent:${params.agentId}`,
+                    message: params.message,
+                    confidence: params.confidence ?? 0.6,
+                    evidence: { source: "nexarch init-agent", timestamp: nowIso },
+                },
+            ],
+            agentContext: {
+                agentId: params.agentId,
+                agentRunId: `init-agent-${Date.now()}`,
+                repoRef: "nexarch-cli/init-agent",
+                observedAt: nowIso,
+                source: "nexarch-cli",
+                model: "n/a",
+                provider: "n/a",
+            },
+            policyContext: {
+                policyBundleHash: params.policyBundleHash,
+                alignmentSummary: {
+                    score: 1,
+                    violations: [],
+                    waivers: [],
+                },
+            },
+        });
+    }
+    catch {
+        // non-fatal telemetry path
+    }
+}
+export async function initAgent(args) {
+    const asJson = parseFlag(args, "--json");
+    const strict = parseFlag(args, "--strict");
+    const explicitAgentId = parseOptionValue(args, "--agent-id");
+    const bindToExternalKey = parseOptionValue(args, "--bind-to-external-key");
+    const bindRelationshipType = parseOptionValue(args, "--bind-relationship-type") ?? "depends_on";
+    const agentId = explicitAgentId ?? getDefaultAgentId();
+    const checks = [];
+    const creds = requireCredentials();
+    const init = await mcpInitialize();
+    checks.push({
+        name: "mcp.initialize",
+        ok: true,
+        detail: `${init.serverInfo?.name ?? "unknown"}@${init.serverInfo?.version ?? "unknown"}`,
+    });
+    const tools = await mcpListTools();
+    const toolNames = new Set(tools.map((t) => t.name));
+    const required = [
+        "nexarch_get_applied_policies",
+        "nexarch_get_ingest_contract",
+        "nexarch_upsert_entities",
+        "nexarch_upsert_relationships",
+        "nexarch_emit_observations",
+    ];
+    const missing = required.filter((name) => !toolNames.has(name));
+    checks.push({
+        name: "mcp.tools.list",
+        ok: missing.length === 0,
+        detail: missing.length ? `missing: ${missing.join(", ")}` : `required tools present (${required.length})`,
+    });
+    const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {});
+    const policies = parseToolText(policiesRaw);
+    checks.push({
+        name: "governance.bootstrap",
+        ok: Boolean(policies.policyBundleHash),
+        detail: policies.policyBundleHash
+            ? `policyBundleHash=${policies.policyBundleHash.slice(0, 12)}… policyCount=${policies.policyCount ?? 0}`
+            : "missing policyBundleHash",
+    });
+    const contractRaw = await callMcpTool("nexarch_get_ingest_contract", {});
+    const contract = parseToolText(contractRaw);
+    checks.push({
+        name: "ingest.contract",
+        ok: Boolean(contract.contractVersion),
+        detail: `version=${contract.contractVersion ?? "unknown"}; entities=${contract.ontology?.entityCodes?.length ?? 0}; relationships=${contract.ontology?.relationshipCodes?.length ?? 0}`,
+    });
+    const hasAgentType = (contract.ontology?.entityCodes ?? []).some((code) => code.toLowerCase() === "agent");
+    checks.push({
+        name: "ontology.agent-type",
+        ok: hasAgentType,
+        detail: hasAgentType
+            ? "entity type 'agent' is enabled"
+            : "entity type 'agent' is not enabled for this workspace ontology",
+    });
+    const preflightPassed = checks.every((c) => c.ok);
+    let registration = {
+        ok: false,
+        detail: "registration not attempted",
+    };
+    let binding = {
+        attempted: false,
+        ok: true,
+        detail: "not requested",
+    };
+    if (preflightPassed && policies.policyBundleHash) {
+        const nowIso = new Date().toISOString();
+        const upsertRaw = await callMcpTool("nexarch_upsert_entities", {
+            entities: [
+                {
+                    externalKey: `agent:${agentId}`,
+                    entityTypeCode: "agent",
+                    name: `Agent ${agentId}`,
+                    description: "Agent identity registered from nexarch init-agent handshake",
+                    confidence: 1,
+                    attributes: {
+                        kind: "ai_agent",
+                        client: "nexarch-cli",
+                        version: CLI_VERSION,
+                        companyId: creds.companyId,
+                        handshake: {
+                            completedAt: nowIso,
+                            source: "init-agent",
+                        },
+                    },
+                },
+            ],
+            agentContext: {
+                agentId,
+                agentRunId: `init-agent-${Date.now()}`,
+                repoRef: "nexarch-cli/init-agent",
+                observedAt: nowIso,
+                source: "nexarch-cli",
+                model: "n/a",
+                provider: "n/a",
+            },
+            policyContext: {
+                policyBundleHash: policies.policyBundleHash,
+                alignmentSummary: {
+                    score: 1,
+                    violations: [],
+                    waivers: [],
+                },
+            },
+            dryRun: false,
+        });
+        const upsert = parseToolText(upsertRaw);
+        const firstResult = upsert.results?.[0];
+        const failed = Number(upsert.summary?.failed ?? 0) > 0;
+        registration = {
+            ok: !failed,
+            detail: failed
+                ? `failed to register agent entry (${upsert.errors?.[0]?.error ?? "unknown"})`
+                : `agent entry ${firstResult?.action ?? "upserted"}`,
+            graphEntityId: firstResult?.graphEntityId ?? null,
+            action: firstResult?.action ?? null,
+            errors: upsert.errors,
+        };
+        if (!registration.ok) {
+            await emitInitObservation({
+                agentId,
+                policyBundleHash: policies.policyBundleHash,
+                message: `init-agent registration failed: ${registration.detail}`,
+                confidence: 1,
+            });
+        }
+        if (registration.ok && bindToExternalKey) {
+            binding.attempted = true;
+            const relRaw = await callMcpTool("nexarch_upsert_relationships", {
+                relationships: [
+                    {
+                        relationshipTypeCode: bindRelationshipType,
+                        fromEntityExternalKey: `agent:${agentId}`,
+                        toEntityExternalKey: bindToExternalKey,
+                        confidence: 1,
+                        attributes: {
+                            source: "nexarch-cli-init-agent",
+                            createdAt: nowIso,
+                        },
+                    },
+                ],
+                agentContext: {
+                    agentId,
+                    agentRunId: `init-agent-bind-${Date.now()}`,
+                    repoRef: "nexarch-cli/init-agent",
+                    observedAt: nowIso,
+                    source: "nexarch-cli",
+                    model: "n/a",
+                    provider: "n/a",
+                },
+                policyContext: {
+                    policyBundleHash: policies.policyBundleHash,
+                    alignmentSummary: {
+                        score: 1,
+                        violations: [],
+                        waivers: [],
+                    },
+                },
+                dryRun: false,
+            });
+            const rel = parseToolText(relRaw);
+            const relResult = rel.results?.[0];
+            const relFailed = Number(rel.summary?.failed ?? 0) > 0;
+            binding = {
+                attempted: true,
+                ok: !relFailed,
+                detail: relFailed
+                    ? `failed to bind agent (${rel.errors?.[0]?.error ?? "unknown"})`
+                    : `agent bound via ${bindRelationshipType}`,
+                graphRelationshipId: relResult?.graphRelationshipId ?? null,
+                action: relResult?.action ?? null,
+                errors: rel.errors,
+            };
+            if (!binding.ok) {
+                await emitInitObservation({
+                    agentId,
+                    policyBundleHash: policies.policyBundleHash,
+                    message: `init-agent binding failed: ${binding.detail}`,
+                    confidence: 1,
+                });
+            }
+        }
+    }
+    checks.push({
+        name: "agent.registration",
+        ok: registration.ok,
+        detail: registration.detail,
+    });
+    if (binding.attempted) {
+        checks.push({
+            name: "agent.binding",
+            ok: binding.ok,
+            detail: binding.detail,
+        });
+    }
+    const allPassed = checks.every((c) => c.ok);
+    if (asJson) {
+        const output = {
+            ok: strict ? allPassed : true,
+            passed: allPassed,
+            strict,
+            checks,
+            summary: {
+                total: checks.length,
+                ok: checks.filter((c) => c.ok).length,
+                failed: checks.filter((c) => !c.ok).length,
+            },
+            policyBundleHash: policies.policyBundleHash ?? null,
+            contractVersion: contract.contractVersion ?? null,
+            agentId,
+            registration,
+            binding,
+            companyId: creds.companyId,
+        };
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        if (strict && !allPassed)
+            process.exitCode = 1;
+        return;
+    }
+    console.log("Running agent onboarding handshake…\n");
+    for (const check of checks) {
+        console.log(`${check.ok ? "✓" : "✗"} ${check.name}`);
+        if (check.detail)
+            console.log(`    ${check.detail}`);
+    }
+    if (registration.graphEntityId) {
+        console.log(`\nRegistered graph entity: ${registration.graphEntityId}`);
+    }
+    if (binding.attempted && binding.graphRelationshipId) {
+        console.log(`Bound relationship id: ${binding.graphRelationshipId}`);
+    }
+    console.log("");
+    if (allPassed) {
+        console.log("✅ Agent handshake + registration completed.");
+    }
+    else {
+        console.log("⚠ Handshake/registration completed with issues.");
+        if (strict) {
+            console.log("Strict mode enabled, exiting non-zero.");
+            process.exitCode = 1;
+        }
+    }
+}

package/dist/index.js

@@ -5,6 +5,7 @@ import { status } from "./commands/status.js";
 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";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -13,6 +14,7 @@ const commands = {
     setup,
     "mcp-config": mcpConfig,
     "mcp-proxy": mcpProxy,
+    "init-agent": initAgent,
 };
 async function main() {
     const handler = commands[command ?? ""];
@@ -27,6 +29,9 @@ Usage:
   nexarch setup         Auto-configure your MCP client (Claude Desktop, Cursor, etc.)
   nexarch mcp-config    Print MCP server config block for manual setup
   nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
+  nexarch init-agent    Run handshake + mandatory agent registration in graph
+                        Options: --agent-id <id> --bind-to-external-key <key>
+                                 --bind-relationship-type <code> --json --strict
     `);
         process.exit(command ? 1 : 0);
     }

package/dist/lib/mcp.js

@@ -2,13 +2,13 @@ import https from "https";
 import { requireCredentials } from "./credentials.js";
 const MCP_GATEWAY_URL = "https://mcp.nexarch.ai";
 const REQUEST_TIMEOUT_MS = 30 * 1000;
-export async function callMcpTool(toolName, toolArgs = {}) {
+async function callMcpRpc(method, params = {}) {
     const creds = requireCredentials();
     const body = JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
-        method: "tools/call",
-        params: { name: toolName, arguments: toolArgs },
+        method,
+        params,
     });
     return new Promise((resolve, reject) => {
         const url = new URL("/mcp", MCP_GATEWAY_URL);
@@ -19,7 +19,7 @@ export async function callMcpTool(toolName, toolArgs = {}) {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "Authorization": `Bearer ${creds.token}`,
+                Authorization: `Bearer ${creds.token}`,
                 "x-company-id": creds.companyId,
                 "Content-Length": Buffer.byteLength(body),
             },
@@ -34,7 +34,7 @@ export async function callMcpTool(toolName, toolArgs = {}) {
                     if (json.error) {
                         reject(new Error(json.error.message));
                     }
-                    else if (json.result) {
+                    else if (json.result !== undefined) {
                         resolve(json.result);
                     }
                     else {
@@ -54,6 +54,20 @@ export async function callMcpTool(toolName, toolArgs = {}) {
         req.end();
     });
 }
+export async function callMcpTool(toolName, toolArgs = {}) {
+    return callMcpRpc("tools/call", { name: toolName, arguments: toolArgs });
+}
+export async function mcpInitialize() {
+    return callMcpRpc("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "nexarch-cli", version: "0.1.6" },
+    });
+}
+export async function mcpListTools() {
+    const result = await callMcpRpc("tools/list", {});
+    return result.tools ?? [];
+}
 export async function forwardToGateway(token, companyId, body) {
     return new Promise((resolve, reject) => {
         const url = new URL("/mcp", MCP_GATEWAY_URL);
@@ -64,7 +78,7 @@ export async function forwardToGateway(token, companyId, body) {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "Authorization": `Bearer ${token}`,
+                Authorization: `Bearer ${token}`,
                 "x-company-id": companyId,
                 "Content-Length": Buffer.byteLength(body),
             },

package/package.json

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