HM-side logic for the template-agent model, written against a proposed AM
contract that is fully isolated in agent_template_runtime.go — when AM ships its
real API, only the default paths + response field names in that one file change.
- agent_template_runtime.go: AM adapter (list templates, start template agent
with env, stop/delete) reusing the existing runtime config/url/envelope helpers.
- agent_template_handlers.go: GET /api/heicode/agent-templates; POST /api/heicode/
agents (resolve bindings -> env, start via AM, persist subdomain+token);
GET /agents, GET/:id, POST/:id/stop, DELETE/:id. Owner-scoped; env never logged.
- reuses AgentDeployment as the agent record (TemplateID/Subdomain/AccessToken/
BindingIDsJSON) and buildAgentEnvFromBindings for env assembly.
- routes wired under /api/heicode (UserOrV2DeviceAuth), verified no registration
panic (router tests pass).
- agent_template_test.go: 7 independent unit tests (env assembly metadata-only,
ownership, secret-without-ref, unknown-source, empty; path substitution;
response mapping) — all pass without AM/KV.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
buildAgentEnvFromBindings resolves selected resource bindings into a flat env map
for a template agent's .env at start: non-secret values from Metadata, secret
values resolved from Key Vault (getJSONSecret) only here, lazily, never persisted.
AM-independent foundation for the deploy-agent flow.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Additive, AutoMigrate-friendly (new columns only, cross-DB safe). Foundation for
the template-agent + direct-connect model:
- AgentDeployment: TemplateID, Subdomain, AccessToken, BindingIDsJSON — reuse the
existing deployment record as the deployed-agent record instead of a new table.
- ResourceBinding.EnvMap: declares which env vars a binding exposes to a template
agent at start (non-secret from Metadata; secret resolved from KV only at start).
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>
The wallet page already renders Current Balance / Total Usage / API Requests
from /api/user/self. Reuse that exact component (WalletStatsCard) on the
Overview instead of a hand-written block — DRY, identical numbers
($160.47 / $39.53 / 521 for the current user).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The reused LogStatCards aggregates ALL users for admin accounts, so an admin
(root) saw gateway-wide totals (e.g. $628 / 339M tokens / 5218 req) instead of
their own. And per-user windowed quota-dates were empty (0). Replaced with the
user's own lifetime usage from /api/user/self (used_quota = spend, quota =
remaining, request_count), formatted with formatQuota. Real, non-zero, per-user.
(LogStatCards also gained an optional userScope prop for future per-user use.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reuse the existing LogStatCards (requests / quota=cost / tokens=consumption,
all props optional) on the Overview cockpit — no new data/logic, just renders
the current user usage stats under a "Usage & cost" section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Re-adds Resource binding to the Heicode cockpit (/resources). Add bindings for
GitHub / Gitea (type=git + provider), VM (ssh), database, blob; non-secret
fields go to metadata, the credential is written to Azure Key Vault via
POST /api/resources/:id/secret and only the secret_ref is shown (masked).
List + unbind. Backend already supported this; now functional since KV is up.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Resource binding backend (CRUD + secret-to-KV) is now fully functional after
provisioning the Key Vault. Added vm/database/blob to allowedResourceTypes for
the desktop binding set (gitea/github use type=git + provider). git binding +
KV secret write verified end-to-end (secret lands in heicode-kv).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per direction: 概述 should be a 看板, not a "turn an idea into shippable
software" marketing surface.
- Removed the idea-hero (home-hero.tsx: IdeaInput + mcp-fed ContinueTasks/
TodayFocus/HelperEntries, which were often empty/unreachable).
- Overview now renders the live metrics dashboard (CockpitView, previously
dead code): Running / Completed / Failed / Pending counts by display_status
+ recent runs, fed by the working listAgentDeployments.
- Dropped the marketing "Quick actions / Control plane online" tier.
- Subtitle: "From an idea to shippable software." -> "Live overview of your
Agent runs." Added zh translations.
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>
- /api/heicode/sub-agile/tasks now returns only sub_agile, /swarm only swarm
(both previously returned every deployment regardless of mode).
- DELETE /tasks/{id} now hard-deletes the record (best-effort runtime stop +
remove row + in-memory entry) so a deleted task disappears from the list,
instead of only marking it stopped.
- Admin runs page: renamed Task overview -> Agent runs, cards show the mode
(Sub Agile / Swarm) chip, added a mode filter; status already uses
display_status.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The Manager console carried screens built to an early control-plane vision
that no longer matches how the product runs (desktop client drives tasks;
Manager is gateway + status judge). Removed the dead/misleading ones and
aligned task overview to the real status model. Frontend only; no backend
endpoints touched.
Deleted (routes + pages + menu entries):
- Resource binding (/sk-sources): mcp-server /api/resources unwired (301) +
Azure Key Vault unreachable -> page was inert.
- Audit (/audit): only simulated approvals, empty leases, mcp audit unwired.
- Events / Templates / Agents pages: legacy control-plane (hardcoded mock
templates), not in the main menu but route-reachable.
- azure-cloud-binding-sheet + create-agent-deployment-sheet (New run).
Task overview (/deployments) kept and fixed:
- status now uses Manager-judged display_status (completed / needs_codegen /
completed_without_deliverable=fail / running ...) instead of raw phase, so
success vs failure is legible.
- dropped New run, scope/budget/secret_ref pills, permission-manifest grants
table, Simulate; kept the task list, per-task audit timeline and artifacts.
Cleaned all menu/nav/dashboard references to the deleted routes (sidebar,
top-nav, footer, cockpit, home-hero, agent-hub, task-card-view) and
regenerated routeTree.gen.ts. tsc -b and rsbuild build both pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per the HeiCode-Swarm 蜂群对接文档 §3.1, the swarm runtime standard routes are
/api/agent/swarm/* (legacy /api/swarms/* still works but is no longer default).
Swarm-only change; sub-agile (AGENT_RUNTIME_*) defaults and the agent_management
wiring are untouched.
- SWARM_RUNTIME default create/stop/approval -> /api/agent/swarm/deployments[...]
- swarm status: the runtime has no /status subpath, so status is read from the
deployment detail endpoint GET /api/agent/swarm/deployments/{deployment_id};
StatusPath/ArtifactContentPath defaults made mode-aware (sub keeps legacy).
- update the swarm HTTP smoke test to assert the standard runtime paths.
Verified reachable: HeiCode-Swarm at 52.139.240.116:8000 returns the standard
POST /api/agent/swarm/deployments (401 needs token, endpoint exists).
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>
Address the desktop client sub-mode gap report:
- B: /tasks list items now carry Manager-judged display_status (were raw
status, so completed could really be needs_codegen).
- D: list + detail expose top-level mode (sub_agile|swarm) derived from the
runtime mode, so a task recovered from /list after restart routes to the
right mode instead of defaulting to sub-agile.
- F: unify mode naming on sub_agile everywhere (capabilities/list/detail/
workflow); workflow keeps sub_mode for the agile/waterfall cadence.
- A: /workflow gains phases[], per-agent tokens/tools/elapsed_seconds/
artifact_ids, and top-level metrics + aggregates, filled from runtime
status diagnostics. Per-agent tokens/tools, artifact source role and phase
breakdown surface as 0/[] until agent_management reports them.
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>
LatestAcceptedRevisionForDeployment ordered by a non-existent column
(created_at), so the query errored and /messages and /execute never picked
up the latest accepted local-edit revision. Found via live VM smoke test.
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>
Document how the desktop client should classify and display sub-mode artifacts, including summary-only outputs and markdown code documents.
Constraint: Keep interface paths stable; update display and validation rules only
Confidence: high
Scope-risk: narrow
Not-tested: Documentation-only change; git diff --check passed
Record the 2026-05-31 production Manager smoke result for ordinary sub mode after the Agent Manager Runtime image update.
Constraint: Keep ordinary sub mode separate from swarm mode and document real production ids only
Confidence: high
Scope-risk: narrow
Not-tested: Documentation-only change; git diff --check passed
Add separate Runtime mode selection for ordinary sub and swarm flows, including Swarm-specific create payload shaping and Azure VM env wiring. Document the ordinary sub artifact callback gap, swarm runtime findings, PayPal billing boundaries, deployment migration requirements, and desktop/API progress.
Constraint: Keep ordinary sub and HeiCode-Swarm Runtime deployments separate
Confidence: high
Scope-risk: moderate
Tests: go test ./...
chenchenandClaude Opus 4.8