Changeset 0.29.2 (#197)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

docs/ICD/extensions.md

@@ -143,8 +143,8 @@ Admin must grant each before the package activates.
 | `filters.pre_completion` | — | Register pre-completion filter |
 | `api.http` | `http` | Outbound HTTP requests (v0.29.0: module, v0.29.1: also required for API routes) |
 | `provider.complete` | `provider` | LLM completion calls via BYOK chain (v0.29.1) |
-| `db.read` | `db` | Read extension tables (future) |
-| `db.write` | `db` | Write extension tables (future) |
+| `db.read` | `db` | Read extension tables and platform views (v0.29.2) |
+| `db.write` | `db` | Write extension tables (v0.29.2) |
 
 ### Starlark Modules (v0.29.0+)
 
@@ -171,6 +171,110 @@ Modules injected into the script namespace based on granted permissions:
 - Response: `{"content", "model", "finish_reason", "input_tokens", "output_tokens"}`
 - Provider resolved via BYOK chain; pinnable via `requires_provider.provider_config_id`
 
+**`db`** (requires `db.read` or `db.write`, v0.29.2):
+- `db.query(table, filters=None, order=None, limit=100)` → list of dicts
+  - `table`: logical name (physical: `ext_{pkg_slug}_{table}`)
+  - `filters`: dict of `{column: value}` equality filters (optional)
+  - `order`: `"col"` or `"-col"` for descending (optional)
+  - `limit`: max rows (default 100)
+- `db.insert(table, row_dict)` → inserted row dict with auto-generated `id` (`db.write`)
+- `db.update(table, id, partial_dict)` → True (`db.write`)
+- `db.delete(table, id)` → True (`db.write`)
+- `db.list_tables()` → list of logical table names for this package
+- `db.view(view_name, filters=None, limit=100)` → list of dicts
+  - Allowed view names: `"users"` → `ext_view_users`, `"channels"` → `ext_view_channels`
+  - `ext_view_users`: `id`, `display_name`, `email`
+  - `ext_view_channels`: `id`, `title`, `type`, `team_id`
+
+### Extension Database Tables (v0.29.2)
+
+Starlark packages declare owned tables in `manifest.db_tables`. Tables
+are created on install and dropped on uninstall.
+
+**Manifest `db_tables` field:**
+
+```json
+{
+  "db_tables": {
+    "logs": {
+      "columns": {
+        "message":    "text",
+        "user_id":    "text",
+        "count":      "int",
+        "score":      "real",
+        "active":     "bool",
+        "created_at": "timestamp"
+      },
+      "indexes": [
+        ["user_id"],
+        ["user_id", "created_at"]
+      ]
+    }
+  }
+}
+```
+
+- **Physical name**: `ext_{pkg_slug}_{logical_name}` (hyphens → underscores)
+- **Auto-columns**: `id TEXT PRIMARY KEY` (UUID generated on insert),
+  `created_at` (dialect-correct timestamp default)
+- **Column types**: `text`, `int`/`integer`, `real`/`float`,
+  `bool`/`boolean`, `timestamp` — mapped to dialect-correct SQL
+- **Indexes**: each entry is a list of columns for a composite index
+- **Dialect**: PG uses `TIMESTAMPTZ`/`BOOLEAN`; SQLite uses `TEXT`/`INTEGER`
+- **Catalog**: tracked in `ext_data_tables` per package for lifecycle management
+
+### Extension Tools (v0.29.2)
+
+Starlark packages declare server-side tools in `manifest.tools`. These
+are included in `BuildToolDefs` alongside server tools. The completion
+tool loop dispatches matched calls to the `on_tool_call` entry point.
+
+**Manifest `tools` field (starlark tier only):**
+
+```json
+{
+  "tier": "starlark",
+  "permissions": ["db.read"],
+  "tools": [
+    {
+      "name": "search_logs",
+      "description": "Search extension log entries",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query":   {"type": "string"},
+          "user_id": {"type": "string"}
+        },
+        "required": ["query"]
+      }
+    }
+  ]
+}
+```
+
+**`on_tool_call(call)` entry point:**
+
+Called by the completion tool loop when a tool declared in `tools` is
+invoked by the LLM.
+
+```python
+def on_tool_call(call):
+    # call dict:
+    # {
+    #   "tool_name":    "search_logs",
+    #   "tool_call_id": "call_abc123",
+    #   "arguments":    {"query": "hello", "user_id": "u1"}
+    # }
+    if call["tool_name"] == "search_logs":
+        rows = db.query("logs", filters={"user_id": call["arguments"]["user_id"]})
+        return {"results": rows}
+    return {"error": "unknown tool"}
+```
+
+- Return value is serialized to JSON and returned as the tool result
+- All sandbox modules (including `db`) are available per granted permissions
+- No additional permission is required beyond package being `active`
+
 ### Builtin Seeding
 
 On startup, `SeedBuiltinExtensions()` scans `extensions/builtin/`