Nexum-Expanded/runtime/docs/integration.md

# 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.