|
| 1 | +--- |
| 2 | +name: corbits-hub-libs |
| 3 | +description: Mount Corbits hub libraries (cron, artifacts, memory, mailbox, webhooks, agent-token) and use the embedding and reranking clients. |
| 4 | +user-invocable: false |
| 5 | +--- |
| 6 | + |
| 7 | +# Corbits hub libraries |
| 8 | + |
| 9 | +Six libraries add features to an Interchange hub. They share one shape. |
| 10 | + |
| 11 | +## Shared pattern |
| 12 | + |
| 13 | +- Each exports `createXRoutes(deps)`, a Hono sub-app you mount with `app.route(...)` on `@intx/hub-api`, gated by `requireGrant` (from `createRequireGrant({ grantStore, conditionRegistry })`). |
| 14 | +- Each has `runXMigrations(dbConfig, { schema })`. On every boot run `@intx/db`'s `runMigrations` first, then these. They are idempotent and advisory-locked, so replicas are safe. |
| 15 | +- Each owns its own Postgres schema. `schema` is the host schema holding `tenant`, `principal`, and `credential`. |
| 16 | +- Mount paths: `/api/tenants/:tenantId/<name>`, with `artifacts` at `/api` and `webhooks` at `/api/hooks`. |
| 17 | +- Agents reach them through a tool pack (`.../sidecar-bundle`) and run-scoped routes that use an agent token. |
| 18 | + |
| 19 | +## Pick one |
| 20 | + |
| 21 | +| Package | Reach for it when | Notes | |
| 22 | +| ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | |
| 23 | +| `@corbits/cron` | An agent should run on a schedule. | Five-field UTC cron. No edit: delete and recreate. At most once per due minute. Pair with webhooks' deliverer. | |
| 24 | +| `@corbits/webhooks` | An outside system should trigger a run. | Verifies Slack, Standard Webhooks, bearer. No unsigned mode. Mount outside session middleware. | |
| 25 | +| `@corbits/artifacts` | Users or agents produce files or documents to keep. | Versioned. Bytes go through a pluggable `ContentStore` (`InlineContentStore` uses Postgres). No UI. | |
| 26 | +| `@corbits/memory` | Agents need shared searchable memory. | Needs Postgres with pgvector, and falls back to full text (`degraded`). Tools: `memory_add`, `memory_search`, `memory_list`, `memory_feed`. | |
| 27 | +| `@corbits/mailbox` | Humans need an inbox in the loop (approvals by mail). | For human principals. No UI and no transport: the host supplies `deliver`. | |
| 28 | +| `@corbits/agent-token` | A deployed agent calls back into the hub. | Mint and revoke routes plus `requireAgentToken` middleware. Tokens last until revoked. | |
| 29 | + |
| 30 | +## Mount example |
| 31 | + |
| 32 | +```ts |
| 33 | +import { |
| 34 | + createCronRoutes, |
| 35 | + createCronTicker, |
| 36 | + createRunTriggerCronDeliver, |
| 37 | +} from "@corbits/cron"; |
| 38 | +import { runCronMigrations } from "@corbits/cron/migrations"; |
| 39 | + |
| 40 | +await runMigrations(dbConfig, { schema: "public" }); |
| 41 | +await runCronMigrations(dbConfig, { schema: "public" }); |
| 42 | +app.route( |
| 43 | + `/api/tenants/:tenantId/cron`, |
| 44 | + createCronRoutes({ db, requireGrant }), |
| 45 | +); |
| 46 | +createCronTicker({ |
| 47 | + db, |
| 48 | + deliver: createRunTriggerCronDeliver(deliverer), |
| 49 | +}).start(); |
| 50 | +``` |
| 51 | + |
| 52 | +Run one ticker per hub process. The best real wiring is upstream in `workbench/apps/hub/src/server.ts` and `migrate.ts` (note its older pins), and each README has a "Using with Interchange" section. |
| 53 | + |
| 54 | +## Standalone clients (no hub) |
| 55 | + |
| 56 | +- `@corbits/embedding`: `embedTexts(texts, { baseURL, model })` over any OpenAI-compatible `/v1/embeddings` (OpenAI, Ollama, TEI, vLLM, Jina). It does not store or search. |
| 57 | +- `@corbits/reranking`: `rerankDocuments(query, docs, { baseURL, apiStyle: "tei" | "cohere" | "voyage" })` returns `{ id, score }[]`, best first. On failure keep the original order. |
| 58 | + |
| 59 | +## Grants |
| 60 | + |
| 61 | +Libraries declare the grants they need in `package.json` under `interchange.grantRequirements`. Give principals only what they need, for example `cron-schedule:*` create, `memory:search`, `artifact:*` create. |
| 62 | + |
| 63 | +## Need more |
| 64 | + |
| 65 | +- Triggering workflows from these: `use_skill interchange-workflows`. |
| 66 | +- A client UI for artifacts, mail, and runs: `use_skill corbits-ui-apps`. |
| 67 | +- Hub topology and credentials: `use_skill interchange-run-modes`. |
| 68 | +- Catalog: `use_skill corbits`. |
0 commit comments