nexarch 0.1.6 → 0.1.8

package/README.md

@@ -19,8 +19,9 @@ 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 [--json] [--strict] [--agent-id <id>] [--redact-hostname]` | 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 |
+| `nexarch init-agent` (default behavior) | Also upserts technology component entities (host, OS, Node.js runtime) and links them to the agent |
 
 ## Requirements
 

package/dist/commands/init-agent.js

@@ -1,7 +1,10 @@
-import { hostname, userInfo } from "os";
+import { arch, hostname, platform, release, type as osType, userInfo } from "os";
+import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
-const CLI_VERSION = "0.1.6";
+const CLI_VERSION = "0.1.8";
+const AGENT_ENTITY_TYPE = "agent";
+const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {
     return args.includes(flag);
 }
@@ -23,6 +26,28 @@ function getDefaultAgentId() {
     const host = hostname() || "unknown-host";
     return `nexarch-cli:${osUser}@${host}`;
 }
+function getRuntimeMode() {
+    if (process.env.CI)
+        return "ci";
+    return "interactive";
+}
+function getSanitizedHostname(redactHostname) {
+    const raw = hostname() || "unknown-host";
+    return redactHostname ? "redacted" : raw;
+}
+function hasEntityType(contract, code) {
+    return (contract.ontology?.entityCodes ?? []).some((entityCode) => entityCode.toLowerCase() === code.toLowerCase());
+}
+function pickRelationshipType(contract) {
+    const available = new Set((contract.ontology?.relationshipCodes ?? []).map((c) => c.toLowerCase()));
+    if (available.has("depends_on"))
+        return "depends_on";
+    if (available.has("uses"))
+        return "uses";
+    if (available.has("runs_on"))
+        return "runs_on";
+    return null;
+}
 async function emitInitObservation(params) {
     if (!params.policyBundleHash)
         return;
@@ -64,10 +89,20 @@ async function emitInitObservation(params) {
 export async function initAgent(args) {
     const asJson = parseFlag(args, "--json");
     const strict = parseFlag(args, "--strict");
+    const redactHostname = parseFlag(args, "--redact-hostname");
     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 runtime = {
+        osPlatform: platform(),
+        osType: osType(),
+        osRelease: release(),
+        arch: arch(),
+        hostname: getSanitizedHostname(redactHostname),
+        nodeVersion: process.version,
+        mode: getRuntimeMode(),
+    };
     const checks = [];
     const creds = requireCredentials();
     const init = await mcpInitialize();
@@ -107,7 +142,7 @@ 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");
+    const hasAgentType = hasEntityType(contract, AGENT_ENTITY_TYPE);
     checks.push({
         name: "ontology.agent-type",
         ok: hasAgentType,
@@ -115,23 +150,51 @@ export async function initAgent(args) {
             ? "entity type 'agent' is enabled"
             : "entity type 'agent' is not enabled for this workspace ontology",
     });
+    const hasTechComponentType = hasEntityType(contract, TECH_COMPONENT_ENTITY_TYPE);
+    checks.push({
+        name: "ontology.technology-component-type",
+        ok: hasTechComponentType,
+        detail: hasTechComponentType
+            ? "entity type 'technology_component' is enabled"
+            : "entity type 'technology_component' is not enabled for this workspace ontology",
+    });
+    const relForTechBinding = pickRelationshipType(contract);
+    checks.push({
+        name: "ontology.agent-tech-relationship",
+        ok: Boolean(relForTechBinding),
+        detail: relForTechBinding
+            ? `using relationship '${relForTechBinding}' for agent->technology_component links`
+            : "no supported relationship code found (expected one of depends_on|uses|runs_on)",
+    });
     const preflightPassed = checks.every((c) => c.ok);
     let registration = {
         ok: false,
         detail: "registration not attempted",
     };
+    let techComponents = {
+        attempted: false,
+        ok: true,
+        detail: "not attempted",
+    };
+    let techRelationships = {
+        attempted: false,
+        ok: true,
+        detail: "not attempted",
+    };
     let binding = {
         attempted: false,
         ok: true,
         detail: "not requested",
     };
-    if (preflightPassed && policies.policyBundleHash) {
+    if (preflightPassed && policies.policyBundleHash && relForTechBinding) {
         const nowIso = new Date().toISOString();
+        const agentRunId = `init-agent-${Date.now()}`;
+        const agentExternalKey = `agent:${agentId}`;
         const upsertRaw = await callMcpTool("nexarch_upsert_entities", {
             entities: [
                 {
-                    externalKey: `agent:${agentId}`,
-                    entityTypeCode: "agent",
+                    externalKey: agentExternalKey,
+                    entityTypeCode: AGENT_ENTITY_TYPE,
                     name: `Agent ${agentId}`,
                     description: "Agent identity registered from nexarch init-agent handshake",
                     confidence: 1,
@@ -140,6 +203,21 @@ export async function initAgent(args) {
                         client: "nexarch-cli",
                         version: CLI_VERSION,
                         companyId: creds.companyId,
+                        governance: {
+                            policyBundleHash: policies.policyBundleHash,
+                            contractVersion: contract.contractVersion ?? null,
+                            policyCount: policies.policyCount ?? null,
+                            strict,
+                        },
+                        runtime: {
+                            os: runtime.osPlatform,
+                            osType: runtime.osType,
+                            osRelease: runtime.osRelease,
+                            arch: runtime.arch,
+                            hostname: runtime.hostname,
+                            nodeVersion: runtime.nodeVersion,
+                            mode: runtime.mode,
+                        },
                         handshake: {
                             completedAt: nowIso,
                             source: "init-agent",
@@ -149,7 +227,7 @@ export async function initAgent(args) {
             ],
             agentContext: {
                 agentId,
-                agentRunId: `init-agent-${Date.now()}`,
+                agentRunId,
                 repoRef: "nexarch-cli/init-agent",
                 observedAt: nowIso,
                 source: "nexarch-cli",
@@ -186,6 +264,158 @@ export async function initAgent(args) {
                 confidence: 1,
             });
         }
+        if (registration.ok) {
+            techComponents.attempted = true;
+            const hostExternalKey = `tech:host:${runtime.hostname}:${runtime.arch}`;
+            const osExternalKey = `tech:os:${runtime.osPlatform}:${runtime.osRelease}:${runtime.arch}`;
+            const nodeExternalKey = `tech:runtime:nodejs:${runtime.nodeVersion}`;
+            const techUpsertRaw = await callMcpTool("nexarch_upsert_entities", {
+                entities: [
+                    {
+                        externalKey: hostExternalKey,
+                        entityTypeCode: TECH_COMPONENT_ENTITY_TYPE,
+                        name: `Host ${runtime.hostname}`,
+                        description: "Execution host for registered agent runtimes",
+                        confidence: 0.95,
+                        attributes: {
+                            kind: "host_machine",
+                            hostname: runtime.hostname,
+                            arch: runtime.arch,
+                            os: runtime.osPlatform,
+                            osRelease: runtime.osRelease,
+                        },
+                    },
+                    {
+                        externalKey: osExternalKey,
+                        entityTypeCode: TECH_COMPONENT_ENTITY_TYPE,
+                        name: `${runtime.osPlatform} ${runtime.osRelease}`,
+                        description: "Operating system platform used by registered agents",
+                        confidence: 0.95,
+                        attributes: {
+                            kind: "operating_system",
+                            os: runtime.osPlatform,
+                            osType: runtime.osType,
+                            osRelease: runtime.osRelease,
+                            arch: runtime.arch,
+                        },
+                    },
+                    {
+                        externalKey: nodeExternalKey,
+                        entityTypeCode: TECH_COMPONENT_ENTITY_TYPE,
+                        name: `Node.js ${runtime.nodeVersion}`,
+                        description: "Node.js runtime used by nexarch-cli agent",
+                        confidence: 0.95,
+                        attributes: {
+                            kind: "runtime",
+                            runtime: "nodejs",
+                            version: runtime.nodeVersion,
+                        },
+                    },
+                ],
+                agentContext: {
+                    agentId,
+                    agentRunId: `${agentRunId}-tech`,
+                    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 techUpsert = parseToolText(techUpsertRaw);
+            const techFailed = Number(techUpsert.summary?.failed ?? 0) > 0;
+            techComponents = {
+                attempted: true,
+                ok: !techFailed,
+                detail: techFailed
+                    ? `technology component upsert failed (${techUpsert.errors?.[0]?.error ?? "unknown"})`
+                    : `upserted ${(techUpsert.summary?.succeeded ?? 0)} technology components`,
+                results: techUpsert.results,
+                errors: techUpsert.errors,
+            };
+            if (!techComponents.ok) {
+                await emitInitObservation({
+                    agentId,
+                    policyBundleHash: policies.policyBundleHash,
+                    message: `init-agent technology component upsert failed: ${techComponents.detail}`,
+                    confidence: 1,
+                });
+            }
+            if (techComponents.ok) {
+                techRelationships.attempted = true;
+                const techRelRaw = await callMcpTool("nexarch_upsert_relationships", {
+                    relationships: [
+                        {
+                            relationshipTypeCode: relForTechBinding,
+                            fromEntityExternalKey: agentExternalKey,
+                            toEntityExternalKey: hostExternalKey,
+                            confidence: 0.95,
+                            attributes: { source: "nexarch-cli-init-agent", kind: "execution_host", createdAt: nowIso },
+                        },
+                        {
+                            relationshipTypeCode: relForTechBinding,
+                            fromEntityExternalKey: agentExternalKey,
+                            toEntityExternalKey: osExternalKey,
+                            confidence: 0.95,
+                            attributes: { source: "nexarch-cli-init-agent", kind: "operating_system", createdAt: nowIso },
+                        },
+                        {
+                            relationshipTypeCode: relForTechBinding,
+                            fromEntityExternalKey: agentExternalKey,
+                            toEntityExternalKey: nodeExternalKey,
+                            confidence: 0.95,
+                            attributes: { source: "nexarch-cli-init-agent", kind: "runtime", createdAt: nowIso },
+                        },
+                    ],
+                    agentContext: {
+                        agentId,
+                        agentRunId: `${agentRunId}-tech-rel`,
+                        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 relUpsert = parseToolText(techRelRaw);
+                const relFailed = Number(relUpsert.summary?.failed ?? 0) > 0;
+                techRelationships = {
+                    attempted: true,
+                    ok: !relFailed,
+                    detail: relFailed
+                        ? `technology relationship upsert failed (${relUpsert.errors?.[0]?.error ?? "unknown"})`
+                        : `upserted ${(relUpsert.summary?.succeeded ?? 0)} technology relationships`,
+                    results: relUpsert.results,
+                    errors: relUpsert.errors,
+                };
+                if (!techRelationships.ok) {
+                    await emitInitObservation({
+                        agentId,
+                        policyBundleHash: policies.policyBundleHash,
+                        message: `init-agent technology relationship upsert failed: ${techRelationships.detail}`,
+                        confidence: 1,
+                    });
+                }
+            }
+        }
         if (registration.ok && bindToExternalKey) {
             binding.attempted = true;
             const relRaw = await callMcpTool("nexarch_upsert_relationships", {
@@ -248,6 +478,16 @@ export async function initAgent(args) {
         ok: registration.ok,
         detail: registration.detail,
     });
+    checks.push({
+        name: "technology.components",
+        ok: techComponents.ok,
+        detail: techComponents.detail,
+    });
+    checks.push({
+        name: "technology.relationships",
+        ok: techRelationships.ok,
+        detail: techRelationships.detail,
+    });
     if (binding.attempted) {
         checks.push({
             name: "agent.binding",
@@ -270,7 +510,12 @@ export async function initAgent(args) {
             policyBundleHash: policies.policyBundleHash ?? null,
             contractVersion: contract.contractVersion ?? null,
             agentId,
+            runtime,
             registration,
+            technology: {
+                components: techComponents,
+                relationships: techRelationships,
+            },
             binding,
             companyId: creds.companyId,
         };

package/dist/index.js

@@ -31,7 +31,8 @@ Usage:
   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
+                                 --bind-relationship-type <code> --redact-hostname
+                                 --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.6" },
+        clientInfo: { name: "nexarch-cli", version: "0.1.8" },
     });
 }
 export async function mcpListTools() {

package/package.json

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