Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,13 +163,14 @@ While pi is running, use these provider commands without restarting:
- `/commandcode-refresh` fetches and re-registers the current model catalog, and resets the latest transport status. Every inference attempt uses the Provider API; entitlement denials are not cached. Overlapping refreshes are coalesced, and a failed refresh keeps the last valid catalog active.
- `/commandcode-status` shows redacted discovery diagnostics, including the source, model count, timestamps, cache path, endpoint, and warning. Transport status is `unknown` until the latest inference attempt completes successfully; a denial remains `unknown`, not proof of API entitlement. If a Responses reasoning event has an unsupported shape, a separate stream warning is cleared when the next Responses HTTP request starts, before its outcome is known. Requests on Chat Completions or Messages do not clear it. The slot is shared by concurrent Responses requests, so a late warning from an older in-flight response can still replace it. The event is preserved unchanged; no reasoning text is included in the warning.
- `/commandcode-diagnostics` shows a shareable support report: plugin/host version, CLI snapshot, selected transport and wire, capability provenance, price status, and the latest request's HTTP status, attempts, outcome, first body-chunk latency and longest gap. It keeps only one request summary in memory. It never collects prompts, tool content, credentials, raw errors, account data or configured local paths. Model identifiers come from the host; recognized path-/credential-shaped values are redacted, but custom names can still identify your setup. Request IDs are included only when they match a bounded hexadecimal/UUID format. Timing is measured between body chunks, not tokens; first-chunk latency may include an error response. A request started most recently owns the report even if another request finishes later. Retry counts are scoped to that stream call, not host-level retries. Review the report before sharing it.
- `/commandcode-zdr` shows the effective zero-data-retention state; `/commandcode-zdr on` or `/commandcode-zdr off` writes it to the agent settings file. The provider re-registers so the change applies to the next request and survives restart. Saving is supported on pi only; Oh My Pi keeps the `CMD_ZDR` environment opt-in. A symlinked `settings.json` is updated through its target. Turning it off is refused while `CMD_ZDR` or `COMMANDCODE_ZDR` is set, because the environment wins.
- `/commandcode-quota` shows your Command Code account usage and quota in a dashboard-style layout: credits remaining and used with a percentage, monthly/purchased/free sources, the current plan, available usage totals, the API key name, and the 5-hour and weekly usage windows.

As an explicit exception to the inference policy, the `commandcode-quota` command reads from the internal Command Code alpha usage endpoints (the same ones the `cmd` CLI `/usage` command uses): `whoami`, `billing/credits`, `billing/subscriptions`, and `usage/summary`. It authenticates with the same API key the provider already uses. These requests are GET-only account/usage reads, not an inference fallback. Their success says nothing about Provider API entitlement; the undocumented schemas and availability may change independently. If the command cannot reach those endpoints or an endpoint schema changes, unavailable sections are reported explicitly instead of being displayed as zero usage. Output is plain text (via `ui.notify`) so it works across pi and compatible hosts such as OMP.

On Oh My Pi the provider also registers an OMP usage provider through the `usage` field of `pi.registerProvider`, reading the same endpoints with the same credentials. It supplies the account's 5-hour and weekly usage windows, credits remaining and used against the billing-period pool, and the current plan to the host's usage surfaces, and it follows the same rule for sections the API does not report. pi has no such field and ignores it.

Set `CMD_ZDR=1` to send Command Code's documented `x-cmd-zdr: 1` zero-data-retention header. The legacy `COMMANDCODE_ZDR=1` alias remains supported.
Set `CMD_ZDR=1` to send Command Code's documented `x-cmd-zdr: 1` zero-data-retention header. The legacy `COMMANDCODE_ZDR=1` alias remains supported. On pi, a settings file is an alternative where exporting an environment variable is inconvenient: add `{ "commandcode": { "enableZDR": true } }` to `settings.json` in the agent directory (`~/.pi/agent/settings.json` for pi), or run `/commandcode-zdr on`. The provider reads that agent-directory file directly, so a project `.pi/settings.json` cannot turn the opt-in on or off; the environment takes precedence over the file. Oh My Pi ignores that file and keeps the environment opt-in only, so a settings file shared with a pi install cannot switch protection on there. A single leading UTF-8 BOM in the file is tolerated. Only a literal `true` enables it, and every other settings key is preserved when the command writes it. The opt-in is sent as a registration header, so an edit made outside the command applies after `/reload` or a restart. Some models have no ZDR-capable upstream yet; a request for those models fails instead of routing through a non-ZDR provider.

The following environment variables are intended for tests, local mocks, and compatible API endpoints:

Expand Down
133 changes: 120 additions & 13 deletions index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,14 @@ import { registerCommandCodeQuota } from "./src/quota-command.ts"
import { normalizeCommandCodeResponsesResponse } from "./src/responses-stream.ts"
import { modelWireTraits, withResponsesWireRepairs } from "./src/responses-compat.ts"
import { createCommandCodeRuntime } from "./src/runtime.ts"
import {
describeZdr,
loadZdrSettings,
resolveZdr,
saveZdrSetting,
zdrHeaders,
type ZdrState,
} from "./src/zdr.ts"
import {
compatForEndpoint,
endpointChoiceForModel,
Expand Down Expand Up @@ -81,6 +89,15 @@ function compatApiProviderRegistrar(): ((...args: unknown[]) => unknown) | undef
return typeof register === "function" ? (register as (...args: unknown[]) => unknown) : undefined
}

/**
* The settings.json opt-in is pi-only. pi registers the compat API provider that
* applies a re-registered header; Oh My Pi does not, so its contract stays the
* environment only. Both paths use the same probe as the write guard.
*/
function settingsZdrSupported(): boolean {
return compatApiProviderRegistrar() !== undefined
}

function registerCompatApiProvider(stream: CompatStreamFunction): void {
compatApiProviderRegistrar()?.(
{ api: COMMAND_CODE_API, stream, streamSimple: stream },
Expand Down Expand Up @@ -112,13 +129,6 @@ function providerApiKey(): string | undefined {
return compatApiProviderRegistrar() ? "$COMMAND_CODE_API_KEY" : undefined
}

function commandCodeHeaders(): Record<string, string> | undefined {
if (process.env.CMD_ZDR === "1" || process.env.COMMANDCODE_ZDR === "1") {
return { "x-cmd-zdr": "1" }
}
return undefined
}

/**
* The registered config, plus Oh My Pi's extension-only usage hook.
*
Expand Down Expand Up @@ -181,19 +191,23 @@ function createProviderConfig(
models: readonly CommandCodeModel[],
apiBase: string,
streamCommandCode: ProviderConfig["streamSimple"],
headers: Record<string, string> | undefined,
): CommandCodeProviderConfig {
const headers = commandCodeHeaders()
// The host merges a re-registration over the previous one and preserves
// undefined values, so an empty object is what clears a previously sent
// header after ZDR is turned off.
const registeredHeaders = headers ?? {}
return {
name: "Command Code",
baseUrl: apiBase,
apiKey: providerApiKey(),
api: COMMAND_CODE_API,
streamSimple: streamCommandCode,
headers,
headers: registeredHeaders,
// Same alpha endpoints and credentials as the /commandcode-quota command.
usage: createCommandCodeUsageProvider({
apiBase: quotaApiBase(apiBase),
headers,
headers: registeredHeaders,
}),
oauth: {
name: "Command Code",
Expand All @@ -216,7 +230,7 @@ function createProviderConfig(
},
contextWindow: model.contextWindow,
maxTokens: model.maxTokens,
headers,
headers: registeredHeaders,
compat: { ...compatForModel(model), commandCodeWire: model.api },
})),
}
Expand Down Expand Up @@ -260,6 +274,9 @@ export default async function (pi: ExtensionAPI) {
// Hosts may select their built-in Command Code model before loading extensions.
// Rebind that stale selection to our registered transport before the first turn.
pi.on("session_start", async (_event, ctx) => {
// Applies the opt-in from the agent settings file and picks up a file
// changed since the last load.
await applyHostZdr()
if (ctx.model?.provider !== "commandcode") return
const registered = ctx.modelRegistry.find("commandcode", ctx.model.id)
if (registered?.api === COMMAND_CODE_API && ctx.model.api !== COMMAND_CODE_API) {
Expand All @@ -277,6 +294,13 @@ export default async function (pi: ExtensionAPI) {
// the wire each model answers on is resolved here from the catalog that
// `createProviderConfig` registered. Unknown ids fall back to the id rule.
const catalogModels = new Map<string, CommandCodeModel>()
// The environment is readable while extensions load; the agent settings file
// is read at session start so a change made while the host was stopped applies
// before the first request. The environment is fixed for the process, and the
// file only reloads with the extension. /commandcode-zdr updates this state
// after writing the file.
const settingsPath = join(getAgentDir(), "settings.json")
let zdr: ZdrState = resolveZdr(undefined)
const routingPath = join(getAgentDir(), "commandcode-routing.json")
let routing: EndpointOverrides = {}
let routingWarning: string | undefined
Expand Down Expand Up @@ -413,15 +437,97 @@ export default async function (pi: ExtensionAPI) {
const compatStream: CompatStreamFunction = measuredStream
registerCompatApiProvider(compatStream)

const registerProvider = () =>
pi.registerProvider(
"commandcode",
createProviderConfig([...catalogModels.values()], apiBase, measuredStream, zdrHeaders(zdr)),
)
const applyHostZdr = async () => {
// Read the agent settings file, not the host's merged global+project view:
// the command writes this file, so a project override must not be able to
// invalidate the persisted opt-in at restart. Only pi owns this file; OMP
// must not pick up a leftover one, so it keeps the environment opt-in.
const resolved = resolveZdr(
settingsZdrSupported() ? await loadZdrSettings(settingsPath) : undefined,
)
const changed = resolved.enabled !== zdr.enabled
zdr = resolved
// Re-registration is the only way to change a registration header, and it
// needs a catalog to register.
if (changed && catalogModels.size > 0) registerProvider()
}

pi.on("message_end", async (event, ctx) => {
if (event.message.role !== "assistant") return
const normalized = normalizeCommandCodeMessage(event.message, ctx.model?.provider)
return normalized ? { message: normalized.message } : undefined
})

// The opt-in is only sent as a registration header, so a change needs the
// provider re-registered before it reaches the next request. Re-registering
// is the same path /commandcode-refresh already uses.
pi.registerCommand("commandcode-zdr", {
description: "Show or set zero data retention: /commandcode-zdr [on|off]",
handler: async (args, ctx) => {
const [choice, extra] = args.trim().split(/\s+/)
if (!choice) {
ctx.ui.notify(
`Command Code zero data retention: ${describeZdr(zdr)}. Usage: /commandcode-zdr on|off`,
"info",
)
return
}
if ((choice !== "on" && choice !== "off") || extra) {
ctx.ui.notify("Usage: /commandcode-zdr on|off", "warning")
return
}
// Only pi reads this settings file back and applies a re-registered header
// to the next request; other hosts keep the environment opt-in.
if (!settingsZdrSupported()) {
ctx.ui.notify(
"Saving zero data retention is only supported on pi. Set CMD_ZDR=1 in the environment instead.",
"warning",
)
return
}
// The environment wins at resolution time, so refuse instead of writing a
// setting that would not take effect.
if (choice === "off" && zdr.source === "env") {
ctx.ui.notify(
`Zero data retention is forced on by ${zdr.envVar ?? "the environment"}. Unset that variable to disable it.`,
"warning",
)
return
}
await ctx.waitForIdle?.()
let written: unknown
try {
written = await saveZdrSetting(settingsPath, choice === "on")
} catch (error) {
ctx.ui.notify(
error instanceof Error ? error.message : "Could not save settings.json",
"error",
)
return
}
zdr = resolveZdr(written)
// Without a catalog there is nothing to register; the next successful
// load or /commandcode-refresh picks the saved setting up.
const applied = catalogModels.size > 0
if (applied) registerProvider()
ctx.ui.notify(
`Command Code zero data retention: ${describeZdr(zdr)}. Saved to settings.json; ` +
(applied
? "applies to the next request and survives restart."
: "applies after the next catalog load or /commandcode-refresh."),
"info",
)
},
})

registerCommandCodeQuota(pi, {
apiBase: quotaApiBase(apiBase),
headers: commandCodeHeaders(),
headers: () => zdrHeaders(zdr),
})

const runtime = createCommandCodeRuntime<ProviderConfig, ExtensionCommandContext>(pi, {
Expand All @@ -438,7 +544,7 @@ export default async function (pi: ExtensionAPI) {
createProviderConfig: (models) => {
catalogModels.clear()
for (const model of models) catalogModels.set(model.id, model)
return createProviderConfig(models, apiBase, measuredStream)
return createProviderConfig(models, apiBase, measuredStream, zdrHeaders(zdr))
},
getDiagnostics: (model) => {
let route = "not selected"
Expand Down Expand Up @@ -473,6 +579,7 @@ export default async function (pi: ExtensionAPI) {
request: diagnostics.snapshot(),
}),
endpointStatus,
`zdr: ${describeZdr(zdr)}`,
routingWarning,
]
.filter(Boolean)
Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
"LICENSE"
],
"scripts": {
"test": "npm run typecheck && npm run test:diagnostics && npm run test:routing && node --test tests/test-release.mjs tests/test-maintenance-alert.mjs tests/test-pi-child-cleanup.mjs tests/test-entrypoint-typecheck.mjs tests/test-host-protocol-helpers.mjs && tsx tests/test-package-manifest.ts && tsx tests/test-api-key.ts && tsx tests/test-pure-functions.ts && tsx tests/test-models.ts && tsx tests/test-model-metadata-check.ts && tsx tests/test-runtime.ts && tsx tests/test-pricing.ts && tsx tests/test-pricing-check.ts && tsx tests/test-cost.ts && tsx tests/test-oauth.ts && tsx tests/test-overflow.ts && tsx tests/test-quota.ts && tsx tests/test-quota-command.ts && tsx tests/test-usage.ts && tsx tests/test-transport.ts && tsx tests/test-responses-compat.ts && node tests/test-pi-isolated.mjs && node tests/test-pi-authenticated.mjs && node tests/test-pi-local.mjs && node tests/test-omp-compat.mjs && node tests/test-host-protocols.mjs && node tests/test-endpoint-routing.mjs",
"test": "npm run typecheck && npm run test:diagnostics && npm run test:routing && node --test tests/test-release.mjs tests/test-maintenance-alert.mjs tests/test-pi-child-cleanup.mjs tests/test-entrypoint-typecheck.mjs tests/test-host-protocol-helpers.mjs && tsx tests/test-package-manifest.ts && tsx tests/test-api-key.ts && tsx tests/test-pure-functions.ts && tsx tests/test-models.ts && tsx tests/test-model-metadata-check.ts && tsx tests/test-runtime.ts && tsx tests/test-pricing.ts && tsx tests/test-pricing-check.ts && tsx tests/test-cost.ts && tsx tests/test-oauth.ts && tsx tests/test-overflow.ts && tsx tests/test-quota.ts && tsx tests/test-quota-command.ts && tsx tests/test-usage.ts && tsx tests/test-transport.ts && tsx tests/test-responses-compat.ts && tsx tests/test-zdr.ts && node tests/test-pi-isolated.mjs && node tests/test-pi-authenticated.mjs && node tests/test-pi-local.mjs && node tests/test-omp-compat.mjs && node tests/test-host-protocols.mjs && node tests/test-endpoint-routing.mjs",
"typecheck": "tsc --noEmit",
"typecheck:entrypoint": "node scripts/typecheck-entrypoint.mjs",
"format:check": "prettier --check '**/*.{ts,mjs,json,md}'",
Expand All @@ -41,7 +41,7 @@
"sync:commandcode-catalog": "tsx .github/scripts/check-commandcode-model-metadata.ts command-code@latest --write",
"test:quota": "tsx tests/test-quota.ts && tsx tests/test-quota-command.ts && tsx tests/test-usage.ts",
"test:usage": "tsx tests/test-usage.ts",
"test:unit": "npm run test:diagnostics && npm run test:routing && tsx tests/test-api-key.ts && tsx tests/test-pure-functions.ts && tsx tests/test-models.ts && tsx tests/test-model-metadata-check.ts && tsx tests/test-runtime.ts && tsx tests/test-pricing.ts && tsx tests/test-pricing-check.ts && tsx tests/test-cost.ts && tsx tests/test-oauth.ts && tsx tests/test-overflow.ts && tsx tests/test-quota.ts && tsx tests/test-quota-command.ts && tsx tests/test-usage.ts && tsx tests/test-transport.ts && tsx tests/test-responses-compat.ts",
"test:unit": "npm run test:diagnostics && npm run test:routing && tsx tests/test-api-key.ts && tsx tests/test-pure-functions.ts && tsx tests/test-models.ts && tsx tests/test-model-metadata-check.ts && tsx tests/test-runtime.ts && tsx tests/test-pricing.ts && tsx tests/test-pricing-check.ts && tsx tests/test-cost.ts && tsx tests/test-oauth.ts && tsx tests/test-overflow.ts && tsx tests/test-quota.ts && tsx tests/test-quota-command.ts && tsx tests/test-usage.ts && tsx tests/test-transport.ts && tsx tests/test-responses-compat.ts && tsx tests/test-zdr.ts",
"test:api-key": "tsx tests/test-api-key.ts",
"test:models": "tsx tests/test-models.ts && tsx tests/test-model-metadata-check.ts",
"test:diagnostics": "tsx tests/test-diagnostics.ts",
Expand All @@ -65,6 +65,7 @@
"test:e2e:live:provider": "node scripts/live-e2e-profile.mjs provider",
"test:e2e:live:all": "node scripts/live-e2e-profile.mjs goat provider",
"test:cost": "tsx tests/test-cost.ts",
"test:zdr": "tsx tests/test-zdr.ts",
"test:responses-compat": "tsx tests/test-responses-compat.ts"
},
"pi": {
Expand Down
5 changes: 3 additions & 2 deletions src/quota-command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ interface QuotaCommandApi {

interface RegisterQuotaCommandOptions {
apiBase: string
headers?: Record<string, string>
/** A function is resolved per run so a header changed after startup (ZDR) is sent. */
headers?: Record<string, string> | (() => Record<string, string> | undefined)
getConfiguredKey?: () => string | undefined
fetchQuota?: typeof fetchCommandCodeQuota
}
Expand Down Expand Up @@ -54,7 +55,7 @@ export function registerCommandCodeQuota(
const result = await fetchQuota({
apiKey,
baseUrl: options.apiBase,
extraHeaders: options.headers,
extraHeaders: typeof options.headers === "function" ? options.headers() : options.headers,
})
if (!result.ok) {
ctx.ui.notify(redactValue(result.error.message), "error")
Expand Down
Loading