@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/src/improvement-pass-binding.ts

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, LiveScope, ProjectId, TenantId, Timestamp } from '@kindgi/types';
+
+import type { EvalClassWeights } from './eval-run-binding.js';
+import type { PromotionActor } from './live-version-binding.js';
+import type { ProposalObjective } from './supervisor-binding.js';
+
+/**
+ * Improvement passes (`POST /v1/proposals/improve`,
+ * `/v1/improvement-passes`): the runtime looks for better values for an
+ * agent version's tunable settings (`x-kindgi-tunable`) on a test set,
+ * within a budget, and writes the best as an improvement proposal, which
+ * a reviewer then decides like any other. How a pass searches is the
+ * runtime's own; this is what starts one and reads it back.
+ *
+ * Optional: without it, `improve` answers `501 improve-unsupported`.
+ */
+export interface ImprovementPassBinding {
+  /** Record a pass as `running` and start it; it carries on in the background. */
+  start(input: StartImprovementPassInput): Promise<ImprovementPass>;
+  /** A pass, or `null` when the tenant has none with that id. */
+  get(input: {
+    readonly tenantId: TenantId;
+    readonly passId: string;
+  }): Promise<ImprovementPass | null>;
+  /** The tenant's passes, newest first; `agentId` narrows them. */
+  list(input: ListImprovementPassesInput): Promise<{
+    readonly data: readonly ImprovementPass[];
+    readonly nextCursor?: Cursor;
+  }>;
+  /** Stop a running pass: it ends `cancelled`, writing no proposal. */
+  cancel(input: {
+    readonly tenantId: TenantId;
+    readonly passId: string;
+    readonly by: string;
+  }): Promise<
+    | { readonly kind: 'ok'; readonly pass: ImprovementPass }
+    | { readonly kind: 'not-found' }
+    | { readonly kind: 'finished'; readonly pass: ImprovementPass }
+  >;
+}
+
+/** What a pass tunes: settings values, or (drafted by a model) a prompt template. */
+export type ImprovementTier = 'settings' | 'prompt';
+
+/** A provider and model, by the tenant's provider id. */
+export interface ImprovementModel {
+  readonly providerId: string;
+  readonly model: string;
+}
+
+export interface ImprovementBudget {
+  /** The most the pass's comparisons may cost, in US dollars. */
+  readonly maxCostUsd: number;
+  /** The most candidates it compares. */
+  readonly maxCandidates: number;
+}
+
+export interface StartImprovementPassInput {
+  readonly tenantId: TenantId;
+  /** The agent version's project, when the agent store records one. */
+  readonly projectId?: ProjectId;
+  readonly agentId: string;
+  /** The version whose settings it tunes. */
+  readonly fromVersion: string;
+  /** The live scope the proposal it writes is for. */
+  readonly scope: LiveScope;
+  /** The test set it searches and proves on (split into a search and a hold-out part). */
+  readonly suiteId: string;
+  readonly tiers: readonly ImprovementTier[];
+  readonly objective: ProposalObjective;
+  /** Which judgments its comparisons count (K4: trusted ones only, by default). */
+  readonly classWeights: EvalClassWeights;
+  /** For a prompt pass: what drafts the templates. */
+  readonly model?: ImprovementModel;
+  /** For a prompt pass: how many templates it drafts. */
+  readonly candidates?: number;
+  readonly budget: ImprovementBudget;
+  readonly requestedBy: PromotionActor;
+}
+
+/**
+ * When an `improve` schedule's fire starts a pass: enough trusted "no"
+ * judgments (recorded under a restricted class) on the agent's runs in the
+ * scope since its last pass, across enough runs, from enough judges. One
+ * judge can't start a pass alone.
+ */
+export interface ImproveThreshold {
+  readonly judgments: number;
+  readonly runs: number;
+  readonly judges: number;
+}
+
+/** An `improve` schedule's input (`config.input`): when a fire starts a pass, and the pass's options. */
+export interface ImproveScheduleInput {
+  readonly tiers: readonly ImprovementTier[];
+  readonly objective: ProposalObjective;
+  readonly classWeights: EvalClassWeights;
+  readonly model?: ImprovementModel;
+  readonly candidates?: number;
+  /** Each pass's budget; never more than what's left of the month's cap. */
+  readonly budget: ImprovementBudget;
+  readonly threshold: ImproveThreshold;
+  /** The most its passes may cost in a calendar month (UTC), in US dollars. */
+  readonly monthlyCapUsd: number;
+}
+
+export const IMPROVE_SCHEDULE_DEFAULTS = {
+  threshold: { judgments: 5, runs: 3, judges: 2 },
+  monthlyCapUsd: 20,
+  /** The shortest interval between an `improve` schedule's occurrences: a pass costs money. */
+  minIntervalSeconds: 3600,
+} as const;
+
+export interface ListImprovementPassesInput {
+  readonly tenantId: TenantId;
+  readonly agentId?: string;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export type ImprovementPassStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+
+/** What a finished pass found. */
+export type ImprovementPassOutcome =
+  /** Its best candidate beat the current values on the hold-out part: an improvement proposal. */
+  | { readonly kind: 'proposed'; readonly proposalId: string }
+  /** No candidate beat them by more than the noise (or within the budget); no proposal. */
+  | {
+      readonly kind: 'nothing-found';
+      readonly reason: string;
+      /** The best candidate's hold-out numbers, when one got that far. */
+      readonly holdOut?: {
+        readonly baseline: number | null;
+        readonly candidate: number | null;
+        readonly delta: number | null;
+        readonly spread?: number;
+      };
+    }
+  | { readonly kind: 'failed'; readonly message: string };
+
+export interface ImprovementPass {
+  readonly id: string;
+  readonly tenantId: TenantId;
+  readonly agentId: string;
+  readonly fromVersion: string;
+  readonly scope: LiveScope;
+  readonly suiteId: string;
+  readonly tiers: readonly ImprovementTier[];
+  readonly objective: ProposalObjective;
+  readonly classWeights: EvalClassWeights;
+  readonly model?: ImprovementModel;
+  readonly candidates?: number;
+  readonly budget: ImprovementBudget;
+  /** `user:<id>` or `service:<id>`. */
+  readonly requestedBy: string;
+  readonly status: ImprovementPassStatus;
+  /** Candidates compared so far. */
+  readonly candidatesEvaluated: number;
+  /** What its comparisons have cost so far, in US dollars (a decimal string). */
+  readonly costUsd: string;
+  /** Set once it ends. */
+  readonly outcome?: ImprovementPassOutcome;
+  /** Its comparisons so far, each an eval run to open. */
+  readonly comparisons?: readonly ImprovementPassComparison[];
+  /** The `improve` schedule and fire that started it; absent for a pass a person started. */
+  readonly trigger?: { readonly triggerId: string; readonly fireId: string };
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+  readonly finishedAt?: Timestamp;
+}
+
+/** One comparison a pass ran: the version as it is, a candidate, or the proposal's proof. */
+export interface ImprovementPassComparison {
+  /** Absent until it started. */
+  readonly evalRunId?: string;
+  /** `reference`: the version as it is; `candidate`: other values; `proof`: the proposal, on the hold-out part. */
+  readonly role: 'reference' | 'candidate' | 'proof';
+  readonly part: 'search' | 'hold-out';
+  /** For a candidate: its block, and the values it changed. */
+  readonly blockId?: string;
+  readonly changed?: Readonly<Record<string, unknown>>;
+  /** Its score on the pass's objective, once it finished (`null`: no judged evidence). */
+  readonly score?: number | null;
+  /** Why it didn't run or finish, when it didn't. */
+  readonly failed?: string;
+  /** For a drafted template that was never compared: why the check refused it. */
+  readonly refused?: readonly { readonly path: string; readonly message: string }[];
+  /** For a drafted template: what the drafter meant it to change. */
+  readonly hypothesis?: string;
+}

package/src/index.ts

@@ -10,11 +10,13 @@ export type {
 } from './app.js';
 export type { AppEnv } from './types.js';
 export {
+  SESSION_COOKIE_NAME,
   SESSION_TOKEN_PREFIX,
   encodeSessionToken,
   MULTI_TENANT_LOOKUP,
 } from './middleware/auth.js';
-export type { TokenResolution, TokenResolver } from './middleware/auth.js';
+export type { SessionCookieOptions, TokenResolution, TokenResolver } from './middleware/auth.js';
+export type { SignInOptionsRateLimit } from './routes/sign-in-options.js';
 export type {
   ClaimMappingScopesSpec,
   ClaimMappingSpec,
@@ -25,9 +27,20 @@ export type {
   IdentityProviderPage,
   IdentityProviderRegisterInput,
   IdentityProviderRegisterOutcome,
+  IdentityProviderSignInUrlsInput,
   IdentityProviderUnregisterInput,
   IdentityProviderUnregisterOutcome,
+  IdentityProviderUpdateInput,
+  IdentityProviderUpdateOutcome,
+  OAuth2ProviderConfig,
+  OidcProviderConfig,
   ProviderConfig,
+  ProviderConfigBase,
+  ProviderSignIn,
+  SamlAttributeMapping,
+  SamlProviderConfig,
+  SignInOption,
+  SignInOptionsInput,
   ExchangeCodeFn,
   ExchangeCodeInput,
   ExchangeCodeOutcome,
@@ -41,7 +54,9 @@ export type {
   SessionGetInput,
   SessionListInput,
   SessionPage,
+  SessionResolveTokenInput,
   SessionRevokeAllForUserInput,
+  SessionRevokeByProviderInput,
   SessionRevokeAllForUserOutcome,
   SessionRevokeInput,
   SessionRevokeOutcome,
@@ -50,11 +65,17 @@ export type {
   SessionTouchOutcome,
 } from './session-store-binding.js';
 export type {
+  IdentityCreateUserInput,
+  IdentityCreateUserResult,
   IdentityDirectoryBinding,
+  IdentityFindUserByEmailInput,
   IdentityGetUserInput,
   IdentityListSessionsInput,
   IdentityListUsersInput,
   IdentityRevokeSessionsInput,
+  IdentityUnregisterUserInput,
+  IdentityUnregisterUserRefusal,
+  IdentityUnregisterUserResult,
   RevokeSessionsResult,
   SessionSummary,
   SessionSummaryPage,
@@ -71,7 +92,13 @@ export {
   createInMemoryIdempotencyStore,
   idempotencyMiddleware,
 } from './middleware/idempotency.js';
-export type { IdempotencyStore, StoredIdempotencyEntry } from './middleware/idempotency.js';
+export type {
+  IdempotencyHold,
+  IdempotencyHoldOutcome,
+  IdempotencyHolds,
+  IdempotencyStore,
+  StoredIdempotencyEntry,
+} from './middleware/idempotency.js';
 export { CURRENT_EVENT_BUS_ENVELOPE_VERSION } from './event-bus-binding.js';
 export type {
   EventBusBinding,
@@ -89,9 +116,32 @@ export {
   type TokenListInput,
   type TokenMintInput,
   type TokenMintOutput,
+  type TokenMintRefusal,
+  type TokenPrincipal,
   type TokenRevokeInput,
   type TokenRevokeOutcome,
 } from './token-admin.js';
+export type {
+  ServiceAccount,
+  ServiceAccountBinding,
+  ServiceAccountChange,
+  ServiceAccountCreateInput,
+  ServiceAccountError,
+  ServiceAccountErrorCode,
+  ServiceAccountGrant,
+  ServiceAccountGrantTarget,
+  ServiceAccountListInput,
+  ServiceAccountRef,
+} from './service-account-binding.js';
+export type {
+  PersonGrant,
+  PersonGrantChange,
+  PersonGrantError,
+  PersonGrantErrorCode,
+  PersonGrants,
+  PersonGrantsBinding,
+  PersonRef,
+} from './person-grants-binding.js';
 export type {
   InvokeAgentBindingInput,
   InvokeFlowBindingInput,
@@ -115,6 +165,7 @@ export type {
 } from './reviewer-binding.js';
 export type {
   Approval,
+  ApprovalPosition,
   ApprovalStatus,
   HitlBinding,
   HitlBindingError,
@@ -156,7 +207,7 @@ export type {
   AdapterTestInput,
   AdapterTestOutcome,
 } from './adapter-binding.js';
-export { TRIGGER_KINDS } from './trigger-binding.js';
+export { SCHEDULE_DEFAULTS, TRIGGER_KINDS } from './trigger-binding.js';
 export {
   DEFAULT_PUBLIC_RUN_TOKEN_TTL_SECONDS,
   MAX_PUBLIC_RUN_TOKEN_RUNS,
@@ -173,12 +224,15 @@ export type {
   VerifyPublicRunTokenFailure,
   VerifyPublicRunTokenResult,
 } from './public-run-token.js';
+export { runFailure } from './run-failure.js';
+export type { RunFailure } from './run-failure.js';
 export {
   WEBHOOK_DELIVERY_STATUSES,
   WEBHOOK_EVENT_TYPES,
 } from './webhook-endpoint-binding.js';
 export type {
   FinishedRun,
+  ImprovementPassFinishedEvent,
   RunFinishedEvent,
   WebhookDelivery,
   WebhookDeliveryListInput,
@@ -206,18 +260,25 @@ export type {
   CronTriggerRecord,
   EventTriggerRecord,
   GetTriggerInput,
+  ListTriggerFiresInput,
   ListTriggersInput,
   RegisterCronTriggerInput,
   RegisterEventTriggerInput,
   RegisterTriggerError,
   RegisterTriggerInput,
   RegisterWebhookTriggerInput,
+  ScheduleCatchUp,
+  ScheduleOverlap,
+  TriggerFire,
+  TriggerFirePage,
   TriggerKind,
   TriggerLifecycleError,
   TriggerLifecycleInput,
   TriggerListPage,
+  TriggerOwner,
   TriggerRecord,
   TriggerRegistryBinding,
+  TriggerTarget,
   UpdateCronTriggerInput,
   UpdateEventTriggerInput,
   UpdateTriggerError,
@@ -258,6 +319,7 @@ export type {
 } from './flow-binding.js';
 export type {
   CapabilityDescriptor,
+  CapabilityProvider,
   CapabilityGetInput,
   CapabilityListInput,
   CapabilityPage,
@@ -345,8 +407,15 @@ export type {
   EvalCaseStoreBinding,
   JudgedEvalCase,
   JudgedItemSummary,
+  JudgedReason,
 } from './eval-case-binding.js';
-export { MAX_JUDGED_CASES } from './routes/judged-suites.js';
+export { MAX_JUDGED_CASES, buildJudgedSuite } from './routes/judged-suites.js';
+export type {
+  BuildJudgedSuiteInput,
+  BuildJudgedSuiteOutcome,
+  JudgedSuiteQuery,
+} from './routes/judged-suites.js';
+export { segmentsStartWith } from './routes/segments.js';
 export { MAX_JUDGED_HISTORY } from './routes/judgment-context.js';
 export type {
   JudgeClass,
@@ -430,6 +499,8 @@ export { GATE_METRICS } from './gate-policy-binding.js';
 export type { GateApproval, GateCheck, GateInput, GateResult } from './gate.js';
 export { evaluateGate, gateApproval } from './gate.js';
 export type { AgentReleaseGateDeps } from './routes/agent-releases.js';
+export { coordinatesOf as liveScopeCoordinates } from './routes/agent-releases.js';
+export type { GuardrailConfigCheck } from './routes/guardrails.js';
 export { EVAL_KINDS } from './eval-suite-binding.js';
 export type {
   EvalKind,
@@ -548,6 +619,8 @@ export type {
 } from './guardrail-binding.js';
 export type {
   MemoryBinding,
+  MemoryDeleteFactInput,
+  MemoryFactChangeOutcome,
   MemoryFactPage,
   MemoryGetFactInput,
   MemoryListFactsInput,
@@ -557,45 +630,94 @@ export type {
   MemoryRetrieveOutcome,
   MemorySupersedeFactInput,
   MemorySupersedeFactOutcome,
+  MemoryVerifyFactInput,
   MemoryWriteFactInput,
   MemoryWriteFactOutcome,
 } from './memory-binding.js';
 export type {
-  SupervisorApplyOutcome,
-  SupervisorApplyProposalInput,
-  SupervisorBinding,
-  SupervisorDraftOutcome,
-  SupervisorDraftProposalInput,
-  SupervisorDryRunOutcome,
-  SupervisorDryRunProposalInput,
-  SupervisorGetProposalInput,
-  SupervisorListProposalsInput,
-  SupervisorProposalPage,
-  SupervisorRollbackOutcome,
-  SupervisorRollbackProposalInput,
-  SupervisorSubmitReviewInput,
-  SupervisorSubmitReviewOutcome,
-  SupervisorWithdrawOutcome,
-  SupervisorWithdrawProposalInput,
-} from './supervisor-binding.js';
-export type {
-  FixProposal,
-  FixProposalStatus,
+  CreateMemoryErasureOutcome,
+  MemoryErasure,
+  MemoryErasureBinding,
+  MemoryErasureLedgerEntry,
+  MemoryErasureSelector,
+  MemoryErasureSelectorKind,
+  MemoryErasureStatus,
+  MemoryErasureWarning,
+  ReplayMemoryErasuresResult,
+} from './memory-erasure-binding.js';
+export type {
+  CreateProposalInput,
+  CreateProposalOutcome,
+  GetProposalInput,
+  ListProposalsInput,
   Observation,
   ObservationStatus,
   ObservedViolation,
-  PassCriterion,
-  PatternKind,
-  PatternRef,
-  PromptChange,
+  ProposalCandidate,
+  ProposalDrafter,
+  ProposalEvaluationRef,
+  ProposalEvidence,
+  ProposalObjective,
+  ProposalStep,
+  ProposalTier,
   ProposedChange,
-  RetrievalChange,
-  RetrievalIntentShape,
+  RecordProposalInput,
+  RecordProposalOutcome,
+  StoredProposal,
+  StoredProposalPage,
+  SupervisorBinding,
   SupervisorObservationPage,
   SupervisorQueryObservationsInput,
   SupervisorQueryObservationsOutcome,
-  ToolConfigChange,
 } from './supervisor-binding.js';
+export type {
+  ImproveScheduleInput,
+  ImproveThreshold,
+  ImprovementBudget,
+  ImprovementModel,
+  ImprovementPass,
+  ImprovementPassBinding,
+  ImprovementPassComparison,
+  ImprovementPassOutcome,
+  ImprovementPassStatus,
+  ImprovementTier,
+  ListImprovementPassesInput,
+  StartImprovementPassInput,
+} from './improvement-pass-binding.js';
+export { IMPROVE_SCHEDULE_DEFAULTS } from './improvement-pass-binding.js';
+export {
+  DEFAULT_BUDGET as DEFAULT_IMPROVEMENT_BUDGET,
+  parseImproveScheduleInput,
+  serializePass,
+} from './routes/improvement-passes.js';
+export { sampleCases } from './eval-sample.js';
+export type { EvalOverrides, EvalSample } from './eval-run-binding.js';
+export {
+  DRAFTED_PROPOSAL_APPROVAL,
+  createProposalService,
+  proposalNotFound,
+} from './proposal-service.js';
+export type {
+  DraftProposalInput,
+  EvaluateProposalInput,
+  ProposalFacts,
+  ProposalOutcome,
+  ProposalService,
+  ProposalServiceDeps,
+  ProposalServiceError,
+} from './proposal-service.js';
+export {
+  FIX_PROPOSAL_STATUSES,
+  PROPOSAL_ACTIONS,
+  evaluationOutcome,
+  proposalActionAllowed,
+  proposalStatus,
+} from './proposal-status.js';
+export type {
+  FixProposalStatus,
+  ProposalAction,
+  ProposalEvaluationOutcome,
+} from './proposal-status.js';
 export type {
   Deployment,
   DeploymentBinding,