@nexus-cortex/server 4.92.0 → 4.94.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cortex-subagent
|
|
3
|
+
description: >
|
|
4
|
+
Drive Nexus Cortex headlessly as a full autonomous SUB-AGENT from your own
|
|
5
|
+
agent harness — configure it, prompt it, budget it, and verify its output. Use
|
|
6
|
+
when another agent/harness (not a human at a TUI) should delegate a real task
|
|
7
|
+
to cortex: "run cortex as a subagent", "delegate this to cortex headlessly",
|
|
8
|
+
"use the cortex CLI/server to do X", "offload work to nexus-cortex". Covers the
|
|
9
|
+
three headless entry points, the operational config levers worth setting, how
|
|
10
|
+
to write a self-contained autonomous brief, isolation, and orchestrator-side
|
|
11
|
+
verification. NOT for interactive TUI use.
|
|
12
|
+
metadata:
|
|
13
|
+
short-description: "Drive nexus-cortex headlessly as an autonomous subagent from your own harness"
|
|
14
|
+
author: "nexus-cortex"
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# cortex-subagent — driving Nexus Cortex as an autonomous sub-agent
|
|
18
|
+
|
|
19
|
+
Nexus Cortex is a **headless harness**: the engine underneath an agent, not an app for a
|
|
20
|
+
human to sit in front of. Its highest-leverage use is as a **full-featured autonomous
|
|
21
|
+
sub-agent that your own agent/harness drives** — you (an LLM orchestrator) can configure and
|
|
22
|
+
prompt it far more precisely than a human clicking a UI. This skill is the operational
|
|
23
|
+
formula for doing that well.
|
|
24
|
+
|
|
25
|
+
> The authoritative config reference is **`docs/configuration.md`** + the annotated
|
|
26
|
+
> **`.env.example`** (every lever, with its ledgered status). This skill curates the
|
|
27
|
+
> *operationally important* levers and the *driving patterns*; it points at the ledger for
|
|
28
|
+
> values rather than duplicating it.
|
|
29
|
+
|
|
30
|
+
## 1. Three headless entry points — pick by shape
|
|
31
|
+
|
|
32
|
+
| Need | Entry point |
|
|
33
|
+
|---|---|
|
|
34
|
+
| One-shot autonomous task, get the final answer | **CLI:** `cortex --new --quiet -m <model> "<task>"` |
|
|
35
|
+
| Programmatic / streaming / many calls | **HTTP:** `POST http://localhost:4000/v1/messages` (Anthropic-shaped body) — the server **auto-starts on first use**, or run `cortex serve` |
|
|
36
|
+
| In-process, same runtime | **Library:** `import { CortexOrchestrator } from '@nexus-cortex/core'` |
|
|
37
|
+
|
|
38
|
+
Headless behavior that makes autonomy work: **tools auto-approve** (no permission prompts to
|
|
39
|
+
babysit) and the **server auto-starts** — a driver never has to interact. `--new` starts a
|
|
40
|
+
fresh session (no context bleed from a prior run); `--quiet` suppresses the CLI chrome so
|
|
41
|
+
stdout is the answer.
|
|
42
|
+
|
|
43
|
+
## 2. Always PIN the model
|
|
44
|
+
|
|
45
|
+
Pass `-m <exact-id>` (CLI), `"model": "<id>"` (HTTP), or set `DEFAULT_MODEL_ID`. Do **not**
|
|
46
|
+
rely on `auto`/the router when you need a *specific* model's behavior or cost — the router may
|
|
47
|
+
route per-task-type and silently swap the variable you care about. `cortex models list` prints
|
|
48
|
+
the live set (many providers; switch mid-flight, mix models across sub-agents).
|
|
49
|
+
|
|
50
|
+
## 3. The operational config surface (set what the task needs; leave the rest)
|
|
51
|
+
|
|
52
|
+
Set via `export VAR=…` before launch (inherited by the auto-spawned server), `cortex config
|
|
53
|
+
set VAR value` (writes `~/.cortex/.env`), or a project `.env`. **Echo a `config:` line at
|
|
54
|
+
launch to prove your vars are live** — a stale server reuses old config.
|
|
55
|
+
|
|
56
|
+
- **Autonomy** — headless already auto-approves tools; the permission engine still gates truly
|
|
57
|
+
destructive ops. For a fully hands-off run in a sandbox, that default is what you want.
|
|
58
|
+
- **Judgment quality (the mentor/gate family — opt-in):** these make a weaker/cheaper model
|
|
59
|
+
finish *correctly* more often. `MENTORSHIP_ENABLED` + `MENTORSHIP_HELPER_MODEL` (a stronger
|
|
60
|
+
model consulted on thrash); `CORTEX_LIFT_PLAN` (a bounded planner reads the task at turn-1 and
|
|
61
|
+
injects a plan + the real success criteria); `CORTEX_ENDTURN_GATE` + `CORTEX_ENDTURN_REQUIREMENTS`
|
|
62
|
+
(a finish is rejected unless each stated requirement is attested with proof); `CORTEX_ENDTURN_RESOLVER`
|
|
63
|
+
(a stronger model adjudicates the finish). Turn these on when correctness matters more than a
|
|
64
|
+
few extra cents/seconds; see `.env.example` for the tuning knobs (`*_EFFORT`, `*_BUDGET_TOKENS`, `*_TIMEOUT_MS`).
|
|
65
|
+
- **Tool surface:** `CORTEX_TOOL_ANCHOR` frames the model toward a tool style at turn-1 (e.g.
|
|
66
|
+
`bash-edit` for a shell/edit-native task). Tool profiles trade schema scaffolding (helps small
|
|
67
|
+
models) vs a lean surface (helps frontier models).
|
|
68
|
+
- **Budgets & failsafes** (see §5): `MAX_TOOL_ITERATIONS`, `TOOL_BUDGET_SOFT`, `CORTEX_TURN_DEADLINE_MS`.
|
|
69
|
+
|
|
70
|
+
## 4. Write a SELF-CONTAINED autonomous brief
|
|
71
|
+
|
|
72
|
+
A headless subagent gets one prompt and no chance to ask you a follow-up. So the brief must carry
|
|
73
|
+
everything:
|
|
74
|
+
- **The task + all context it needs** — don't assume it can see your conversation. Paste the
|
|
75
|
+
grounding (file paths, the mechanism, line pointers) into the brief.
|
|
76
|
+
- **An explicit deliverable + where to put it** — "edit `./src/x.ts` in place AND write
|
|
77
|
+
`./NOTES.md` describing the change + how you verified it." A concrete artifact is checkable.
|
|
78
|
+
- **Verification instructions** — tell it to run the build/tests/typecheck itself and report what
|
|
79
|
+
it did (it may not always succeed — see §6 — but asking makes it try).
|
|
80
|
+
- **Guardrails** — "do NOT touch other files / deploy / call live services." Headless = no human
|
|
81
|
+
veto, so state the boundaries.
|
|
82
|
+
- **Isolation** — run it in its own directory or a git worktree so parallel subagents (or a bad
|
|
83
|
+
run) can't corrupt shared state.
|
|
84
|
+
|
|
85
|
+
## 5. Bound the run — budgets are failsafes, not work limits
|
|
86
|
+
|
|
87
|
+
- `CORTEX_TURN_DEADLINE_MS` — a **wall-clock deadline**; at the limit the harness **force-
|
|
88
|
+
synthesizes** a best-effort finish instead of running forever. For a one-shot task (a single
|
|
89
|
+
turn), this effectively bounds the WHOLE task — set it to ~90% of your own timeout so cortex
|
|
90
|
+
converges before you'd kill it. (The clock starts at the tool-loop, i.e. after server boot and
|
|
91
|
+
any turn-1 planning — measure the loop, not total process wall, when checking if it fired.)
|
|
92
|
+
- `MAX_TOOL_ITERATIONS` — a hard cap on tool round-trips (a runaway-loop failsafe, set high).
|
|
93
|
+
- `TOOL_BUDGET_SOFT` — a soft pressure signal (nudges the model to converge as tool calls
|
|
94
|
+
accumulate); `<= 0` disables the budget-pressure system.
|
|
95
|
+
|
|
96
|
+
## 6. Verify the subagent's work — orchestrator-verifies-worker
|
|
97
|
+
|
|
98
|
+
Never ship a subagent's output on its self-report alone.
|
|
99
|
+
- **Do the authoritative check yourself** (the driver): run the build, `tsc`, the tests, or grep
|
|
100
|
+
the artifact. A subagent nested in a large repo copy sometimes *cannot* run its own
|
|
101
|
+
build/typecheck (install/git timeouts) and will fall back to inspection — so the driver owns the
|
|
102
|
+
real verification.
|
|
103
|
+
- **Discard-and-rerun confounded runs.** A `fetch failed` / transport error means the model call
|
|
104
|
+
died, not that the task is impossible — throw that run away and re-run (optionally a different
|
|
105
|
+
model). One transport wobble is not a result.
|
|
106
|
+
- For high-value tasks, run **N candidates** and keep the best (see the `best-of-n` skill), or
|
|
107
|
+
gate the result with the `verify-work` skill.
|
|
108
|
+
|
|
109
|
+
## 7. Sessions & memory
|
|
110
|
+
|
|
111
|
+
`--new` per task for isolation; omit it to continue a session. Sessions persist to disk; enable
|
|
112
|
+
**canon** (`docs/CANON.md`) for provider-neutral, cross-harness memory so a task's context can be
|
|
113
|
+
handed to another model or harness later.
|
|
114
|
+
|
|
115
|
+
## Pointers
|
|
116
|
+
- **`docs/configuration.md`** + **`.env.example`** — the canonical lever ledger (values + status).
|
|
117
|
+
- **`docs/user-guide.md`** — the full CLI, the HTTP server, the REST API, sessions, deployment.
|
|
118
|
+
- **`docs/authentication.md`** — API keys and the Claude OAuth-subscription path.
|
|
119
|
+
- **`docs/CANON.md`** — portable agent memory / cross-harness handoff.
|
|
120
|
+
- Related skills: **`best-of-n`** (parallel tournament), **`verify-work`** (adversarial verification), **`cortex-bench`** (measuring the harness).
|
package/dist/routes/config.js
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* PUT /config/:key — set value, hot-apply when possible
|
|
8
8
|
*/
|
|
9
9
|
import { Router } from 'express';
|
|
10
|
-
import { SettingsLoader,
|
|
10
|
+
import { SettingsLoader, setGlobalSetting, SETTINGS_METADATA, getRuntimeConfigEntry, isLiveToggleable, } from '@nexus-cortex/core';
|
|
11
11
|
import { getServerOrchestrator } from './messages.js';
|
|
12
12
|
export const configRouter = Router();
|
|
13
13
|
function getProjectPath() {
|
|
@@ -50,8 +50,9 @@ configRouter.put('/config/:key', (req, res) => {
|
|
|
50
50
|
res.status(400).json({ error: 'Missing "value" in request body' });
|
|
51
51
|
return;
|
|
52
52
|
}
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
// Harness config is GLOBAL: write a single sparse override to ~/.cortex/.env (not a
|
|
54
|
+
// full-file regen at PROJECT_PATH, which would re-freeze every lever).
|
|
55
|
+
setGlobalSetting(key, String(value));
|
|
55
56
|
process.env[key] = String(value);
|
|
56
57
|
const entry = getRuntimeConfigEntry(key);
|
|
57
58
|
if (entry?.tier === 'config' && entry.mapper) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/routes/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EACL,cAAc,EACd,
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/routes/config.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nexus-cortex/server",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.94.0",
|
|
4
4
|
"description": "Thin Express server wrapper for Nexus Cortex core library",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -20,8 +20,8 @@
|
|
|
20
20
|
"prepack": "node ../../scripts/copy-pkg-cortex-scaffold.mjs"
|
|
21
21
|
},
|
|
22
22
|
"dependencies": {
|
|
23
|
-
"@nexus-cortex/core": "4.
|
|
24
|
-
"@nexus-cortex/executors": "4.
|
|
23
|
+
"@nexus-cortex/core": "4.94.0",
|
|
24
|
+
"@nexus-cortex/executors": "4.94.0",
|
|
25
25
|
"chalk": "^5.3.0",
|
|
26
26
|
"cors": "^2.8.5",
|
|
27
27
|
"dotenv": "^16.4.5",
|