# Nexum Integration Surfaces ## CLI ```bash nexum capabilities nexum tools list nexum tasks list --workspace ./workspace nexum artifacts list --workspace ./workspace nexum events --workspace ./workspace --session-id SESSION_ID nexum learning status --model /models/Nexum \ --state-dir ./state --state-namespace RELEASE_INSTANCE nexum approvals decide APPROVAL_ID approve \ --workspace ./workspace --session-id SESSION_ID ``` For a direct policy-controlled tool retry, preserve the same tool text, session, and call identifier, then attach the approved receipt: ```bash nexum tools execute "PatchRollback(patch_id='patch_...')" \ --workspace ./workspace --session-id SESSION_ID --call-id CALL_ID nexum approvals decide APPROVAL_ID approve \ --workspace ./workspace --session-id SESSION_ID nexum tools execute "PatchRollback(patch_id='patch_...')" \ --workspace ./workspace --session-id SESSION_ID --call-id CALL_ID \ --approval-id APPROVAL_ID ``` `nexum agent` runs the model-driven NNF X loop. There is no default host turn limit. A caller may cancel by disconnecting or by cancelling a durable task. Shared-learning rollback is an explicit operator recovery action. First inspect the validated status and candidate identity, then supply all three concurrency guards: ```bash nexum learning rollback --model /models/Nexum \ --state-dir ./state --state-namespace RELEASE_INSTANCE \ --target-generation 2 --expected-generation 3 \ --expected-candidate EXACT_CANDIDATE_SHA256 ``` The restored state is committed as the next generation so the decision history remains append-only. ## Engineering Evidence Workflow Reproduction, triage, disclosure, and patching are available through the same typed tool surface as terminal and repository operations. A typical model-owned sequence is: 1. `DraftCreate` records candidate actions or answers before an effect is taken. `DraftCompare` attaches evidence and observations; `DraftSelect` persists the model-selected route for the next action or final response. 2. `ReproductionRun` captures one contained run and model-selected file state; `ReproductionCompare` distinguishes stable output from environmental drift. 3. `TriageCreate` cites those receipts and records facts separately from hypotheses, impact, confidence, and unresolved investigation actions. `TriageUpdate` appends later evidence and next actions to the same case. 4. `PatchBegin` snapshots every covered file. `PatchApply` uses exact digests; `PatchVerify` binds real execution to the patch; `PatchCommit` checks that the verified bytes have not changed. `PatchRollback` restores exact original snapshots under the destructive-action policy. 5. `DisclosureCreate` can cite the triage and patch receipts while omitting raw command output, credentials, absolute paths, session identity, and private runtime state. `DisclosureStatus` reads the resulting sanitized receipt. 6. `EvidenceBundleCreate` can combine reproduction, triage, disclosure, and patch receipts into one sanitized handoff artifact for external systems or maintainers. `EvidenceBundleStatus` reads the bundle receipt without exposing raw private output. All records are session-scoped under `$NEXUM_HOME/engineering/` (or the host default `.nexum/engineering/`). There is no fixed number of reproduction runs, evidence receipts, patch files, or corrective iterations. Nexum selects the next action from current evidence and trained completion state. ## Integrated NoNE Coordination NNF X invokes one integrated Nexum forward path. It does not emulate internal coordination by repeatedly calling a single isolated model. The complete mapped bank set remains available to learned routing, and selected banks can run multiple specialist routes concurrently before returning one model-owned action or response. Those routes do not collapse immediately into a host-selected winner. Nexum keeps their proposals distinct long enough to measure disagreement, challenge the active draft, combine persistent outcome and repair evidence, and rehearse the result before its native output surface. Model-owned confidence and signed correction pressure determine how strongly rehearsal changes the current path. The runtime imposes no fixed bank, expert, or internal-agent count. Verified self-improvement pressure can grow session-owned banks from a model-selected donor, preserve transferred learned state, and use the expanded topology on the next forward. Mutable pages are restored only for their owning session after a clean restart. Verified promoted lineage can initialize a later session in the same operator namespace without receiving private page contents. Callers observe receipts and results but do not select the bank count or specialist paths. ## HTTP The server offers: - OpenAI-compatible chat and response endpoints; - `POST /agent/run` for the full model-driven tool loop; - `GET /self-improvement/status` and authenticated `POST /self-improvement/rollback` for versioned learning recovery; - `POST /mcp` for MCP JSON-RPC initialization, discovery, and calls; - `GET /.well-known/agent-card.json` and `POST /a2a` for delegated work; - task, approval, event, artifact, template, and capability endpoints. Server-side tool execution requires `--enable-tools` and a bearer key. A non-loopback listener always requires a bearer key. ## Caller-Owned Tools When Nexum selects a tool that the caller owns, `/agent/run` returns `external_tool_required` with the exact pending call. Preserve its ID, name, and arguments. Resume the same session and objective with: ```json { "session_id": "same-session", "prompt": "same objective", "tools": [ { "type": "function", "function": { "name": "CallerTool", "description": "Caller-owned operation", "parameters": { "type": "object", "properties": {"exact": {"type": "string"}}, "required": ["exact"], "additionalProperties": false } } } ], "tool_results": [ { "tool_call_id": "exact-call-id", "name": "CallerTool", "args": {"exact": "arguments"}, "ok": true, "executed": true, "output": "observed result" } ] } ``` The runtime persists the result before signing it. Changed IDs, names, arguments, answer fields, reward fields, or evaluator fields are rejected. If a direct completion contains a model action with an unknown function name or invalid arguments, the response keeps that exact action in `nexum.tool_action_protocol_rejected_calls`. A connector may submit those unchanged calls to `POST /tools/execute` to obtain signed `runtime_rejection` observations, then return those observations to the same session. The connector must not rename the function, rewrite its arguments, or substitute a different action; Nexum owns the corrected forward. For any selected function call, Nexum may include `depends_on` in the function arguments. Treat it as ordering metadata, not as an executable tool argument: return the cited parent results first, then return the dependent result with the ordinary arguments only. The runtime strips this field before execution and enforces that ordering before the next model turn receives signed observations. ## Structured Input `RequestInput` uses the same durable handoff. Its `output` must be a JSON value that satisfies the exact schema selected by Nexum. The open task resumes from the authenticated caller response. ## Long-Running Tasks `TaskStart` launches a detached workspace command without imposing a host time limit. `TaskStatus` returns durable progress and the final content-addressed artifact. `TaskCancel` is model-visible and policy controlled. Worker loss is recorded as a failed result so Nexum can correct instead of waiting indefinitely. ## Browser Extra ```bash python -m pip install './runtime[browser]' playwright install chromium ``` Browser profiles are scoped by workspace and session. Page content is marked untrusted. Navigation is limited to public HTTP(S) targets or files inside the selected workspace. Arbitrary script evaluation is not exposed as a tool.