lifecycle
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
02 资源文件 3
- 脚本__init__.py11.9 KB
- 脚本client.py22.8 KB
- 脚本drain.py5.6 KB
03 SKILL.md 正文
deploy-lifecycle-api skill
The deploy-lifecycle API provides inspection and mutation of the central-deploy management plane:
service inventory, live status and health, environment snapshots, and (when permitted by the deploy
server's per-repo access toggle) service restart and env-write. Configuration management is owned by
each component internally — use the component's own /config endpoints for configuration access,
not the lifecycle API. All secret values in environment responses are masked as *** server-side by
_mask_secrets.
Allowed operations
| Tool | HTTP | Description |
|---|---|---|
list_lifecycle_services |
GET /services |
List all managed services and status. |
get_lifecycle_service_status |
GET /services/{name} |
Live status + health-check history. |
get_lifecycle_service_env |
GET /services/{name}/env |
Runtime environment (secrets masked). |
restart_lifecycle_service |
POST /services/{name}/restart |
Restart a service (requires per-repo access toggle). |
redeploy_lifecycle_service |
POST /services/{name}/redeploy |
Redeploy a service — pulls latest image (requires per-repo access toggle). |
verify_lifecycle_deployment |
GET /services/{name} (poll) |
Poll service until healthy and (optionally) image matches expected ref. |
self_restart |
POST /chat/services/{name}/restart |
Restart this service (named via lifecycle.service_name). |
update_lifecycle_service_env |
PUT /services/{name}/env |
Update service environment (requires per-repo access toggle). |
Configuration ownership
Configuration is owned by each component internally — use the component's own /config endpoints
(e.g. GET /config, PUT /config, POST /config/rollback) for configuration reads and writes, not
the lifecycle API. The lifecycle API no longer exposes config-store endpoints
(GET /services/{name}/config, PUT /services/{name}/config).
Restricted operations (per-repo access toggle)
The following mutation endpoints are available as tools but succeed only when the deploy server's per-repo access toggle is enabled for this component. When the toggle is not enabled the calls return a 403 error — the agent should treat that as "not permitted" and not retry:
POST /services/{name}/restart— restart a servicePOST /services/{name}/redeploy— redeploy a service (pulls the latest image)PUT /services/{name}/env— update service environment
Enabling the toggle: This is a per-repo setting in the central-deploy dashboard (labelled
allow_chat_access or chat_agent_mutatable), not a chat-component config key or environment
variable. See the
deployment guide for
step-by-step instructions.
Deploy registration — check the toggle up front
Registering a component in the deploy plane (POST /chat/services) and every other chat-agent
mutation below is gated by the same per-repo allow_chat_access / chat_agent_mutatable toggle.
When it is off, all of these calls return 403, so a deploy-registration flow that does not warn
early will run several steps and only stall at the first mutation. Warn the user about this
requirement up front, before starting the workflow:
- The moment the user asks to register or deploy a component (or perform any chat-agent mutation),
state the precondition: "Registering/deploying a component requires the
allow_chat_access/chat_agent_mutatabletoggle to be enabled for this repo in the central-deploy dashboard. If it is off, deployment operations will be blocked with 403." - If the user has not confirmed the toggle is already on, ask them to enable it in the central-deploy dashboard before you proceed, and wait for confirmation.
- Only once the toggle is confirmed enabled should you run the registration/deployment steps.
There is no API to read the toggle's current state — the read-only tools
(list_lifecycle_services, get_lifecycle_service_status, get_lifecycle_service_env) never
report it, and the agent learns it only via a 403 on a mutation call. Because you cannot verify it
yourself, treat the toggle as possibly-off and get explicit early confirmation rather than assuming
the operation will succeed. This avoids the stalled turns and back-and-forth caused by discovering
the 403 mid-flow.
Self-restart
self_restart restarts the agent's own service via POST /chat/services/{name}/restart, where
{name} is the configured lifecycle.service_name (the deploy server has no bare /self/restart
route). It is granted by the same allow_chat_access / chat_agent_mutatable flag as the other
chat-agent restart calls. Use this after a deploy that changed the agent's own capabilities (new
component, tool, skill, or permission) so the new capability is picked up. When
lifecycle.service_name is unset the tool returns a clear "not configured" message rather than
attempting a call.
This tool cannot restart other managed services — for those, use restart_lifecycle_service.
Drain gate. A restart kills every agent turn in flight. self_restart (and
restart_lifecycle_service on the agent's own service) therefore defers while other agent turns or
subsessions are mid-turn: the reply reads Restart deferred: N other agent turn(s) are still in flight… and the restart is issued automatically once they finish, or after a bounded drain timeout
(600 s). Do not call it again after a deferral. Never restart just to apply a periodic.sessions
edit — presets hot-reload on PUT /config.
URL protocol handling
If central_deploy.url lacks a URL scheme (e.g. central-deploy:8100), the client prepends the
configured lifecycle.default_protocol (default "http"). URLs with recognised schemes (http,
https) are left unchanged. An empty base_url produces a clear error message from self_restart
instead of a cryptic protocol error — configure central_deploy.url to the deploy-lifecycle API
address (e.g. http://central-deploy:8100) to enable the feature.
Retry behaviour
On transient failures (server 5xx errors, network timeouts, connection failures) self_restart
retries with exponential backoff before reporting failure. Non-retryable errors (4xx client errors
such as 403 Forbidden or 404 Not Found) are returned immediately without retrying.
Retry parameters are configurable via the lifecycle settings:
| Setting | Default | Description |
|---|---|---|
lifecycle.self_restart_max_retries |
3 |
Maximum retries for transient failures. The initial attempt + retries = max_retries + 1 total calls. |
When all retries are exhausted the method returns a combined error message describing the number of attempts made and the last error received.
The following endpoints remain forbidden — no tool exists for them and the agent must not attempt to reach them through any other path:
DELETE /services/{name}— remove a service registration
Post-merge deployment verification
After merging a PR that changes a tracked component (cost-fix, infrastructure change, or any code change that produces a new container image), do not close the ticket until the new image is confirmed running in production:
- Trigger redeploy — call
redeploy_lifecycle_servicefor the affected service. - Verify deployment — call
verify_lifecycle_deploymentwith the expected image reference (e.g. the tag or digest the PR was built from). This polls the service status until the running image matches and the service is healthy. - Re-measure metrics — after the deployment is confirmed, check the key metrics the ticket was meant to improve (cost, latency, error rate, etc.) to confirm the change had the intended effect.
- Only then close the ticket — when deployment is verified and metrics are confirmed.
The verify_lifecycle_deployment tool accepts an expected_image_ref that is matched by substring
against the running image identifier. You can pass a tag (:main), a digest prefix
(sha256:abc123), or a full reference. When expected_image_ref is empty, the tool verifies only
that the service is running and healthy.
Safety
The three read-only tools are pure reads — they make no state changes and can be called freely for
diagnostics and investigation. The two mutation tools (restart, env-write) make real state changes
and are gated by the deploy server's per-repo access toggle. The self_restart tool is a mutation
that restarts the agent's own service (named via lifecycle.service_name) — it should only be
called when the agent needs to pick up a new capability after a deploy. Secret masking is enforced
server-side; the agent never sees raw credentials.
Operating rules (moved from the system prompt, 2026-09-08)
Deploy tools and the deploy plane
– Deploy API (lifecycle tools): • restart_lifecycle_service — restart any service (needs per-repo toggle) • self_restart — restart the agent's own service (no toggle required) • update_lifecycle_service_env — update service environment – Deploy system: The robotsix-deploy (central-deploy) management plane is a runtime API server, not a git repository — component onboarding, lifecycle operations, and configuration changes are all API-driven (POST /onboard/preflight, /onboard/confirm, etc.). The deploy/docker-compose.yml in each component repo is the contract central-deploy reads at onboard time; no git PR to the central-deploy repo is ever needed. Do not suggest git PRs or repo changes for central-deploy onboarding or lifecycle operations. – Deploy pre-check: after a migration or fix ticket is done and the user requests a deploy, first verify the associated PR is merged — query its status via the mill's ticket endpoint (GET /tickets/{id}) or check the PR on GitHub directly, rather than asking the user for confirmation. If the PR is not yet merged, explain the blocker clearly and offer to wait for the merge or escalate. Only proceed with the deploy (restart) after confirming the merge is complete. – Deploy preflight: before calling any deploy endpoint (POST /chat/deploy, POST /onboard/*, or any lifecycle mutation), you MUST:
- Retrieve the target component repo's deploy/docker-compose.yml and count its services, volumes, healthchecks, and commands.
- Check the chat_agent_deployable_components allowlist (via component_request to central-deploy or the roster) — if the component is not listed, refuse to proceed and report the missing allowlist entry; never attempt to deploy a component that is not explicitly authorised for chat-agent deployment.
- Compare the contract against the endpoint's known capabilities: single-container endpoints cannot deploy multi-service compose files, named volumes, multiple networks, or healthcheck stanzas. If the endpoint cannot reproduce the full contract, refuse to proceed and explain which contract elements are unsupported. Do NOT offer to deploy through an endpoint whose capabilities you have not verified — guessing causes failed deploys and wastes operator time. If you cannot determine the endpoint's capabilities (e.g. the server is running an older version whose deploy support is unknown), state that limitation and ask the operator to verify before proceeding. – Contract-version troubleshooting: When a user encounters a "missing or incorrect central-deploy-contract-version header" error during onboarding, diagnose concretely before suggesting a ticket: (a) check whether the component's deploy/docker-compose.yml has "# central-deploy-contract-version: N" as its very first line — if the header is missing, the fix is to add it (the version number is in the repo's own deploy/docker-compose.yml); walk the user through adding it. (b) If the header is present but central-deploy rejects it, check the component's recent PRs for a version bump — a recent merge may have changed the expected version. (c) If the correct version remains unclear after checking the repo, file a ticket on the component repo to clarify the expected contract version.
After a merge
– After a successful merge, immediately check whether the change is live in production: use get_lifecycle_service_status on the affected component to confirm the new image is deployed and healthy. A merged PR whose image is not yet deployed is not truly done — report the deployment status alongside the merge result (never as a separate follow-up), clearly state the deployment gap if the change is not yet live, and offer to track deployment progress or help trigger a deploy. When a deployment gap exists (PR merged but service still running older image), your merge-report message MUST explicitly name the gap and suggest the concrete next step — e.g. 'The fix is merged. To make it live, deploy the update and restart the service.' Do NOT end a conversation or session after a merge without first informing the user of any deployment gap. Never claim a change is complete without confirming its deployment status.
Configuration advice and capability probes
– Service configuration standard (robotsix-standards): Every service in the fleet is configured by a
single config.json file with lowercase key names, not env-style UPPERCASE variables. Refer to
configuration values by their lowercase JSON key path (e.g. radicale.url, radicale.username,
radicale.password), never by uppercase env-var-style names (e.g. RADICALE_URL, RADICALE_USERNAME,
RADICALE_PASSWORD). The config file is one JSON document mounted into the container via a volume —
the operator (or the deploy pipeline) edits that JSON file and the merged result is written before
each start; a value is set or changed by editing config.json, not by exporting an environment
variable. Do not invent or recommend environment variables for service configuration. Use
environment variables only when a component explicitly requires one (e.g. ROBOTSIX_CONFIG_FILE
merely locates the config file). – When advising on configuration settings for a component (secrets,
labels, environment variables, deploy contracts, feature flags), first retrieve and analyse the
relevant source code through available tools to confirm the actual implementation. Do not rely on
assumptions or outdated recollection — central infrastructure may already handle the setting
fleet-wide (e.g. central-deploy’s docker_sdk.py may inject secrets and labels automatically), making
per-repo configuration advice redundant or incorrect. Verify the source of truth before giving
configuration guidance. – Server-side capability probes: when checking whether a new server-side
capability (e.g. a new HTTP endpoint like POST /chat/deploy) is available, probe the target server's
endpoint directly with a GET request rather than relying on static skill descriptions, roster
entries, or the audit log. A catch-all 303 redirect from an old build does NOT confirm the
capability is present — only a meaningful status code (405 Method Not Allowed, 422 Unprocessable
Entity, etc.) from the endpoint itself indicates the route exists. Before concluding a capability is
live, check the server's running image digest (via the health endpoint or deploy status) against the
expected digest from the merged PR that introduced the capability. Report the digest comparison to
the user so they can independently confirm. – Endpoint path verification: before probing any
server-side endpoint with http_probe or component_request, confirm the exact registered path from
the source code (e.g. the Route() registrations in the app factory or the routes module). Do not
guess or infer endpoint paths from naming conventions, module names, or partial memory — a guessed
path like /mobile/auth/login when the actual route is /auth/login will return a misleading 400 or
401 instead of a 404, confusing the operator about whether the endpoint exists. Read the route
definitions first, then probe the confirmed path.