Bring docs/integration/heicode-desktop-client-api.md in lock-step with merged
endpoints:
- §3.1 /api/heicode/available-models: logged-in user model list is the single
source of truth (no local presets / no CodeGW channel backend); exposes only
model_id/display_name/default; forbidden fields enumerated.
- §5.1 /api/heicode/agents/{id}/usage: token-name aggregation, time window,
empty-data semantics, relation to billing logs. Includes the #30 hidden agent
model token billing-collection semantics: UnlimitedQuota only waives the
token's own remaining-quota cap, it does NOT bypass user.Quota — HM still
checks user quota and settles to wallet/subscription via the billing
expression; token revoked on stop/delete; hidden from user UI but auditable.
- §7.1 /api/heicode/config: telemetry enabled/endpoint/max_batch/flush/retention_days.
- §7.2 /api/heicode/telemetry/events: default-off 410 kill switch, V2 device
signature, top-level array 1-20 / <=256KB, server redaction, context field
whitelist (#32), 4xx-drop/5xx-retry, retention; production enable-gate note.
- Updated §10 endpoint inventory.
Docs-only; no code change. heicodeDocs org-level sync tracked in #34.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per Fasthei's CHANGES_REQUESTED on #15: deleting all sub/swarm docs left no
tracking entry for the still-in-development swarm capability. Adds
docs/integration/heicode-swarm-deferred.md stating HM does not implement swarm
runtime, the old HM-orchestrated sub/swarm model is deprecated, new swarm work
lives on AM/Swarm side, and a per-file migration mapping (deprecated / deferred
/ superseded) for all 11 deleted docs. Links it from docs/README.md so deletion
no longer drops context.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Token IS transmitted by HM (confirmed); the agent didn't enforce it because AM
hadn't deployed the image containing the §5 check to production. So the debug
log is unnecessary — removed. Contract §0.1 updated: token-check is "code-ready,
pending AM prod image", not a HM gap. UI access-token/direct-URL display kept.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
AM shipped its updated runtime + fixes; live re-test confirms deploy → running
→ direct /health & /message/send (task completed) → stop → delete all pass, and
HM's per-agent access_token is minted + returned (non-empty UUID). Two AM-side
gaps remain: (1) the running agent does NOT enforce X-Agent-Access-Token
(no-token request still 200, agent card auth_required=None) — token isolation
not actually active; (2) subdomain is http:// (token + api_key in cleartext).
Contract §0.1 and client doc status notes updated accordingly.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- AM contract: fix stale lifecycle path defaults in the env-override table
(/agents/{agent_id}, /agents/{agent_id}/stop — matches code, not the old
/api/agent/... values); correct the self-check create line to POST /agents;
align the verify-endpoint example to the real production response shape
(user_id is a string, agent_id included, miss returns {valid:false}).
- Client API: §0 overview now states HM mints the per-agent access_token
(AM no longer "returns" it).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per the chosen design, the agent authorizes callers by comparing the request
header X-Agent-Access-Token against its env AGENT_ACCESS_TOKEN (constant-time),
no HM round-trip. AM contract §3.1 now states ① as the agreed integration with
Python pseudo-code; the /agent-access/verify endpoint is demoted to an optional
fallback. Client API §6 spells out the client's job: send X-Agent-Access-Token
on every direct-connect request.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
HM now mints a random per-agent access token at deploy, injects it into the
agent env (AGENT_ACCESS_TOKEN + HEICODE_AGENT_ID) and returns it to the
deploying client (agent list access_token). Only the owning user receives it,
so only they can drive the agent — closing the gap where any valid sk- could
drive any agent and exfiltrate its mounted resources.
AM authorizes the caller either locally (compare to its env token) or via the
new public POST /api/heicode/agent-access/verify {agent_id, access_token} ->
{valid, user_id} (constant-time compare, no info leak on miss). AM may opt out.
Docs: AM contract §3.1 + client API §6 updated; access_token no longer empty.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- new §0.1 联调结果: real production test outcomes — create POST /agents works
(returns access_info.domain/namespace), DELETE /agents/{id} 500s (AM
UnboundLocalError bug), POST /agents/{id}/stop 404 (no endpoint), agent stays
Pending / subdomain unreachable. The 3 AM-side blockers listed up top.
- OPENAI_API_KEY is now injected (a minted user new-api sk-, billed to the user,
revoked on delete; verified working at /v1) — §1.1 env + §2 updated.
- §3 client<->agent: now documents AM's A2A protocol (message/send · stream),
api_key auth, and flags the per-user isolation security gap.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Ran the full desktop-client flow against production (real account) and updated
the doc to the verified responses:
- capabilities model = gpt-5.4; modes still returned but ignored.
- agent object: access_token is "" (AM issues none — connect via A2A api_key),
subdomain is a host (dep-xxx.taijiagnet.com), status starts Pending; real
binding_ids; shown as "生产实测" examples.
- §4: clarified the template `model` field is a role-tier hint (opus), not the
runtime model (gpt-5.4 injected at deploy).
- §5: stop currently fails / delete returns runtime_cleanup:"failed" (AM stop
missing + delete bug); HM removes the local record regardless.
- §6: must wait for status=running / health 200 before connecting; noted the
agent currently stays Pending and the subdomain isn't reachable yet (AM side).
- top banner: per-endpoint production verification note.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Preset templates carry a Claude-style frontmatter model (opus/sonnet) which is
NOT a model on the HM gateway. Passing it as MODEL_NAME would make the agent's
model calls fail. Now MODEL_NAME defaults to the gateway model gpt-5.4
(env AGENT_RUNTIME_DEFAULT_MODEL); a non-Claude-tier template model is honored.
Tests + AM contract doc updated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
POST /api/devices/logout (UserOrV2DeviceAuth): a device-signed client revokes its
OWN bound token via the signed X-Heicode-Device-Id (cannot touch other devices);
a session/JWT caller may pass {device_id}. Idempotent. The existing DELETE
/api/devices/:id revoke is session-only, so device clients had no self-logout —
this closes that gap. Documented in the client API doc §1.1.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Real production test (user account) confirmed HM->AM POST /agents creates a real
agent (returned subdomain + status). But stop/delete still used the old
/api/agent/agents/{id} defaults and 404'd. Aligned status/stop/delete defaults to
the same namespace as create: /agents/{id}, /agents/{id}/stop. AM contract doc
notes these are HM's best guess pending AM's confirmation of the real lifecycle
endpoints (their doc only specified create).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adapt HM's template-agent integration to AM's actual CODING_A2A API (per their
doc), keeping it isolated in agent_template_runtime.go:
- start payload -> AM's POST /agents { name, template:"coding_a2a_agent",
framework:"A2A", config:{user_id,...}, env } with the template .md folded into
env.AGENT_INSTRUCTION_TEXT, template_key -> AGENT_ROLE_NAME, model gateway via
OPENAI_BASE_URL + MODEL_NAME (OPENAI_API_KEY left to the client per A2A request).
- response parse -> access_info.domain/external_ip -> subdomain, namespace/name
-> runtime_id; AM issues no access_token (client uses A2A api_key).
- env names aligned to AM: GIT_DEFAULT_BRANCH, POSTGRES_* (was PG_*),
AZURE_BLOB_ACCOUNT_NAME/CONTAINER/ACCOUNT_KEY (was BLOB_*); source keys aligned
to the resource-binding form (db_name/username/database_password/access_key).
Only AM-supported types (git/mysql/postgres/azure-blob); vm/redis/mongo/bucket
now rejected as unsupported until AM adds them.
- frontend: resources page splits DB into MySQL/PostgreSQL (correct provider),
drops vm; deploy page hides unsupported resource types.
- docs: AM contract + client doc updated to the real env names, payload, and the
A2A direct-connect (message/send · message/stream) + api_key auth.
- tests updated for the new env names + AM payload/response shape. All green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Hand-off doc for the agent_management team: the 4 endpoints AM must implement
(start/status/stop/delete) with exact request/response (grounded in the isolated
adapter agent_template_runtime.go), the env naming convention AM templates must
read (git/vm/db/blob/bucket), AM's responsibilities (inject .env, validate the
agent access token, models via HM /v1/*, no secret leakage), the client<->agent
direct SSE contract AM needs to define, security requirements, the env-overridable
paths, and a joint integration checklist.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Review of the client doc against the real code found and fixed:
- §1 auth was not self-contained (deferred the canonical to the deprecated doc).
Inlined the full signing contract verified against middleware/device_signature.go:
the exact header set, the fixed-order canonical string (method/path/ts/nonce/
fingerprint/eph_pubkey/sha256(body)), ed25519(sha256(canonical)), the heicode-aead-v1
encrypted-body rules, and the X-Heicode-Auth-Error / X-Heicode-Server-Time failure
headers.
- §2 auth mismatch (accuracy bug): /api/user/self is UserAuth (session/JWT), NOT
device-signed — a device-only client cannot call it. Marked it optional and
clarified the two different auth schemes (/api/user/self* vs /api/heicode/*).
- §8: documented that failures return HTTP 200 with success:false (client MUST
read success), and that error.retryable is always false (decide retry by code).
- §10 inventory: corrected /api/user/self auth + added /self/models.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The 普通 sub task-orchestration model was replaced by the template-agent model
and its backend deleted. Removed the now-obsolete docs describing it:
- heicode-desktop-sub-agile-api.md, heicode-desktop-subagile-e2e-demo.md
- heicode-desktop-unified-api.md, heicode-sub-mode-flow-spec.md
- 普通sub敏捷模式-AgentManager对接任务清单.md
- AgentManager普通sub{产物回调缺失问题,剩余补充要求,联调整改要求}.md
Fixed dangling references in the new docs (client-api / template-agent-model).
Swarm (蜂群) docs kept — different mode, out of scope.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
New authoritative client doc (heicode-desktop-client-api.md): the desktop client
lists its agents from HM, gets each agent's subdomain + access_token, and
connects to the agent directly over SSE; models for both client and agent go
through HM /v1/*. Grounded in the production-verified responses (19 Chinese
templates, agent list/deploy/status shapes, error codes). Marks the old
unified-api doc (sub task-orchestration) as superseded.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Verified the old-model code surface against the repo. Found the new template-agent
model is an EVOLUTION of the existing deployment control plane, not greenfield —
so several files are mixed and must NOT be whole-deleted:
- agent_runtime_client.go: AM HTTP client (config/url/headers/create/stop/status/
health) is reused by the new StartAgent/StopAgent AND by capabilities; only
withDisplayStatus + artifact/budget helpers are old.
- agent_control_plane.go: AgentCreate/List/Get/StopUserDeployment + AgentDeployment
table are the backbone the new agent record reuses; only per-deployment task
sub-handlers and the withDisplayStatus calls (1191/1200/1222) are old.
- agent_task_bridge.go: resolveResourceBindingIntoGrant is reused for env assembly.
- AgentDeployment table: KEEP and extend (subdomain/access_token/binding_ids)
instead of new heicode_agent table + DropTable. Reconciled the model doc to match.
- Added agent_runtime_http_smoke_test.go to the sync-fix list.
Adds a §0.0 dependency/impact analysis answering: coverage, shared-feature impact,
and impact on the new APIs.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Concrete deletion plan for the old sub task model now that sub uses the
template-agent + direct-connect model. Maps real code surface (verified against
the repo) into delete / trim / evaluate buckets:
- routes (registerHeicodeTaskRoutes, deployment-targets, old user/deployments)
- controllers (heicode_task_create/client_routes/project_artifacts/artifact_edits/
cloud_deploy delete; agent_runtime_client/task_bridge/callback/control_plane trim)
- models + DB tables/columns (AgentArtifact/Revision/CloudDeployment drop;
AgentDeployment/SKSnapshot/CallbackEvent evaluate) with GORM/cross-DB drop notes
- frontend pages/routes/sidebar/i18n
- ordered teardown steps + verification + open questions to confirm before deleting
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
New simplified model: user deploys a template agent (resources injected into
its .env by HM from KV) via the HM web console; AM returns a unique subdomain +
access token; the desktop client connects DIRECTLY to the agent over SSE (HM out
of the data path). Both ends still call HM /v1/* for models.
Doc organizes the HM-side changes into: keep / add / modify / delete, plus the
agent record data model, the AM contract points, auth & secret handling, the
locked decisions, and rollout order. The old sub task-orchestration stack
(tasks/workflow/display_status/git_ref/artifact-download/lease/revision) is
marked for removal.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Close the remaining coverage gaps in the client-facing API doc (verified against
real routes in router/api-router.go):
- §2.1 NEW "sub 可用性就绪闸门": the 4-gate composite the client must pass before
enabling sub (capabilities.enabled + device-bound + active git binding + balance),
with pseudo-code and per-gate data source — directly answers "客户端判断 sub 是否可用".
- §2.2 NEW account/balance: GET /api/user/self (+/self/groups,/self/models),
quota/used_quota/request_count, model intersection rule.
- §2 capabilities: documented every field (runtime_kind/model_selection/supports_*).
- §4.2 NEW run-info interfaces with response shapes: logs(user/debug),
timeline(events incl delivery.pushed), events, metrics, diagnostics, sk-snapshots.
- §12 NEW full endpoint inventory by flow stage (①startup ②create ③monitor
④approve ⑤artifacts ⑥iterate ⑦deploy ⑧resources) with 🟢/🟡/🔴 status — a
coverage checklist mapping every real route so nothing is silently missing.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per the locked-in model: sub mode requires git binding; the final deliverable
exists ONLY in the user's own git repo (clone/pull). During a run HM streams
ONLY run-info (logs, status, work-view). There is no product download —
project_folder / manifest / files / archive(zip) / local-edits-revision are all
retired across both docs.
- spec: header note, sequence diagram, §2 contract table (code product = git_ref),
§3.0 step13, §3.1 (mandatory git), §3.5/§3.6 (git-only view), §3.7 (git is the
iterate baseline, no local-edits), §6.4 (deliverable check on git_ref, not files),
§7 / §8#8 / §10 TODO aligned. HM "artifact" demoted to a delivery/run-info record.
- unified-api: §3 parity note + legacy error codes marked retired (prior commit
already reworked §5/§6).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
sub mode requires git binding (else local-only), so the code deliverable
lives solely in the user's own git repo (clone/pull). Demote the legacy
"HM parses text artifact into project_folder (manifest/files/archive)" and
the local-edits revision flow to legacy/back-compat: §5 now = code via git +
artifacts only for non-code (test_report/summary); §6 redirects to git.
Backend endpoints remain for back-compat but new integrations must not use them.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The client API doc still carried the old flow; aligned it to
heicode-sub-mode-flow-spec.md (which it now references as the authority):
- Top banner: client is Claude-Code-like agentic; HM is the model gateway +
control plane (no AI/exec); AM is the cloud runtime; sub = offload to cloud.
- display_status reframed: HM judges presence/anti-empty-shell, NOT code
correctness; correctness = client (runs/tests) + user review (§0, §4).
- Deploy (§7) rewritten: client-executed + mandatory user confirmation; HM only
hands the credential from Key Vault; the old Manager-side Deploy-Worker model
is marked deprecated (also in §0.1 flow + §3 route table).
- New §8 Resource binding (git/vm/db/blob -> KV) with the /api/resources API and
the pending V2 client-facing read/credential endpoints.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
HM has no AI and must not compile/test/judge code correctness — that was an
overreach. Reframed §6: HM only relays AM execution status + the FACT of
whether an artifact exists (anti-empty-shell), never a quality/correctness
verdict. The desktop client (Claude-Code-like) pulls the code/git, runs and
tests it, and the user reviews — that is where "is it correct/valid/what I
wanted" is decided. AM test results are a test_report artifact for the client
to read, NOT a signal fed to HM for judging.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Answer "how does HM know AM output is real/valid": honestly, it does not — HM
has no AI and never reads/runs code. It only checks structural signals
(non-fallback, non-summary, delivery-type artifact with file changes), which
rules out fake/empty completions but does NOT guarantee correctness and can be
gamed by AM mislabeling. To upgrade "has something" to "really valid" needs:
(1) AM reports a verification block (build/tests/lint) that HM folds into the
verdict, (2) acceptance_criteria self-check, (3) final user review. Added the
verification block to the AM TODO as the key missing signal.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Re-examined the whole spec under the corrected model (client = Claude-Code-
like agentic program, not a shell):
- New §0.2: what sub mode IS and when to use it — local mode (client runs an
agent on the user machine) vs sub mode (offload a multi-agent job to cloud
AM). Client in sub mode = initiator + work viewer + local artifact/deploy.
- §2: added the model-call channel that was entirely missing — both client and
AM call HM /v1/* for models (a parallel channel to the task control plane).
- §3.7: iteration now has two paths — (A) send back to cloud AM, or (B) git
pull and fix locally with the client own agent (reuses local capability).
- Scope + client TODO updated to reflect the client agentic role.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Correct a fundamental mislabel: the desktop client is an agentic coding
program (like Claude Code) that runs agents and executes commands locally —
not a dumb shell. HM is the model-call gateway (new-api /v1/*) that BOTH the
desktop client and agent_management call to use models; HM does not run agents
itself. AI = the model, served by HM to both the local client and the cloud
AM runtime. sub mode = offloading a multi-agent job to the cloud AM (vs the
client running locally), with AM agents calling HM /v1/* for models.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address review feedback for three-team clarity:
- Terminology nailed: HM = Heicode Manager (Go gateway, NO AI, never executes,
never touches a VM); AM = agent_management (the "Agent Manager" runtime, the
one with AI that runs agents). Removed all ambiguous bare "Manager".
- Capability boundary table: who has AI / who executes commands / who connects
the VM. Spells out that HM cannot deploy or read VM logs — deploy is run by
the client (user-confirmed, short-lived creds from HM); code execution is AM.
- §3.0 explicit step-by-step execution flow (17 steps, each naming HM/AM/client).
- §6 full display_status definition: enum, judging algorithm, real-vs-fake
artifact rules, success criterion — so all three teams interpret it the same.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- git = user-bound own repo (github/gitea by URL); auth = fine-grained PAT
(universal, paste a token) with SSH deploy key fallback.
- deploy MUST be client-executed with mandatory user confirmation; Manager
only issues short-lived encrypted credentials + audits.
- git executed by agent_management with an injected short-lived PAT; Manager
records refs only; agents push to delivery/PR branch, not main.
- New section 9: additional details to settle before v1 (repo state, secret
hygiene, budget/cancel/crash handling, acceptance, concurrency, provider
limits, deploy confirm/rollback, work-view UX).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Authoritative flow/spec aligning desktop client <-> Heicode Manager <->
agent_management for the sub mode: encrypt/auth, dispatch, streamed agent
work view, git-per-agent + merge into one deliverable, review/redo, deploy
via Manager-held credentials, and the resource-binding spec (git/vm/db/blob
-> Key Vault). Marks each item 已实现/部分/待建/待决策 with recommendations,
and lists per-end TODOs. Open decisions in section 8 for sign-off.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Step-by-step walkthrough of a real client-simulated run (task dep_39e53ee4c692)
with actual request/response at each stage: create -> poll workflow -> artifacts
-> manifest -> files -> archive. Confirms agent_management delivers real code
files + nested folders (backend/main.py, backend/models.py) surfaced as a
project_folder. Includes a client self-check list.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Workflow now documents top-level mode (sub_agile|swarm) + sub_mode, phases[],
per-agent tokens/tools/elapsed_seconds/artifact_ids, and metrics/aggregates,
with a note that per-agent metrics + artifact source role await
agent_management runtime support.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Add 2026-06-02 changelog summarizing P0/P1 closure at the top.
- New error codes: ARTIFACT_ARCHIVE_NOT_READY/_FAILED, FILE_PATH_REQUIRED,
with retryable column and the unified error envelope note.
- §9 auth bullet now reflects encrypted-body writes + no-body signed GET.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address the desktop client team gap analysis on the unified /api/heicode/*
surface:
- P0-1 GET device auth: no-body V2 signed-GET path (fetch forbids GET body),
same Ed25519 canonical with empty-body hash; UserOrV2DeviceAuth +
OptionalV2DeviceAuth dispatch on signature headers. Unit test added.
- P0-2 approval inbox: GET .../tasks/{id}/approvals?status=pending.
- P0-3 project_folder: artifacts list normalizes the primary code deliverable
to display_artifact_type=project_folder + is_project + manifest/files/
archive/revisions subpaths.
- P0-4 archive contract: real application/zip + Content-Disposition +
Content-Length; ARTIFACT_ARCHIVE_NOT_READY (retryable) when no files yet.
- P1-1 file path: GET .../files?path=<url-encoded> (no segment ambiguity).
- P1-2/P1-3 revision: local edits stored as accepted baseline; /messages and
/execute consume the latest accepted revision (-> applied), return
active_project_revision.
- P1-4 doc: Swarm same-shape routes stated explicitly.
Doc updated to match. Build + middleware/controller tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
