@kontextmind/kxm 0.6.0

package/examples/README.md

@@ -0,0 +1,102 @@
+# Examples
+
+These examples demonstrate the transport without requiring an AI model. Run them from the repository root after `npm ci`.
+
+The [`.kxm/config/workflows/jira-development.json`](../.kxm/config/workflows/jira-development.json) workspace configuration is a production-oriented definition for a long-lived coordinator. It covers reproduction, single-agent or three-agent planning, plan review, implementation, local and repository gates, documentation, push/watch retries, merge, Jira update, and continuous improvement. Follow [Webhook workflows](../docs/webhook-workflows.md) to configure it.
+
+The [`workflow-signal.ts`](workflow-signal.ts) sender demonstrates the signed callback that resumes a coordinator after CI, review, merge, or Jira work completes. The webhook guide documents its required environment and arguments.
+
+The [`provenance-workflow.json`](provenance-workflow.json) definition is a
+minimal command-first quorum example. It requires two eligible peer replies for
+one exact run, stage, requirement, and attempt, while demonstrating an optional
+admin-approved one-peer degradation. Its tested topology is project
+`provenance-demo`, coordinator `coordinator`, and reviewers `reviewer-claude`
+and `reviewer-grok`. Follow
+[Peer provenance and quorum gates](../docs/provenance-gates.md) for the complete
+runbook and trust boundary.
+
+The [`vnext`](vnext/README.md) directory is a machine-validated planned-contract
+fixture for the local-first KXM vNext architecture. Production configuration
+loader tests consume it, but no current Runtime executes its workflows.
+
+## Self-contained round trip
+
+Start an in-memory hub, connect a planner and reviewer, send an idempotent request, and print the reply:
+
+```powershell
+npm run example
+```
+
+Expected result:
+
+```json
+{
+  "peers": [
+    "example-reviewer",
+    "example-planner"
+  ],
+  "status": "replied",
+  "reply": "Reviewed: Check the rollout plan"
+}
+```
+
+The message ID is generated at runtime and is omitted above.
+
+## Custom reviewer client
+
+With the normal hub running, start a deterministic reviewer:
+
+```powershell
+$env:KXM_AUTH_TOKEN = "replace-with-your-token"
+$env:KXM_PROJECT = "example"
+node --experimental-strip-types examples/reviewer-agent.ts
+```
+
+This sample echoes requests to demonstrate acknowledgement and reply mechanics. It does not perform a real review and should not be used as an approval bot.
+
+Send it a request from another terminal:
+
+```powershell
+$env:KXM_AUTH_TOKEN = "replace-with-your-token"
+$env:KXM_PROJECT = "example"
+node --experimental-strip-types examples/requester.ts example-reviewer "Check the rollout plan"
+```
+
+## Agent use cases
+
+### Plan then review
+
+```text
+Use kxm. Ask planner to produce a bounded implementation plan, then
+ask reviewer to identify correctness and security risks. Verify both responses
+before making changes.
+```
+
+### Implement with separate ownership
+
+```text
+Use kxm. Give api-builder ownership of src/api only and ui-builder
+ownership of src/ui only. Ask each for changed paths and test results. Do not
+let either agent edit shared configuration.
+```
+
+### Non-blocking delegation
+
+```text
+Send reviewer a request with kxm_send, retain the message ID, continue the
+independent implementation, then use kxm_get before deciding whether to wait.
+```
+
+### Cancel obsolete work
+
+```text
+If a sent request is no longer relevant, call kxm_cancel with its message ID.
+Do not treat cancellation as rollback: verify whether the peer already changed
+files or external state.
+```
+
+### Retry safely
+
+Supply a stable `idempotencyKey` when an automated caller might retry the same
+send after a network failure. Reusing the key with different content returns a
+conflict instead of silently creating ambiguous work.

package/examples/provenance-workflow.json

@@ -0,0 +1,40 @@
+[
+  {
+    "id": "provenance-review",
+    "source": "generic",
+    "project": "provenance-demo",
+    "target": "coordinator",
+    "secretEnv": "KXM_WORKFLOW_SECRET",
+    "delivery": "followUp",
+    "promptTemplate": "Review {{task.id}}: {{task.summary}}. Collect independent peer findings, preserve contradictions, and make an evidence-backed decision.",
+    "stages": [
+      {
+        "id": "review",
+        "label": "Independent review",
+        "instructions": "Ask both eligible reviewers independently with one kxm_fanout call. Set correlationId to the exact run ID, timeoutMs to 120000, and idempotencyKeyPrefix to the deterministic value provenance-review:<runId>:review:<attempt>. The tool call itself must include workflowContext for this run, stage review, requirement independent peer reviews, and the current attempt; stating that context in a plan is not sufficient. Treat every returned messageId as the durable handle immediately. Use kxm_get to verify each stored message has the exact run, stage, requirement, and attempt binding. For every pending reply, call kxm_await with that messageId and timeoutMs 120000; never replace pending work with a new idempotency prefix. On interruption or uncertain delivery, repeat the exact fanout parameters so the hub returns the same messages. Re-read and verify each durable message after it replies. Compare findings, record contradictions and the chosen resolution, then cite only the bound durable replied message IDs.",
+        "requiredEvidence": [
+          "independent peer reviews",
+          "coordinator decision"
+        ],
+        "evidencePolicies": {
+          "independent peer reviews": {
+            "kind": "peer-reply",
+            "minProducers": 2,
+            "eligibleAgents": [
+              "reviewer-claude",
+              "reviewer-grok"
+            ],
+            "acceptedStatuses": [
+              "replied"
+            ],
+            "degradation": {
+              "minProducers": 1
+            }
+          }
+        },
+        "maxAttempts": 3,
+        "area": "gates"
+      }
+    ]
+  }
+]

package/examples/requester.ts

@@ -0,0 +1,30 @@
+import { randomUUID } from "node:crypto";
+import { HubClient } from "../plugins/kxm/src/client.ts";
+
+const [target, ...contentParts] = process.argv.slice(2);
+if (!target || contentParts.length === 0) {
+  throw new Error("usage: requester.ts <target> <request text>");
+}
+
+const authToken = process.env.KXM_AUTH_TOKEN;
+const client = new HubClient({
+  serverUrl: process.env.KXM_SERVER_URL ?? "http://127.0.0.1:7331",
+  name: process.env.KXM_AGENT_NAME ?? `example-requester-${process.pid}`,
+  purpose: process.env.KXM_AGENT_PURPOSE ?? "Sends a request from the command line",
+  project: process.env.KXM_PROJECT ?? "example",
+  ...(authToken ? { authToken } : {}),
+});
+
+try {
+  await client.start(() => undefined);
+  const request = await client.send({
+    target,
+    content: contentParts.join(" "),
+    idempotencyKey: randomUUID(),
+  });
+  process.stdout.write(`sent ${request.id}; waiting for ${target}\n`);
+  const completed = await client.awaitResponse(request.id);
+  process.stdout.write(`${JSON.stringify(completed, null, 2)}\n`);
+} finally {
+  await client.stop();
+}

package/examples/reviewer-agent.ts

@@ -0,0 +1,29 @@
+import { HubClient } from "../plugins/kxm/src/client.ts";
+
+const serverUrl = process.env.KXM_SERVER_URL ?? "http://127.0.0.1:7331";
+const authToken = process.env.KXM_AUTH_TOKEN;
+const project = process.env.KXM_PROJECT ?? "example";
+const client = new HubClient({
+  serverUrl,
+  name: process.env.KXM_AGENT_NAME ?? "example-reviewer",
+  purpose: process.env.KXM_AGENT_PURPOSE ?? "Demonstrates a custom mesh client",
+  project,
+  ...(authToken ? { authToken } : {}),
+});
+
+await client.start(async (event) => {
+  if (event.type !== "message") return;
+  await client.acknowledge(event.message.id);
+  process.stdout.write(`request from ${event.message.fromName}: ${event.message.content}\n`);
+  await client.reply(event.message.id, `Example client received: ${event.message.content}`);
+});
+
+process.stdout.write(`reviewer connected as ${client.agent!.name} in ${project}\n`);
+
+async function shutdown(): Promise<void> {
+  await client.stop();
+  process.exit(0);
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/examples/roundtrip.ts

@@ -0,0 +1,46 @@
+import { HubClient } from "../plugins/kxm/src/client.ts";
+import { createMeshHub } from "../plugins/kxm/src/hub.ts";
+
+const token = "local-example-token";
+const hub = createMeshHub({ port: 0, authToken: token, rateLimit: false });
+const address = await hub.start();
+const planner = new HubClient({
+  serverUrl: address.url,
+  authToken: token,
+  name: "example-planner",
+  purpose: "Delegates a focused example task",
+  project: "example",
+});
+const reviewer = new HubClient({
+  serverUrl: address.url,
+  authToken: token,
+  name: "example-reviewer",
+  purpose: "Returns a deterministic example review",
+  project: "example",
+});
+
+try {
+  await reviewer.start(async (event) => {
+    if (event.type !== "message") return;
+    await reviewer.acknowledge(event.message.id);
+    await reviewer.reply(event.message.id, `Reviewed: ${event.message.content}`);
+  });
+  await planner.start(() => undefined);
+  const peers = await planner.listAgents();
+  const request = await planner.send({
+    target: "example-reviewer",
+    content: "Check the rollout plan",
+    idempotencyKey: "example-roundtrip-1",
+    ttlMs: 10_000,
+  });
+  const completed = await planner.awaitResponse(request.id, 3_000);
+  process.stdout.write(`${JSON.stringify({
+    peers: peers.map((peer) => peer.name),
+    messageId: completed.id,
+    status: completed.status,
+    reply: completed.reply?.content,
+  }, null, 2)}\n`);
+} finally {
+  await Promise.allSettled([planner.stop(), reviewer.stop()]);
+  await hub.close();
+}

package/examples/vnext/.kxm/agents/coordinator.yaml

@@ -0,0 +1,16 @@
+schema: kxm.agent.v1
+purpose: Coordinate the pinned workflow and emit only schema-validated commands.
+model:
+  profile: primary
+tools:
+  preset: coordinator
+defaultRepositoryAccess: read
+repositories:
+  control: read
+  api: read
+  web: read
+network: restricted
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope
+  maxIdleMs: 1800000

package/examples/vnext/.kxm/agents/critic-1.yaml

@@ -0,0 +1,16 @@
+schema: kxm.agent.v1
+purpose: First fixed-identity critic for migrated strict producer policies.
+harness: claude
+model:
+  profile: critic-claude
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+  api: read
+  web: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope

package/examples/vnext/.kxm/agents/critic-2.yaml

@@ -0,0 +1,15 @@
+schema: kxm.agent.v1
+purpose: Second fixed-identity critic for migrated strict producer policies.
+model:
+  profile: critic-grok
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+  api: read
+  web: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope

package/examples/vnext/.kxm/agents/critic-3.yaml

@@ -0,0 +1,15 @@
+schema: kxm.agent.v1
+purpose: Third provider-distinct critic used by the vNext MOA target.
+model:
+  profile: critic-gemini
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+  api: read
+  web: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope

package/examples/vnext/.kxm/agents/implementer.yaml

@@ -0,0 +1,15 @@
+schema: kxm.agent.v1
+purpose: Implement the approved plan in the assignment-owned repository worktree.
+model:
+  tag: implementation
+tools:
+  preset: workspace-writer
+defaultRepositoryAccess: none
+repositories:
+  control: read
+  api: write
+  web: write
+network: provider-only
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope

package/examples/vnext/.kxm/agents/planner.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Produce an implementation plan grounded in the pinned repositories and evidence.
+model:
+  tag: planning
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+  api: read
+  web: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/examples/vnext/.kxm/agents/reproducer.yaml

@@ -0,0 +1,15 @@
+schema: kxm.agent.v1
+purpose: Create and execute a production-coupled failing reproduction without changing production code.
+model:
+  tag: implementation
+tools:
+  preset: tests-writer
+defaultRepositoryAccess: none
+repositories:
+  control: read
+  api: write
+  web: write
+network: provider-only
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope

package/examples/vnext/.kxm/agents/reviewer.yaml

@@ -0,0 +1,15 @@
+schema: kxm.agent.v1
+purpose: Independently review correctness, security, regression risk, and evidence.
+model:
+  tag: critic
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+  api: read
+  web: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1
+session:
+  reuse: compatible-run-scope

package/examples/vnext/.kxm/gates.yaml

@@ -0,0 +1,8 @@
+schema: kxm.gate-registry.v1
+gates:
+  test:
+    kind: command
+    argv: [npm, test]
+    timeoutMs: 3600000
+  scm-delivery:
+    kind: reserved

package/examples/vnext/.kxm/models/critic-claude.yaml

@@ -0,0 +1,11 @@
+schema: kxm.model.v1
+provider: anthropic
+model: claude-fable-5-1
+tags:
+  - critic
+capabilities:
+  - tools
+  - structured-output
+priority: 100
+limits:
+  timeoutMs: 1800000

package/examples/vnext/.kxm/models/critic-gemini.yaml

@@ -0,0 +1,11 @@
+schema: kxm.model.v1
+provider: google
+model: gemini-3.1-pro-preview
+tags:
+  - critic
+capabilities:
+  - tools
+  - structured-output
+priority: 80
+limits:
+  timeoutMs: 1800000

package/examples/vnext/.kxm/models/critic-grok.yaml

@@ -0,0 +1,12 @@
+schema: kxm.model.v1
+provider: xai
+model: grok-4.6
+thinking: high
+tags:
+  - critic
+capabilities:
+  - tools
+  - structured-output
+priority: 90
+limits:
+  timeoutMs: 1800000

package/examples/vnext/.kxm/models/implementation.yaml

@@ -0,0 +1,14 @@
+schema: kxm.model.v1
+provider: anthropic
+model: claude-sonnet-4-6
+thinking: high
+tags:
+  - implementation
+capabilities:
+  - tools
+  - structured-output
+priority: 100
+limits:
+  contextTokens: 200000
+  outputTokens: 32000
+  timeoutMs: 1800000

package/examples/vnext/.kxm/models/primary.yaml

@@ -0,0 +1,17 @@
+schema: kxm.model.v1
+provider: xai
+model: grok-4.6
+thinking: high
+tags:
+  - primary
+  - planning
+capabilities:
+  - tools
+  - structured-output
+priority: 100
+fallbacks:
+  - profile: implementation
+limits:
+  contextTokens: 200000
+  outputTokens: 32000
+  timeoutMs: 1800000

package/examples/vnext/.kxm/prices.yaml

@@ -0,0 +1,111 @@
+schema: kxm.prices.v1
+date: "2026-09-08"
+sha256: 949aac1795e626204a093b7a70a398412c6128e241adf012652ca7abe79018ae
+currency: USD
+models:
+  - id: anthropic/claude-3-7-sonnet
+    provider: anthropic
+    model: claude-3-7-sonnet
+    aliases:
+      - fable
+      - claude-3-7-sonnet-latest
+    tiers:
+      - upToContextTokens: 200000
+        inputPerMillion: 3.00
+        outputPerMillion: 15.00
+        cacheReadPerMillion: 0.30
+        cacheWritePerMillion: 3.75
+
+  - id: anthropic/claude-3-5-sonnet
+    provider: anthropic
+    model: claude-3-5-sonnet
+    aliases:
+      - claude-3-5-sonnet-latest
+    tiers:
+      - upToContextTokens: 200000
+        inputPerMillion: 3.00
+        outputPerMillion: 15.00
+        cacheReadPerMillion: 0.30
+        cacheWritePerMillion: 3.75
+
+  - id: openai/gpt-5.6-sol
+    provider: openai
+    model: gpt-5.6-sol
+    aliases:
+      - gpt-5.6-sol
+      - gpt-4o
+    tiers:
+      - upToContextTokens: 128000
+        inputPerMillion: 2.50
+        outputPerMillion: 10.00
+        cacheReadPerMillion: 1.25
+        cacheWritePerMillion: 2.50
+
+  - id: openai/o3-mini
+    provider: openai
+    model: o3-mini
+    tiers:
+      - upToContextTokens: 200000
+        inputPerMillion: 1.10
+        outputPerMillion: 4.40
+        cacheReadPerMillion: 0.55
+        cacheWritePerMillion: 1.10
+
+  - id: xai/grok-4.6
+    provider: xai
+    model: grok-4.6
+    aliases:
+      - grok-4.6
+    tiers:
+      - upToContextTokens: 131072
+        inputPerMillion: 2.00
+        outputPerMillion: 10.00
+        cacheReadPerMillion: 0.50
+        cacheWritePerMillion: 2.00
+
+  - id: xai/grok-2
+    provider: xai
+    model: grok-2
+    tiers:
+      - upToContextTokens: 131072
+        inputPerMillion: 2.00
+        outputPerMillion: 10.00
+        cacheReadPerMillion: 0.50
+        cacheWritePerMillion: 2.00
+
+  - id: zhipu/glm-4-plus
+    provider: zhipu
+    model: glm-4-plus
+    aliases:
+      - glm-4
+    tiers:
+      - upToContextTokens: 128000
+        inputPerMillion: 1.40
+        outputPerMillion: 1.40
+        cacheReadPerMillion: 0.14
+        cacheWritePerMillion: 1.40
+
+  - id: moonshot/kimi-k1.5
+    provider: moonshot
+    model: kimi-k1.5
+    aliases:
+      - moonshot-v1-128k
+    tiers:
+      - upToContextTokens: 128000
+        inputPerMillion: 1.00
+        outputPerMillion: 2.00
+        cacheReadPerMillion: 0.20
+        cacheWritePerMillion: 1.00
+
+  - id: alibaba/qwen3-coder-plus
+    provider: alibaba
+    model: qwen3-coder-plus
+    aliases:
+      - openrouter/qwen/qwen3-coder-plus
+      - qwen/qwen3-coder-plus
+    tiers:
+      - upToContextTokens: 131072
+        inputPerMillion: 1.00
+        outputPerMillion: 3.00
+        cacheReadPerMillion: 0.20
+        cacheWritePerMillion: 1.00

package/examples/vnext/.kxm/project/env.yaml

@@ -0,0 +1,7 @@
+schema: kxm.environment.v1
+values:
+  CI: false
+  DOTNET_NOLOGO: "1"
+path:
+  prepend:
+    - tools

package/examples/vnext/.kxm/project.yaml

@@ -0,0 +1,32 @@
+schema: kxm.project.v1
+id: prj_01JPROJECT00000000000000000
+name: Payments Platform
+description: Example control project with API and web member repositories.
+defaultWorkflow: default
+defaultExecutor: local
+defaultHarness: pi
+repositories:
+  - id: control
+    role: control
+    required: true
+    pathHint: .
+  - id: api
+    role: member
+    required: true
+    remoteIdentity: ssh://git.example.test/payments/api.git
+    pathHint: repositories/api
+  - id: web
+    role: member
+    required: true
+    remoteIdentity: ssh://git.example.test/payments/web.git
+    pathHint: repositories/web
+workspace:
+  dirtySnapshot:
+    untracked: bounded
+    maxUntrackedFileBytes: 26214400
+    maxUntrackedTotalBytes: 262144000
+    dirtySubmodules: fail
+limits:
+  maxConcurrentRuns: 4
+  maxRunDurationMs: 28800000
+  maxAgentTimeMs: 57600000

package/examples/vnext/.kxm/repo/repo.yaml

@@ -0,0 +1,8 @@
+schema: kxm.repository.v1
+projectId: prj_01JPROJECT00000000000000000
+repositoryId: control
+description: Authoritative project configuration and optional application code.
+ecosystems:
+  - node
+classification: internal
+defaultAccess: read