agentic-mobile-control/openspec/changes/skill-management-console/specs/skill-subscription-sync/spec.md at 44e1a6651ad3dbf83fbbbbcf1bacd2464aaa6177

Files

T

q792602257andClaude Opus 4.6 dd03abbbb0 feat(skills): open skill-management-console change + local skill store

Opens the skill-management-console openspec change (cloud/local skill split
with local override) with proposal, design (D1-D11), four delta specs, and
tasks. Implements the agent-side persistent local skill store
(storage/local_skills.py): authored local skills + cloud-skill overrides in
a physically separate SQLite file, with fork-on-revocation. 10 tests pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-07-15 07:28:42 +08:00

4.2 KiB

Raw Blame History

REMOVED Requirements

Requirement: Pull-based sync from the Subscription Platform

Replaced by per-host incremental pull from this project's Cloud API (the external Subscription Platform is no longer the source).

Requirement: Subscription-based visibility enforcement

Replaced by per-host entitlement visibility enforcement.

ADDED Requirements

Requirement: Pull-based incremental sync from the Cloud API

The agent SHALL periodically pull an incremental delta of its own host's entitled cloud skills from this project's Cloud API (not an external Subscription Platform), using the host-scoped bearer credential already used for heartbeat and planner-decision. The Cloud API maintains a monotonic per-host entitlement version; the agent supplies the last version it successfully applied and the Cloud returns only upserted skills, removed_ids, and the new latest_version, or a full replace when the agent has no prior version or its version is too old to serve incrementally. The transport-replaceable client interface is preserved — only the concrete upstream and endpoint change.

Scenario: Agent syncs incrementally after entitlement or content change

WHEN the agent pulls with a recent since_version and its host's entitled set or an entitled skill's content has changed
THEN only the upserted skills and removed_ids since that version are applied to the local synced store, and the agent records the new latest_version

Scenario: Agent performs a full replace on first sync or stale version

WHEN the agent has no prior version, or its since_version is too old for the Cloud to serve incrementally
THEN the agent applies a full replace of its host's entitled set and records the returned latest_version

Requirement: Per-host entitlement visibility enforcement

The agent's synced catalog SHALL contain only cloud skills entitled to that agent's own host, and the read surface SHALL re-check visibility at query time so that an entitlement revoked before the next sync completes takes effect as soon as the revocation is reflected in the local synced state. Skills entitled to other hosts only SHALL never be visible.

Scenario: Revoked skill disappears after the next incremental sync

WHEN the Cloud reports a previously-entitled skill in removed_ids for this host
THEN the next sync removes it from the local synced store and it is no longer visible on the read surface

Scenario: Only this host's entitled skills are visible

WHEN the read surface lists cloud skills
THEN only skills entitled to this host are returned, never skills entitled solely to other hosts

Requirement: The sync runner runs inside the agent process

The agent SHALL construct and run the skill sync runner within the host-agent process so that the synced catalog stays current without manual intervention, on a configurable poll interval. A failed sync attempt SHALL leave the last-known-good synced catalog intact and queryable, and SHALL be observable rather than silently discarded.

Scenario: Sync runs automatically in the running agent

WHEN the host agent is running with cloud-transport configured
THEN the sync runner periodically pulls the host's entitled skills and keeps the local synced catalog current without any manual step

Scenario: Sync failure preserves the catalog

WHEN a sync attempt fails
THEN the existing synced catalog remains intact and queryable, and the failure is recorded for observability

Requirement: Agent reports its local-skill inventory to the Cloud

The agent SHALL periodically report a read-only inventory of its local skills (authored skills and active overrides, metadata only) to the Cloud API over the host-scoped channel, so the Console can display per-host local skills. Reporting is best-effort: a failure to report SHALL NOT affect local authoring, overrides, sync, or the agent's cloud entitlements.

Scenario: Agent reports local inventory periodically

WHEN the agent has local skills or active overrides
THEN it reports their metadata to the Cloud on a periodic best-effort basis

Scenario: Report failure is non-fatal

WHEN the inventory report cannot be delivered
THEN no local skill operation, override, or sync behaviour is impaired

4.2 KiB Raw Blame History