Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

3.9 KB
Raw Blame
/**
 * Provider REFERENCE grammar (#7564, epic #7561): the two spellings a
 * `{ providerId, model, effort }` selection may name a provider by.
 *
 *   - a PRESET id — a `data/providers.json` record: `^[a-z0-9][a-z0-9-]*$`
 *     (the same slug `aiToolkit/validation.js#providerSchema.id` mints);
 *   - a COMPOSITE id — `<harness>.<method>@<service-slug>[+<bootstrap-slug>]`,
 *     e.g. `pi.tui@nvidia-nim-free`, `direct.api@ollama`,
 *     `claude.cli@anthropic+corp-auth`: an enabled harness driven in one of its
 *     execution methods against an enabled service instance, materialized at
 *     resolve time and never persisted as a record.
 *
 * The two grammars cannot collide: `.` and `@` are outside the preset
 * alphabet, so a composite is recognizable from the string alone and a preset
 * lookup can never accidentally read one. The `+<bootstrap-slug>` suffix names
 * a credential-bootstrap app (`settings.credentialBootstraps`) and is legal
 * only with a process method (`cli` / `tui`): a direct API call has no spawn
 * for a wrapper to sit in front of.
 *
 * Pure and dependency-free so both the browser and the vendored toolkit
 * (`aiToolkit/internal/providerRef.js`, a deliberate mirror behind
 * `providerRef.parity.test.js`) can carry the same rule.
 */

/** A preset record id — the slug `createProvider` assigns. */
export const PRESET_ID_RE = /^[a-z0-9][a-z0-9-]*$/;

/**
 * `<harness>.<method>@<service-slug>[+<bootstrap-slug>]`. Groups: harness id,
 * method, service slug, optional bootstrap slug.
 */
export const COMPOSITE_ID_RE = /^([a-z0-9-]+)\.(cli|tui|api)@([a-z0-9][a-z0-9-]*)(?:\+([a-z0-9][a-z0-9-]*))?$/;

/** Longest reference any selection field accepts. */
export const MAX_PROVIDER_REF_LENGTH = 200;

/** The validation message a selection field reports for a malformed reference. */
export const PROVIDER_REF_MESSAGE = 'provider must be a preset id (lowercase alphanumeric with hyphens) or a composite <harness>.<cli|tui|api>@<service-slug>[+<bootstrap-slug>] (the bootstrap suffix only with cli or tui)';

/** The message a PRESET-ONLY field reports when handed a composite. */
export const PRESET_ONLY_MESSAGE = 'must be a preset provider id (lowercase alphanumeric with hyphens); a composite harness.method@service selection is not accepted here';

/**
 * Parse a provider reference.
 *
 * @param {unknown} id
 * @returns {{kind: 'preset', id: string}
 *   | {kind: 'composite', id: string, harnessId: string, method: 'cli'|'tui'|'api', serviceSlug: string, bootstrapSlug: string|null}
 *   | null} `null` for anything that is neither grammar — including a
 *   bootstrap suffix on the `api` method.
 */
export function parseProviderRef(id) {
  if (typeof id !== 'string' || id.length === 0 || id.length > MAX_PROVIDER_REF_LENGTH) return null;
  if (PRESET_ID_RE.test(id)) return { kind: 'preset', id };
  const match = COMPOSITE_ID_RE.exec(id);
  if (!match) return null;
  const [, harnessId, method, serviceSlug, bootstrapSlug = null] = match;
  if (bootstrapSlug && method === 'api') return null;
  return { kind: 'composite', id, harnessId, method, serviceSlug, bootstrapSlug };
}

/** Whether `id` is a well-formed composite reference. */
export const isCompositeProviderId = (id) => parseProviderRef(id)?.kind === 'composite';

/** Whether `id` is a well-formed preset record id. */
export const isPresetProviderId = (id) => parseProviderRef(id)?.kind === 'preset';

/**
 * The composite id for its parts. Throws on parts that do not form a valid
 * reference, so a caller can never mint an id `parseProviderRef` rejects.
 *
 * @param {{harnessId: string, method: string, serviceSlug: string, bootstrapSlug?: string|null}} parts
 * @returns {string}
 */
export function formatCompositeId({ harnessId, method, serviceSlug, bootstrapSlug = null }) {
  const id = `${harnessId}.${method}@${serviceSlug}${bootstrapSlug ? `+${bootstrapSlug}` : ''}`;
  if (parseProviderRef(id)?.kind !== 'composite') {
    throw new Error(`"${id}" is not a composite provider id`);
  }
  return id;
}