graft-comboagent

Problems it solves

Engineers split time between:

• Cloud combo agent: heavy analysis (ASPICE traces, requirement audits, baseline deltas, novelty search) with artifacts in the cloud KB
• Local IDE: coding, tests, PRs, docs

Bridging is more than pasting session blurbs. graft-comboagent packages three usage modes:

A is pure RAG (no session spin-up). B is read-only graft. C is the only write path—it cannot create/delete sessions or files; it only appends a turn to an existing session.

Architecture

• Server: api/apps/graft_app.py exposes user-scoped HTTPS endpoints
• Auth: reuse UI signed_auth_token (itsdangerous) after /v1/user/login
• Client: Python helpers (login / whoami / logout / call) plus bundled public.pem
• Writes such as register_artifact, copy_kb_document, save_* blocked client- and server-side—only dispatch_task escapes read-only posture

Install

graft-comboagent lives under skills/graft-comboagent/ (Nox-Lumen-tech/combo-skills). Copy or symlink into the host:

Cursor also scans ~/.claude/skills/ and ~/.codex/skills/, so one symlink under ~/.cursor/skills/ often covers every host.

Restart after first install (Claude watches running sessions live, yet new root folders still need restart).

Dependencies:

pip install requests pycryptodome

Legacy pycrypto installs still work—login.py falls back automatically.

First run (three steps)

Step 1 — login

cd ~/.cursor/skills/graft-comboagent   # wherever you installed
python scripts/login.py

Interactive prompt:

ragbase server URL [https://xipnex.nox-lumen.com]:
email: me@example.com
password: ********
[OK] Logged in as me@example.com (user=ab12cd34…)

Default hostname is https://xipnex.nox-lumen.com; override if you self-host.

Behind the scenes:

1. Reads public.pem beside SKILL.md
2. RSA-encrypts the password (same routine as the web UI crypt())
3. POST /v1/user/login → signed_auth_token
4. Writes ~/.config/graft-comboagent/token.json with chmod 0600

Step 2 — verify

python scripts/whoami.py

Sample output:

email      : me@example.com
user_id    : ab12cd34ef…
server     : https://xipnex.nox-lumen.com
token_path : /home/me/.config/graft-comboagent/token.json

Step 3 — exercise all three modes

# A. KB search
python scripts/call.py list_kbs
python scripts/call.py search --query cooling --source document --kb-ids "ASPICE engineering KB"
 
# B. Session graft
python scripts/call.py list_sessions --query cooling
python scripts/call.py get_digest --session-id "Cooling system analysis"
 
# C. Dispatch
python scripts/call.py dispatch_task --session-id "Cooling system analysis" \
  --prompt "Re-run ASPICE trace against newly pushed src/cooling/*.c"

Action catalog

Everything routes through scripts/call.py; tokens load automatically from ~/.config/graft-comboagent/token.json.

The pack ships references/action-decision-tree.md—branch on user intent (“find a doc”, “inspect a session”, “offload work to cloud”) before choosing actions.

A · KB search (session optional)

search --source document fans out to platform unified_search (BM25 + vectors + rerank)—same stack as the product chat box.

B · Session graft (read-only)

Focused read_file modes

Default behavior returns the whole markdownized document. For >20K-token files, narrow the window:

# 1) Keyword window—server grep first
python scripts/call.py read_file --path <p> --find "DFMEA failure mode" --max-find-matches 3
 
# 2) Line window—anchor around line 1200 ±50
python scripts/call.py read_file --path <p> --center-line 1200 --context-lines 50

C · Dispatch (only write path)

python scripts/call.py dispatch_task \
  --session-id "ASPICE analysis" \
  --prompt "Pull latest main commits and rerun SRS-to-code trace for src/cooling"

Mechanics:

1. Server queues a new conversational round
2. HTTP returns immediately (non-blocking IDE)
3. Cloud worker executes asynchronously
4. Poll with list_sessions, get_digest, or newest get_round

Limits: cannot spawn/delete sessions/files—only append turns.

Names vs. UUIDs for session_id / kb_id

Aligned with tenant kb_ids / naming rules—either UUIDs or human labels resolve server-side:

python scripts/call.py get_digest --session-id "Cooling study"       # friendly name
python scripts/call.py get_digest --session-id 7b3c…                 # UUID
python scripts/call.py search --kb-ids "ASPICE engineering KB,EEA platform KB"  # comma list

If multiple names collide, ask the user—never guess.

Response envelope

Stdout is JSON:

{
  "success": true,
  "data": { /* action-specific payload */ }
}

Failures:

{
  "success": false,
  "code": "ACCESS_DENIED",   // or SESSION_NOT_FOUND / FILE_TOO_LARGE / ACTION_NOT_ALLOWED
  "message": "...",
  "hint": "optional friendly guidance"
}

LLMs should read code + hint before blind retries.

Context throttling rules

Local windows are tighter than cloud Agents. Follow SKILL.md discipline:

1. Start with get_digest for session recon (≈5–20K tokens)
2. Drill into get_round only when digest points to critical rounds
3. Never dump entire binaries into prompts—use read_file --find/--center-line; download goes to disk, not chat
4. KB queries default --source document—don’t scan all rounds unless you intend graft mode B
5. No brute-force scraping—forbid looping all rounds, entire chunk lists, or mass downloads

Breaking these bursts local context budgets after a handful of calls.

Three cookbook flows

Flow A · Cloud KB as local RAG

“While coding an EEA init routine locally, cite canonical samples from cloud ‘EEA platform KB’.”

Key: locate a few chunks, then --find; don’t hydrate whole libraries.

Flow B · Graft cloud session conclusions

“Using cloud session ‘ASPICE study’ DFMEA output, audit local src/ for uncovered SRS clauses.”

Flow C · Cloud continues heavy lifting

“I pushed fixes—have the cloud session re-run ASPICE trace; I’ll poll later.”

Dispatch keeps the IDE unblocked—queue analysis, resume coding, fetch conclusions minutes later.

Environment variables

Server requirements

Rolling clusters need:

1. /v1/user/login embedding signed_auth_token (api/apps/user_app.py)
2. api/apps/graft_app.py routes:
   • POST /v1/graft/memory/unified_search — modes A+B JSON actions
   • GET /v1/graft/memory/download — binary streaming
   • POST /v1/graft/dispatch — enqueue prompts

All endpoints sit behind @login_required sharing _verify_graft_access (tenant + ACL + mutation guard).

Clients pass Authorization: Bearer <signed_auth_token>.

Known limitations

• Mostly read-only aside from dispatch_task; even dispatch cannot mutate session lifecycle or arbitrary files—only enqueue turns
• Single profile: one ragbase hostname per login; switch hosts via logout.py + login or alternate token paths
• No browser SSO: email/password today (OAuth requests go through PM)
• Downloads ≤200 MB enforced server-side
• Dispatch lacks synchronous results—always poll afterward

Troubleshooting

Cloud builtin graft comparison

Related docs

• Local coding agent hub
• skills/agentic/graft
• Graft concept
• ASPICE engineering loop
• Nox-Lumen-tech/combo-skills