Ruling 1: the bus runtime passes launchSettings a key lineage lookup read from its own credential records (ids only). A new daily key quota takes the earliest stored since among the old document's daily key quotas in its key's lineage, and now only when there is none. A reset still sets now, a caller-supplied since still refuses, and a quota removed and added back in a later write is new. A failed or malformed lookup refuses proxy-key-refused; a write that adds no new daily key quota never calls it. Ruling 2: every limits refresh updates the remembered orphan set, an empty set when no daily key quota is left, so a quota removed and added back logs again. In memory only: a restart is a fresh observation. Ruling 3: pollSettledAfterTick yields on the real setImmediate, captured at load, inside its deadline. Tests: p5-key-lineage (writer move counts 160, reset restarts, lookup failure, orphan remove and re-add), p5-runtime (exhausted on A, moved to B through the real runtime, refuses), p5-background (barrier with every timer mocked), token-limit-settings (earliest, no match, re-add, caller since, malformed answers, default refusal). READMEs: business, plugins, daily-quota, cliproxy-queue.
74 lines
4.6 KiB
Markdown
74 lines
4.6 KiB
Markdown
# Optional CLIProxyAPI queue telemetry (P5)
|
|
|
|
Enable through the human `plugins.set` transport with `plugins.usage` set to
|
|
`"cliproxy-queue"`. Omission is off. The same patch may set
|
|
`usage.cliproxyQueue.pollSeconds` (integer 1 through 59, default 15); `usage: null`
|
|
removes this setting. Both switches and polling changes are human-only, including
|
|
on the tester path. The existing instance configuration and proxy key paths do
|
|
not change.
|
|
|
|
Interface 1 exports `read({ readUsageQueue })`. The bus hands the module one
|
|
frozen object holding one function, its management client's queue read, and
|
|
nothing else (row 333 R3), so no key write, credential call or OAuth call is
|
|
reachable from it. The module never reads credentials, configuration paths or
|
|
the environment. Each read performs exactly one bounded GET of
|
|
`/v8/management/observability/usage/queue?count=100` per poll. Existing fixed
|
|
loopback, timeout, response byte cap and no-redirect/no-retry controls apply.
|
|
The proxy's array response is validated completely and mapped immediately:
|
|
`api_key` and `source` become their first 12 hexadecimal SHA-256 characters.
|
|
Only whitelisted token counts, a failure flag/status, and IDs leave the client.
|
|
No request IDs, failure bodies, client values or upstream values are retained.
|
|
Malformed batches fail atomically and yield a fixed, value-free failure code.
|
|
|
|
One bus/store writer owns the reader for its instance. It serializes polls,
|
|
drains the shared queue once, and assigns IDs to current and retiring model-key
|
|
metadata owners. Unknown `msk-` IDs go to the reconcile receipt. Foreign keys
|
|
without that prefix are ignored. Disabled businesses receive no telemetry.
|
|
|
|
Telemetry uses the existing append-only usage table with source
|
|
`@proxy/cliproxy-queue`, separate from native session source records. `turnRecords`
|
|
excludes it before every limit check and native usage total. Proxy totals may be
|
|
incomplete (60-second upstream retention and a 100-event drain); the Console
|
|
labels them proxy-reported and reports the reader's availability. They never
|
|
independently enforce quotas.
|
|
|
|
Native transcript counts carry the immutable run's safe `modelKeyId` in the
|
|
usage cursor, preserved at turn begin and end. The Console exposes `byKey`.
|
|
A business can set a daily per-key quota at
|
|
`launch.limits.tokens.keys.<12-hex-key-id>` with `{limit, since, reset, timeZone}`;
|
|
the human writer stamps `since`. Enable `limit-check: ["daily-quota"]` to apply
|
|
that quota. Plain `{limit,since}` keys leaves remain cumulative legacy account limits, even
|
|
when the name is twelve hex characters. They use `token-limit` and never resolve
|
|
model metadata. Omitting a limit means no quota. Existing named account keys and
|
|
`tokens.daily.<account>` retain their existing behavior. Model-key limits and
|
|
resets are human-only through every organization writer. Missing, ambiguous or
|
|
foreign run-key metadata fails closed with `proxy-key-refused`; a run bound to a
|
|
retiring key keeps that key id in its usage records.
|
|
|
|
A key quota follows the agent its key id belongs to, across rotations and
|
|
re-issues, for as long as the agent stays hired: it applies to any key in that
|
|
agent's lineage (current, retiring and up to 64 earlier ids) and counts the
|
|
whole lineage, while usage records and the Console's per-key counts stay per key
|
|
id. A fire removes the agent's model record, so a re-hired agent starts a new
|
|
lineage and a quota named by an old id matches no agent: it limits nothing, the
|
|
Console usage view lists it, and the bus logs one value-free
|
|
`limit-key-orphaned` line when it becomes orphaned. An agent with no model key
|
|
under a key quota refuses `key-quota-no-model-key`; an id in two agents'
|
|
lineages, or a run bound to an id the agent no longer holds, refuses
|
|
`proxy-key-refused`. The 64 is a limit: once an id falls out of the newest 64,
|
|
its quota is orphaned while the agent stays hired.
|
|
|
|
After a rotation no move is needed. A quota moved to the agent's new key id
|
|
keeps its count (row 333 R4): the human writer gives a new key quota the
|
|
earliest `since` among the old file's key quotas whose ids are in the same
|
|
agent's lineage, asking the bus for that lineage (ids only, from its own
|
|
credential records), and stamps now only when none of them holds one. Only an
|
|
explicit reset restarts the count. A quota removed in one write and added back
|
|
in a later one is a new quota and gets now. If the lineage can't be read, a
|
|
write that adds a key quota refuses `proxy-key-refused`.
|
|
|
|
The orphan line is logged at the first limits refresh that finds the quota
|
|
orphaned, which can be at boot or before a launch refusal. A quota removed and
|
|
added back logs again. The bus keeps what it has logged in memory only, so a
|
|
restart is a fresh observation and a quota still orphaned logs once more.
|