lockbot 2.10.0__tar.gz → 2.11.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. {lockbot-2.10.0/python/lockbot.egg-info → lockbot-2.11.0}/PKG-INFO +1 -1
  2. {lockbot-2.10.0 → lockbot-2.11.0}/pyproject.toml +1 -1
  3. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/agent_skill/SKILL.md +105 -9
  4. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/router.py +3 -0
  5. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/main.py +19 -1
  6. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/managed_paths.py +1 -0
  7. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/op_skill/SKILL.md +9 -1
  8. lockbot-2.11.0/python/lockbot/backend/app/resource_api/discovery.py +135 -0
  9. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/ingress.py +1 -1
  10. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/op_skill.py +17 -4
  11. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/skill.py +50 -10
  12. lockbot-2.11.0/python/lockbot/backend/app/resource_api/versioning.py +36 -0
  13. lockbot-2.11.0/python/lockbot/backend/app/resource_api/view_links.py +128 -0
  14. lockbot-2.11.0/python/lockbot/backend/app/resource_api/views.py +135 -0
  15. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/dependencies.py +7 -4
  16. lockbot-2.11.0/python/lockbot/backend/app/resource_auth/http_errors.py +20 -0
  17. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/service.py +19 -0
  18. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/state_migration.py +67 -1
  19. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/base_bot.py +12 -0
  20. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/device_bot.py +2 -4
  21. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/i18n/en.py +3 -2
  22. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/i18n/zh.py +2 -2
  23. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/node_bot.py +1 -1
  24. {lockbot-2.10.0 → lockbot-2.11.0/python/lockbot.egg-info}/PKG-INFO +1 -1
  25. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot.egg-info/SOURCES.txt +5 -0
  26. {lockbot-2.10.0 → lockbot-2.11.0}/LICENSE +0 -0
  27. {lockbot-2.10.0 → lockbot-2.11.0}/MANIFEST.in +0 -0
  28. {lockbot-2.10.0 → lockbot-2.11.0}/README.md +0 -0
  29. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/__init__.py +0 -0
  30. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/__init__.py +0 -0
  31. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/__init__.py +0 -0
  32. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/admin/__init__.py +0 -0
  33. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/admin/router.py +0 -0
  34. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/audit/__init__.py +0 -0
  35. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/audit/models.py +0 -0
  36. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/audit/router.py +0 -0
  37. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/audit/service.py +0 -0
  38. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/auth/__init__.py +0 -0
  39. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/auth/dependencies.py +0 -0
  40. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/auth/models.py +0 -0
  41. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/auth/router.py +0 -0
  42. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/auth/schemas.py +0 -0
  43. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/backup/__init__.py +0 -0
  44. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/backup/router.py +0 -0
  45. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/backup/scheduler.py +0 -0
  46. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/backup/service.py +0 -0
  47. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bot_audit/__init__.py +0 -0
  48. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bot_audit/models.py +0 -0
  49. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bot_audit/router.py +0 -0
  50. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bot_audit/service.py +0 -0
  51. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/__init__.py +0 -0
  52. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/encryption.py +0 -0
  53. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/manager.py +0 -0
  54. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/models.py +0 -0
  55. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/schemas.py +0 -0
  56. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/bots/webhook_handler.py +0 -0
  57. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/broadcast/__init__.py +0 -0
  58. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/broadcast/models.py +0 -0
  59. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/broadcast/router.py +0 -0
  60. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/broadcast/service.py +0 -0
  61. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/config.py +0 -0
  62. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/database.py +0 -0
  63. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/deployment.py +0 -0
  64. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/logs/__init__.py +0 -0
  65. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/rate_limit.py +0 -0
  66. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/__init__.py +0 -0
  67. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/activity.py +0 -0
  68. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/commands.py +0 -0
  69. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/errors.py +0 -0
  70. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/notifications.py +0 -0
  71. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/observability.py +0 -0
  72. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/operator.py +0 -0
  73. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/resources.py +0 -0
  74. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/snapshot.py +0 -0
  75. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/sources.py +0 -0
  76. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/traffic.py +0 -0
  77. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/usage.py +0 -0
  78. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_api/usage_cleanup.py +0 -0
  79. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/__init__.py +0 -0
  80. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/authority.py +0 -0
  81. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/credentials.py +0 -0
  82. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/models.py +0 -0
  83. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/pending.py +0 -0
  84. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/resource_auth/router.py +0 -0
  85. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/settings/__init__.py +0 -0
  86. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/settings/models.py +0 -0
  87. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/settings/router.py +0 -0
  88. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/sqlite_paths.py +0 -0
  89. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/state_ownership.py +0 -0
  90. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/backend/app/static.py +0 -0
  91. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/__init__.py +0 -0
  92. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/bot_instance.py +0 -0
  93. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/command_context.py +0 -0
  94. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/config.py +0 -0
  95. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/device_usage_alert.py +0 -0
  96. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/device_usage_utils.py +0 -0
  97. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/entry.py +0 -0
  98. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/env.py +0 -0
  99. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/handler.py +0 -0
  100. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/i18n/__init__.py +0 -0
  101. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/io.py +0 -0
  102. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/message_adapter.py +0 -0
  103. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/msg_utils.py +0 -0
  104. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/platforms/__init__.py +0 -0
  105. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/platforms/infoflow.py +0 -0
  106. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/platforms/registry.py +0 -0
  107. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/queue_bot.py +0 -0
  108. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/request.py +0 -0
  109. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/scheduler.py +0 -0
  110. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot/core/utils.py +0 -0
  111. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot.egg-info/dependency_links.txt +0 -0
  112. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot.egg-info/requires.txt +0 -0
  113. {lockbot-2.10.0 → lockbot-2.11.0}/python/lockbot.egg-info/top_level.txt +0 -0
  114. {lockbot-2.10.0 → lockbot-2.11.0}/setup.cfg +0 -0
  115. {lockbot-2.10.0 → lockbot-2.11.0}/tools/create_super_admin.py +0 -0
  116. {lockbot-2.10.0 → lockbot-2.11.0}/tools/gen_keys.py +0 -0
  117. {lockbot-2.10.0 → lockbot-2.11.0}/tools/reset_super_admin_password.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: lockbot
3
- Version: 2.10.0
3
+ Version: 2.11.0
4
4
  Summary: Cluster resource management bot for IM platforms
5
5
  Author-email: Jianbang Yang <yangjianbang112@gmail.com>
6
6
  License: MIT
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "lockbot"
7
- version = "2.10.0"
7
+ version = "2.11.0"
8
8
  description = "Cluster resource management bot for IM platforms"
9
9
  readme = "README.md"
10
10
  license = {text = "MIT"}
@@ -1,16 +1,102 @@
1
1
  ---
2
- name: lockbot-agent-api
2
+ name: lockbot-resource-agent
3
3
  description: >
4
- Drive a LockBot GPU/node/queue lock bot as a verified IM user over HTTP. Use when an agent
4
+ Use Lockbot Resource API (lockbot.resource-api) with lbr_ credentials.
5
+ This is distinct from P800/other Lockbot JWT-token platforms. Use when an agent
5
6
  must lock, unlock, book or query shared compute resources through a bot it has been enrolled
6
7
  on. Enrollment requires human confirmation in chat; resource operations use HTTP.
7
8
  ---
8
9
 
9
- # LockBot Agent API
10
+ # Lockbot Resource API Agent API
10
11
 
11
12
  A LockBot bot guards shared resources (GPU cards, cluster nodes, or queue slots). As an agent
12
13
  you act as **one verified IM identity on exactly one bot**, using a personal credential.
13
14
 
15
+ ## When a user shares this skill URL
16
+
17
+ Read it for the current task; a persistent installation is not required to call the API.
18
+ For ongoing resource work, recommend a persistent installation so future tasks can discover
19
+ this skill. Install it with the client's supported skill installer when the user asks to
20
+ install it or authorizes persistent setup. Use the manifest's `installation` bundle and
21
+ folder name **lockbot-resource-agent**. If installation or hot reload is unavailable, read
22
+ the latest Markdown for this task and explain that future tasks must load it again.
23
+ Never claim an installation/update succeeded without checking the client's saved skill.
24
+ Store the approved origin and last verified manifest revision in private service configuration;
25
+ credentials belong in its private credential store, never in `SKILL.md` or a downloaded ZIP.
26
+
27
+ ## Identify the service before using a saved credential
28
+
29
+ This skill is for **Lockbot Resource API**, identified by
30
+ `service_id: lockbot.resource-api`, API version `1`, and personal `lbr_` keys.
31
+ A similarly named Lockbot skill, matching command URL, or remembered token is not proof
32
+ that it belongs here. P800/other implementations using `/api/infoflow-auth/challenges`
33
+ and JWT tokens have a different protocol and permission scope; never apply their
34
+ "one token for all bots" or `take` instructions to this service.
35
+
36
+ 1. Start with the server/skill URL explicitly supplied or approved by the user. Without
37
+ a trusted server address, ask for that address once; never guess a host or bot ID.
38
+ 2. **Without Authorization**, GET `/api/agent-skill` on that origin. Check `service_id`,
39
+ `instance_id`, `api_version`, and `skill_id`. Do not follow a redirect to another origin.
40
+ 3. For persistent setup, install/update `installation.download_url` as **lockbot-resource-agent**,
41
+ beside other Lockbot skills. Keep their files and credentials intact. Verify the ZIP SHA-256
42
+ and `skill_sha256` from this same trusted origin. Legacy download URLs stay supported.
43
+ 4. Find saved credentials for the **trusted origin + instance_id**; use a known bot UUID
44
+ to narrow matching records. A newly confirmed key needs no bot ID or UUID to call context;
45
+ save its returned bot UUID alongside the key afterwards. Never use a single global
46
+ `LOCKBOT_TOKEN`, generic "lockbot token" memory, or another platform's
47
+ JWT. If an existing record has no service attribution, ask which service it belongs to;
48
+ do not test it against different servers.
49
+ 5. With a matching saved `lbr_` key, GET `/api/agent/context`. It supplies the bot ID, UUID,
50
+ name/type, verified actor and relative operation URLs. Verify the returned instance ID
51
+ against the saved record; use `links` on the same approved origin. Humans do not need
52
+ to know or enter `bot_id`. This context works while the bot is stopped; when access is
53
+ disabled it returns `agent_access_enabled: false`, so pause rather than bind again.
54
+
55
+ Do not send any key to a service just to identify the service. A public service identifier
56
+ prevents accidental protocol confusion; it does not authenticate a malicious host. The
57
+ user-approved origin (and HTTPS where available) remains the credential destination boundary.
58
+ The server cannot erase an Agent's earlier memories: keep the scope explicit in its private
59
+ configuration and use this namespaced skill for requests to this implementation.
60
+
61
+ ## Share a resource/queue page with the user
62
+
63
+ When the user wants to view resources or queue order in a browser, use `view_url` and
64
+ `view_expires_at` returned by `/api/agent/context`. Share that read-only URL; never put your
65
+ personal key into a browser URL. No separate web command or link-creation endpoint is needed.
66
+ The server lazily creates one link per bot, reuses it for 24 hours from creation, and only
67
+ replaces it when a subsequent authorized request arrives after expiry. Page refreshes do not
68
+ renew it. Ordinary group queries also return the current link. If the link expires, request
69
+ context again. Keep the returned URL on the user-approved origin.
70
+
71
+ The link permits its holder to read this bot's resource/queue/task information and can be
72
+ forwarded; it does not prove current group membership or allow commands. Revoking a personal
73
+ key prevents obtaining new links but does not independently revoke an already shared group
74
+ link before its expiry. A bot identity change invalidates its links. Older servers may omit
75
+ these optional fields: retain the existing API workflow rather than guessing a page URL.
76
+
77
+ ## Version checks and compatible updates
78
+
79
+ The manifest separates `server_version`, stable `api_version`, and the opaque content-based
80
+ skill `version` (plus full `skill_sha256`). Compare skill revisions for **equality**, not as
81
+ ordered semantic versions. Check the manifest at task start and after reconnecting. Personal
82
+ API responses also include `X-Lockbot-Service-ID`, `X-Lockbot-API-Version`,
83
+ `X-Lockbot-Server-Version`, and `X-Lockbot-Skill-Version`.
84
+
85
+ If the skill revision changes, re-fetch the manifest and this skill from the same trusted
86
+ origin before the next resource mutation. Use a cache-busting `?version=<revision>` or a
87
+ no-cache request, verify its SHA-256, and reload it without replacing another platform's
88
+ skill. An unknown API major version means stop mutations and request compatible instructions;
89
+ a server version change within API 1 does not itself require a new key or new binding.
90
+ Never renew/revoke credentials merely to update a skill.
91
+ The API advertises updates; the Agent client performs the download and reload. A server
92
+ cannot automatically install a skill in a client that does not support it. Keep checking the
93
+ manifest at task start even if that client loaded an older installed copy.
94
+
95
+ Older 2.10.0 servers lack context discovery and the new identity fields. Their existing
96
+ bot-scoped APIs and keys still work with a previously approved bot configuration. If that
97
+ configuration is missing, explain that the server needs the discovery update, or ask for
98
+ its bot ID once as a legacy fallback. Never scan IDs or fall back to another platform's API.
99
+
14
100
  ## Authentication
15
101
 
16
102
  - Credential form: `Bearer lbr_...`. It is scoped to a single `bot_id` and acts as the IM user
@@ -147,14 +233,17 @@ node do **not** have independent task registrations. Do not claim that distincti
147
233
 
148
234
  ### Actual HTTP call
149
235
 
150
- Use the trusted server address and bot ID supplied by the user. Load the key privately
236
+ Use the trusted server address supplied by the user; discover bot ID with `/api/agent/context`. Load the key privately
151
237
  from the user's credential store; never put it in URLs, logs, shared files or shell history.
152
- For example, after assigning `base_url`, `bot_id` and `key` securely in the Agent process:
238
+ For example, after identifying the service without a credential and loading the matching `base_url` and `key` privately:
153
239
 
154
240
  ```python
155
241
  import requests
156
242
  session = requests.Session()
157
243
  session.headers["Authorization"] = "Bearer " + key
244
+ context = session.get(f"{base_url}/api/agent/context", timeout=15, allow_redirects=False)
245
+ context.raise_for_status()
246
+ bot_id = context.json()["bot"]["id"]
158
247
  response = session.post(
159
248
  f"{base_url}/api/bots/{bot_id}/commands",
160
249
  json={"command": "lock node1 2h", "agent_label": "dev-agent", "purpose": "Develop feature X"},
@@ -167,7 +256,12 @@ state.raise_for_status()
167
256
  # Match state.json()["actor"] against the resource's holders, then use the resource.
168
257
  ```
169
258
 
170
- ## Error codes (JSON `detail.code`)
259
+ ## Error codes
260
+
261
+ Read `detail.code` when `detail` is an object; otherwise read the top-level `code`.
262
+ Published 401 `detail` strings and HTTP statuses are preserved for older clients; new
263
+ auth responses add `code` and `context_url` without changing those fields. On 2.10.0,
264
+ a string-only 401 has no machine code: do not interpret it as permission to scan bot IDs.
171
265
 
172
266
  | code | meaning | action |
173
267
  |---|---|---|
@@ -177,7 +271,9 @@ state.raise_for_status()
177
271
  | `bot_not_running` / `instance_retiring` | transient | retry later (honour `Retry-After`) |
178
272
  | `admission_full` | the bot's concurrency slot is full | back off, `Retry-After` |
179
273
  | `rate_limited` | you exceeded your per-credential budget | back off, `Retry-After` |
180
- | `credential_invalid` | your credential was revoked/rotated | re-enrol in chat |
274
+ | `credential_missing` | no Bearer key | load this origin/instance's own key |
275
+ | `credential_invalid` | unknown, revoked, expired or foreign key | check saved origin/instance; enrol only on the intended service if needed |
276
+ | `wrong_bot` | valid key, wrong existing bot URL (legacy HTTP 401) | GET `/api/agent/context` and use its operation links; do not bind again |
181
277
  | `may_have_executed` | admitted but outcome unknown | do NOT blindly retry; read `/resources` |
182
278
 
183
279
  ## Budgets & etiquette
@@ -189,7 +285,7 @@ state.raise_for_status()
189
285
 
190
286
  ## Typical flow
191
287
 
192
- 1. Reuse the user's securely stored key for this bot if already authorized. Otherwise `POST /api/resource-auth/bindings` with optional `{"label":"task runner"}` returns a credential, binding ID and one-use code. Store the credential privately; it is inactive until confirmation. Ask the human to send `@bot bind <code>` within 10 minutes, then check `GET /api/resource-auth/bindings/{binding_id}` for `confirmed`. Never simulate the human confirmation. If already bound, reuse the existing saved key; a duplicate request does not replace it. If the key is lost, ask the user to unbind and enroll again.
288
+ 1. Identify the approved origin/instance using the steps above, then reuse only its securely stored key if already authorized. Otherwise `POST /api/resource-auth/bindings` with optional `{"label":"task runner"}` returns a credential, binding ID and one-use code. Store the credential privately; it is inactive until confirmation. Ask the human to send `@bot bind <code>` within 10 minutes, then check `GET /api/resource-auth/bindings/{binding_id}` for `confirmed`. No bot ID is needed for this request: the verified group confirmation chooses it. After confirmation, GET `/api/agent/context` with the issued key to learn the bot and operation URLs. Never simulate the human confirmation. If already bound, reuse the existing saved key; a duplicate request does not replace it. If the key is lost, ask the user to unbind and enroll again.
193
289
  2. `GET /resources` → see what is free and your queue position.
194
290
  3. `POST /commands {"command":"lock node1 2h","agent_label":"dev-agent","purpose":"Develop feature X"}` → then `GET /resources` to confirm.
195
291
  4. While working, periodically read `/resources` and check that your verified actor still holds each resource you are using, with a valid lease. Also check before important resource operations and after an interruption. A human may manually release the resource or another authorized actor may preempt it; your original successful lock is not a continuing guarantee.
@@ -268,7 +364,7 @@ not repeatedly retried or reported as an unverified defect.
268
364
  `GET /api/agent-skill/SKILL.md` reads the instructions directly.
269
365
  `GET /api/agent-skill/lockbot-agent-api.zip` downloads the installable folder.
270
366
  These endpoints need no API key and contain no user-specific configuration or credentials.
271
- Resolve the relative URLs against the trusted Lockbot server address supplied by the user.
367
+ Resolve all relative URLs against the user-approved origin. New clients use the namespaced `installation` bundle; the old `name`, `version`, `download_url`, ZIP root and URLs remain for existing integrations.
272
368
 
273
369
 
274
370
  The machine-readable contract is served at `/api/public-openapi.json` (browsable at
@@ -323,6 +323,9 @@ def _build_config_dict(bot: Bot, db: Session | None = None) -> dict:
323
323
  g.strip() for g in (getattr(bot, "group_id", None) or "").split(",") if g.strip()
324
324
  ]
325
325
  config["_AGENT_SKILL_URL"] = lambda bot_id=bot.id, uuid=getattr(bot, "uuid", ""): _agent_skill_url(bot_id, uuid)
326
+ from lockbot.backend.app.resource_api.view_links import group_view_link
327
+
328
+ config["_BOT_VIEW_LINK"] = lambda bot_id=bot.id, uuid=getattr(bot, "uuid", ""): group_view_link(bot_id, uuid)
326
329
  config["_IDENTITY_REVISION"] = getattr(bot, "identity_revision", 0)
327
330
  config["DATA_DIR"] = str(paths.bots_root)
328
331
  config["STATE_FILENAME"] = str(paths.state_file(bot_id))
@@ -420,6 +420,10 @@ async def lifespan(app: FastAPI):
420
420
  _acquire_state_store_ownership()
421
421
 
422
422
  Base.metadata.create_all(bind=engine)
423
+ from lockbot.backend.app.resource_api.discovery import ensure_instance_id
424
+
425
+ with SessionLocal() as identity_db:
426
+ ensure_instance_id(identity_db)
423
427
  _migrate_bot_logs_category()
424
428
  _migrate_bot_consecutive_failures()
425
429
  _migrate_users_must_change_password()
@@ -438,9 +442,12 @@ async def lifespan(app: FastAPI):
438
442
  _migrate_identity_boundaries()
439
443
  _migrate_binding_uniqueness()
440
444
  from lockbot.backend.app.managed_paths import get_managed_paths
441
- from lockbot.backend.app.state_migration import assert_state_store_ready
445
+ from lockbot.backend.app.state_migration import assert_state_store_ready, migrate_legacy_state_files
442
446
 
443
447
  with SessionLocal() as db:
448
+ migrated = migrate_legacy_state_files(db, get_managed_paths())
449
+ if migrated:
450
+ logger.info("Migrated legacy state filenames for bots %s", migrated)
444
451
  assert_state_store_ready(db, get_managed_paths())
445
452
  _seed_dev_admin()
446
453
  _seed_dev_users()
@@ -599,6 +606,11 @@ def create_app() -> FastAPI:
599
606
 
600
607
  app.add_middleware(AgentIngressMiddleware)
601
608
  install_health_endpoint(app)
609
+ from lockbot.backend.app.resource_api.versioning import AgentVersionMiddleware
610
+ from lockbot.backend.app.resource_auth.http_errors import install_resource_auth_errors
611
+
612
+ app.add_middleware(AgentVersionMiddleware)
613
+ install_resource_auth_errors(app)
602
614
 
603
615
  # Rate limiting
604
616
  app.state.limiter = limiter
@@ -624,6 +636,9 @@ def create_app() -> FastAPI:
624
636
  app.include_router(broadcast_router)
625
637
  app.include_router(audit_router)
626
638
  app.include_router(backup_router)
639
+ from lockbot.backend.app.resource_api.discovery import router as discovery_router
640
+
641
+ app.include_router(discovery_router)
627
642
  app.include_router(resource_auth_router)
628
643
  app.include_router(resource_commands_router)
629
644
  app.include_router(resources_router)
@@ -632,6 +647,9 @@ def create_app() -> FastAPI:
632
647
  app.include_router(skill_router)
633
648
  app.include_router(op_skill_router)
634
649
  app.include_router(operator_router)
650
+ from lockbot.backend.app.resource_api.views import router as view_router
651
+
652
+ app.include_router(view_router)
635
653
 
636
654
  # ── Integration API docs: personal Agent, operator, enrollment and downloads ──
637
655
  @app.get("/api/public-openapi.json", include_in_schema=False)
@@ -22,6 +22,7 @@ MANAGED_OVERRIDE_KEYS = frozenset(
22
22
  "_MANAGED_BOT_DIR",
23
23
  "_IDENTITY_REVISION",
24
24
  "_AUTHORIZED_GROUP_IDS",
25
+ "_BOT_VIEW_LINK",
25
26
  }
26
27
  )
27
28
 
@@ -1,10 +1,18 @@
1
1
  ---
2
- name: lockbot-operator-api
2
+ name: lockbot-operator-agent
3
3
  description: Monitor Lockbot resource holders and perform explicitly authorized operator releases through OP API. For trusted operations bots, not ordinary user Agents or machine execution.
4
4
  ---
5
5
 
6
6
  # Lockbot operator API
7
7
 
8
+ This is the **lockbot-operator-agent** skill for
9
+ `service_id: lockbot.resource-api`, not another Lockbot implementation.
10
+ Without credentials, read `/api/op-skill` on the user-approved origin first. Verify the
11
+ service/API identity and use its namespaced `installation` bundle; check the skill content
12
+ revision at task start and on changes in `X-Lockbot-Skill-Version`. Keep each OP key scoped
13
+ to its origin, instance ID and bot; never reuse a generic remembered Lockbot JWT or token.
14
+ Do not overwrite another platform's skill or credential store. Legacy OP routes remain supported.
15
+
8
16
  Use the trusted base URL and bot ID supplied by the administrator. Obtain an **OP API Key**
9
17
  (`lbk_…`) from that bot's administrator and keep it in a private credential store. Send it
10
18
  only as `Authorization: Bearer <key>` to that trusted server. Never include keys in commands,
@@ -0,0 +1,135 @@
1
+ """Identify this implementation/deployment and resolve a personal key's bot scope."""
2
+
3
+ from typing import Any, Literal
4
+ from uuid import uuid4
5
+
6
+ from fastapi import APIRouter, Depends, Request, Response
7
+ from pydantic import BaseModel
8
+ from sqlalchemy.exc import IntegrityError
9
+ from sqlalchemy.orm import Session
10
+
11
+ from lockbot.backend.app.bots.models import Bot
12
+ from lockbot.backend.app.database import get_db
13
+ from lockbot.backend.app.rate_limit import limiter
14
+ from lockbot.backend.app.resource_api import errors
15
+ from lockbot.backend.app.resource_api.traffic import credential_budget
16
+ from lockbot.backend.app.resource_auth import service
17
+ from lockbot.backend.app.resource_auth.dependencies import _bearer_token
18
+ from lockbot.backend.app.resource_auth.http_errors import ResourceAuthenticationError
19
+ from lockbot.backend.app.settings.models import SiteSetting
20
+
21
+ SERVICE_ID = "lockbot.resource-api"
22
+ API_VERSION = "1"
23
+ _INSTANCE_KEY = "resource_api_instance_id"
24
+ router = APIRouter(prefix="/api/agent", tags=["Public API"])
25
+
26
+
27
+ def ensure_instance_id(db: Session) -> str:
28
+ """One persisted, non-secret identifier; old clients/databases need no new table."""
29
+ row = db.get(SiteSetting, _INSTANCE_KEY)
30
+ if row is None:
31
+ row = SiteSetting(key=_INSTANCE_KEY, value=str(uuid4()))
32
+ db.add(row)
33
+ try:
34
+ db.commit()
35
+ except IntegrityError:
36
+ db.rollback()
37
+ row = db.get(SiteSetting, _INSTANCE_KEY)
38
+ if row is None or not row.value:
39
+ raise RuntimeError("Missing resource API instance identity")
40
+ return row.value
41
+
42
+
43
+ def server_metadata(request: Request, db: Session) -> dict:
44
+ return {
45
+ "service_id": SERVICE_ID,
46
+ "instance_id": ensure_instance_id(db),
47
+ "server_version": request.app.version,
48
+ "api_version": API_VERSION,
49
+ "credential_scheme": "lbr_bot_scoped",
50
+ "capabilities": ["credential_context", "namespaced_skill", "skill_version_headers", "resource_view_link"],
51
+ "context_url": "/api/agent/context",
52
+ "enrollment_url": "/api/resource-auth/bindings",
53
+ "openapi_url": "/api/public-openapi.json",
54
+ }
55
+
56
+
57
+ class ServerIdentity(BaseModel):
58
+ service_id: Literal["lockbot.resource-api"]
59
+ instance_id: str
60
+ server_version: str
61
+ api_version: Literal["1"]
62
+ credential_scheme: Literal["lbr_bot_scoped"]
63
+ capabilities: list[str]
64
+ context_url: str
65
+ enrollment_url: str
66
+ openapi_url: str
67
+
68
+
69
+ class BoundBot(BaseModel):
70
+ id: int
71
+ uuid: str
72
+ name: str
73
+ type: str
74
+
75
+
76
+ class AgentContextResponse(BaseModel):
77
+ server: ServerIdentity
78
+ actor: dict[str, str]
79
+ bot: BoundBot
80
+ agent_access_enabled: bool
81
+ credential_scope: Literal["one_user_one_bot"]
82
+ links: dict[str, str]
83
+ skill: dict[str, Any]
84
+ view_url: str | None = None
85
+ view_expires_at: str | None = None
86
+
87
+
88
+ @router.get("/context", response_model=AgentContextResponse)
89
+ @limiter.limit("60/minute")
90
+ def agent_context(request: Request, response: Response, db: Session = Depends(get_db)):
91
+ """Discover only the identity/bot bound to this key. Never scan or list other bots.
92
+
93
+ A valid suspended key can inspect its own context but cannot access resources. No
94
+ running bot instance is needed. Revocation/expiry/identity changes still reject it.
95
+ """
96
+ row = service.authenticate_for_any_bot(db, token=_bearer_token(request))
97
+ if row is None:
98
+ raise ResourceAuthenticationError("Invalid credential", "credential_invalid")
99
+ allowed, retry = credential_budget.check(row.id, "read")
100
+ if not allowed:
101
+ raise errors.rate_limited(retry)
102
+ from lockbot.backend.app.resource_auth.authority import authority_guard
103
+
104
+ bot_id, platform, user_id = row.bound_bot_id, row.platform, row.external_user_id
105
+ with authority_guard(bot_id, platform=platform, external_user_id=user_id):
106
+ db.rollback()
107
+ row = service.authenticate_for_any_bot(db, token=_bearer_token(request))
108
+ if row is None or row.bound_bot_id != bot_id:
109
+ raise ResourceAuthenticationError("Invalid credential", "credential_invalid")
110
+ return _context_payload(request, response, db, row)
111
+
112
+
113
+ def _context_payload(request, response, db, row):
114
+ bot = db.get(Bot, row.bound_bot_id)
115
+ from lockbot.backend.app.resource_api.skill import skill_artifacts
116
+ from lockbot.backend.app.resource_api.view_links import view_link
117
+
118
+ response.headers["Cache-Control"] = "no-store"
119
+ response.headers["Vary"] = "Authorization"
120
+ view = view_link(db, bot, str(request.base_url)) if bot.resource_auth_enabled else {}
121
+ return {
122
+ "server": server_metadata(request, db),
123
+ "actor": {"platform": row.platform, "external_user_id": row.external_user_id},
124
+ "bot": {"id": bot.id, "uuid": bot.uuid, "name": bot.name, "type": bot.bot_type},
125
+ "agent_access_enabled": bot.resource_auth_enabled,
126
+ "credential_scope": "one_user_one_bot",
127
+ "links": {
128
+ "resources": f"/api/bots/{bot.id}/resources",
129
+ "commands": f"/api/bots/{bot.id}/commands",
130
+ "usage_declarations": f"/api/bots/{bot.id}/usage-declarations",
131
+ "skill_manifest": "/api/agent-skill",
132
+ },
133
+ "skill": skill_artifacts()[2],
134
+ **view,
135
+ }
@@ -13,7 +13,7 @@ from collections import OrderedDict
13
13
  from starlette.responses import JSONResponse
14
14
 
15
15
  _PATH = re.compile(
16
- r"^/api/(?:resource-auth/bindings(?:/[^/]+)?|bots/[^/]+/(?:commands|resources|usage-declarations(?:/[^/]+)?))/?$"
16
+ r"^/api/(?:agent/context|bot-views/[^/]+/state|resource-auth/bindings(?:/[^/]+)?|bots/[^/]+/(?:commands|resources|usage-declarations(?:/[^/]+)?))/?$"
17
17
  )
18
18
 
19
19
 
@@ -1,17 +1,24 @@
1
1
  """Public instructions for the existing privileged operator API."""
2
2
 
3
- from fastapi import APIRouter, Request, Response
3
+ from fastapi import APIRouter, Depends, Request, Response
4
+ from sqlalchemy.orm import Session
4
5
 
6
+ from lockbot.backend.app.database import get_db
5
7
  from lockbot.backend.app.rate_limit import limiter
6
- from lockbot.backend.app.resource_api.skill import _download, skill_artifacts
8
+ from lockbot.backend.app.resource_api.skill import (
9
+ _download,
10
+ installation_bundle,
11
+ public_skill_manifest,
12
+ skill_artifacts,
13
+ )
7
14
 
8
15
  router = APIRouter(prefix="/api/op-skill", tags=["Public API"])
9
16
 
10
17
 
11
18
  @router.get("")
12
19
  @limiter.limit("60/minute")
13
- def operator_skill_manifest(request: Request):
14
- return skill_artifacts("operator")[2]
20
+ def operator_skill_manifest(request: Request, response: Response, db: Session = Depends(get_db)):
21
+ return public_skill_manifest("operator", request, response, db)
15
22
 
16
23
 
17
24
  @router.get("/SKILL.md", response_class=Response)
@@ -25,3 +32,9 @@ def operator_skill_markdown(request: Request):
25
32
  def operator_skill_zip(request: Request):
26
33
  _, bundle, manifest = skill_artifacts("operator")
27
34
  return _download(request, bundle, "application/zip", f"lockbot-operator-api-{manifest['version']}.zip")
35
+
36
+
37
+ @router.get("/lockbot-operator-agent.zip", response_class=Response)
38
+ @limiter.limit("60/minute")
39
+ def namespaced_operator_zip(request: Request):
40
+ return _download(request, installation_bundle("operator"), "application/zip", "lockbot-operator-agent.zip")
@@ -6,8 +6,10 @@ import zipfile
6
6
  from functools import lru_cache
7
7
  from importlib.resources import files
8
8
 
9
- from fastapi import APIRouter, Request, Response
9
+ from fastapi import APIRouter, Depends, Request, Response
10
+ from sqlalchemy.orm import Session
10
11
 
12
+ from lockbot.backend.app.database import get_db
11
13
  from lockbot.backend.app.rate_limit import limiter
12
14
 
13
15
  router = APIRouter(prefix="/api/agent-skill", tags=["Public API"])
@@ -21,18 +23,20 @@ def skill_artifacts(kind="agent"):
21
23
  }[kind]
22
24
  markdown = files("lockbot.backend.app").joinpath(f"{folder}/SKILL.md").read_bytes()
23
25
  version = hashlib.sha256(markdown).hexdigest()[:16]
24
- output = io.BytesIO()
25
- with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as archive:
26
- entry = zipfile.ZipInfo(f"{name}/SKILL.md", date_time=(1980, 1, 1, 0, 0, 0))
27
- entry.compress_type = zipfile.ZIP_DEFLATED
28
- entry.external_attr = 0o100644 << 16
29
- archive.writestr(entry, markdown)
30
- bundle = output.getvalue()
26
+ bundle = _zip_skill(markdown, name)
27
+ skill_id = {"agent": "lockbot-resource-agent", "operator": "lockbot-operator-agent"}[kind]
28
+ installation = _zip_skill(markdown, skill_id)
31
29
  return (
32
30
  markdown,
33
31
  bundle,
34
32
  {
35
33
  "name": name,
34
+ "skill_id": skill_id,
35
+ "installation": {
36
+ "name": skill_id,
37
+ "download_url": f"{prefix}/{skill_id}.zip",
38
+ "sha256": hashlib.sha256(installation).hexdigest(),
39
+ },
36
40
  "version": version,
37
41
  "skill_url": f"{prefix}/SKILL.md",
38
42
  "download_url": f"{prefix}/{name}.zip",
@@ -44,11 +48,40 @@ def skill_artifacts(kind="agent"):
44
48
  )
45
49
 
46
50
 
51
+ def _zip_skill(markdown, name):
52
+ output = io.BytesIO()
53
+ with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as archive:
54
+ entry = zipfile.ZipInfo(f"{name}/SKILL.md", date_time=(1980, 1, 1, 0, 0, 0))
55
+ entry.compress_type = zipfile.ZIP_DEFLATED
56
+ entry.external_attr = 0o100644 << 16
57
+ archive.writestr(entry, markdown)
58
+ return output.getvalue()
59
+
60
+
61
+ def public_skill_manifest(kind, request, response, db):
62
+ from lockbot.backend.app.resource_api.discovery import server_metadata
63
+
64
+ response.headers["Cache-Control"] = "no-store"
65
+ identity = server_metadata(request, db)
66
+ if kind == "operator":
67
+ identity["credential_scheme"] = "lbk_bot_scoped"
68
+ identity["capabilities"].remove("credential_context")
69
+ identity["capabilities"].remove("resource_view_link")
70
+ identity.pop("context_url")
71
+ identity.pop("enrollment_url")
72
+ return {**skill_artifacts(kind)[2], **identity}
73
+
74
+
75
+ def installation_bundle(kind):
76
+ markdown, _, meta = skill_artifacts(kind)
77
+ return _zip_skill(markdown, meta["skill_id"])
78
+
79
+
47
80
  @router.get("")
48
81
  @limiter.limit("60/minute")
49
- def skill_manifest(request: Request):
82
+ def skill_manifest(request: Request, response: Response, db: Session = Depends(get_db)):
50
83
  """Discover the skill version, relative URLs and ZIP SHA-256; no API key required."""
51
- return skill_artifacts()[2]
84
+ return public_skill_manifest("agent", request, response, db)
52
85
 
53
86
 
54
87
  def _download(request, content, media_type, filename=None):
@@ -74,3 +107,10 @@ def skill_zip(request: Request):
74
107
  """Download a versioned, deterministic skill bundle without credentials or runtime data."""
75
108
  _, bundle, manifest = skill_artifacts()
76
109
  return _download(request, bundle, "application/zip", f"lockbot-agent-api-{manifest['version']}.zip")
110
+
111
+
112
+ @router.get("/lockbot-resource-agent.zip", response_class=Response)
113
+ @limiter.limit("60/minute")
114
+ def namespaced_skill_zip(request: Request):
115
+ """Install alongside other Lockbot implementations without replacing their skill."""
116
+ return _download(request, installation_bundle("agent"), "application/zip", "lockbot-resource-agent.zip")
@@ -0,0 +1,36 @@
1
+ """Additive response metadata: old API bodies and request requirements stay intact."""
2
+
3
+ from lockbot.backend.app.resource_api.discovery import API_VERSION, SERVICE_ID
4
+ from lockbot.backend.app.resource_api.ingress import _PATH
5
+ from lockbot.backend.app.resource_api.skill import skill_artifacts
6
+
7
+
8
+ class AgentVersionMiddleware:
9
+ def __init__(self, app):
10
+ self.app = app
11
+
12
+ async def __call__(self, scope, receive, send):
13
+ path = scope.get("path", "")
14
+ applies = scope["type"] == "http" and (
15
+ _PATH.fullmatch(path) or path.startswith(("/api/agent-skill", "/api/op-skill"))
16
+ )
17
+ if not applies:
18
+ return await self.app(scope, receive, send)
19
+
20
+ async def send_metadata(message):
21
+ if message["type"] == "http.response.start":
22
+ kind = "operator" if path.startswith("/api/op-skill") else "agent"
23
+ manifest = skill_artifacts(kind)[2]
24
+ headers = list(message.get("headers", []))
25
+ headers.extend(
26
+ [
27
+ (b"x-lockbot-service-id", SERVICE_ID.encode()),
28
+ (b"x-lockbot-api-version", API_VERSION.encode()),
29
+ (b"x-lockbot-server-version", scope["app"].version.encode()),
30
+ (b"x-lockbot-skill-version", manifest["version"].encode()),
31
+ ]
32
+ )
33
+ message = {**message, "headers": headers}
34
+ await send(message)
35
+
36
+ await self.app(scope, receive, send_metadata)