nexarch 0.1.5 → 0.1.6

package/README.md

@@ -19,7 +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]` | Run onboarding handshake checks (initialize, tools, policy bootstrap, ingest contract) |
+| `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

@@ -1,15 +1,75 @@
+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",
@@ -23,6 +83,7 @@ export async function initAgent(args) {
         "nexarch_get_ingest_contract",
         "nexarch_upsert_entities",
         "nexarch_upsert_relationships",
+        "nexarch_emit_observations",
     ];
     const missing = required.filter((name) => !toolNames.has(name));
     checks.push({
@@ -46,6 +107,154 @@ export async function initAgent(args) {
         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 = {
@@ -60,6 +269,10 @@ export async function initAgent(args) {
             },
             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)
@@ -72,12 +285,18 @@ export async function initAgent(args) {
         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 completed. Ready for policy-aware ingest.");
+        console.log("✅ Agent handshake + registration completed.");
     }
     else {
-        console.log("⚠ Handshake completed with issues.");
+        console.log("⚠ Handshake/registration completed with issues.");
         if (strict) {
             console.log("Strict mode enabled, exiting non-zero.");
             process.exitCode = 1;

package/dist/index.js

@@ -29,7 +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 onboarding handshake checks (tools/policies/contract)
+  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

@@ -61,7 +61,7 @@ export async function mcpInitialize() {
     return callMcpRpc("initialize", {
         protocolVersion: "2024-11-05",
         capabilities: {},
-        clientInfo: { name: "nexarch-cli", version: "0.1.4" },
+        clientInfo: { name: "nexarch-cli", version: "0.1.6" },
     });
 }
 export async function mcpListTools() {

package/package.json

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