@makaio/framework 1.0.0-dev-1784154668798 → 1.0.0-dev-1784706768858

package/dist/hook-responses-mmqRa2Dq.d.mts

@@ -0,0 +1,825 @@
+import { z } from "zod";
+
+//#region core/contracts/src/version/primitives.d.ts
+/**
+ * npm semver range syntax (e.g. `">=1.0.0 <2.0.0"`, `"^1.5.0"`).
+ *
+ * Used by all range-bearing compatibility fields in descriptors and manifests.
+ */
+type VersionRange = string;
+/**
+ * Exact semver version (e.g. `"1.0.72"`).
+ *
+ * Used for concrete version pins such as preferred binary versions.
+ */
+type VersionLiteral = string;
+/** Validates that the string is a valid npm semver range. */
+declare const VersionRangeSchema: z.ZodString;
+/**
+ * Check whether a concrete version satisfies a semver range.
+ *
+ * Centralizes the `{ includePrerelease: true }` policy so every compatibility
+ * check in the framework uses the same semantics.
+ * @param version - Concrete semver version string.
+ * @param range - npm semver range to test against.
+ * @returns `true` when the version falls within the range.
+ */
+declare function versionSatisfies(version: string, range: VersionRange): boolean;
+/**
+ * Check whether a semver range is a universal wildcard (`*`, `>=0.0.0`, etc.).
+ *
+ * Uses the `semver` library's normalization so all universal range syntaxes are
+ * recognized, not just the literal `'*'` string.
+ * @param range - Semver range to test.
+ * @returns `true` when the range matches any version.
+ */
+declare function isUniversalRange(range: string): boolean;
+/** Validates that the string is an exact semver version. */
+declare const VersionLiteralSchema: z.ZodString;
+//#endregion
+//#region core/contracts/src/client/definition.d.ts
+/**
+ * Schema for a capability annotation attached to a native client tool.
+ *
+ * Captures a capability tag (e.g. `'shell.execute'`) and an optional
+ * human-readable description so the Harness UI can explain what a tool does
+ * without coupling to the platform capability taxonomy.
+ */
+declare const ClientToolCapabilityAnnotationSchema: z.ZodObject<{
+  tag: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ClientToolCapabilityAnnotation = z.infer<typeof ClientToolCapabilityAnnotationSchema>;
+/**
+ * Schema for a single native tool provided by a client binary.
+ *
+ * Native tools are those the client binary exposes directly (e.g. `bash`,
+ * `file_edit`). They are declared by the client package and seeded into
+ * the harness at startup.
+ */
+declare const ClientToolDefinitionSchema: z.ZodObject<{
+  name: z.ZodString;
+  friendlyName: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  category: z.ZodOptional<z.ZodString>;
+  capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    tag: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ClientToolDefinition = z.infer<typeof ClientToolDefinitionSchema>;
+/**
+ * Schema for a log source definition contributed by a client package.
+ *
+ * Log sources describe where the client binary writes conversation logs so the
+ * Makaio log-import service can discover and ingest them.
+ */
+declare const LogSourceDefinitionSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  glob: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LogSourceDefinition = z.infer<typeof LogSourceDefinitionSchema>;
+/**
+ * Schema for a hook event declaration on a client definition.
+ *
+ * Declares which native hook events the client binary fires. Used by the
+ * wiring layer to know what hooks to install, and by the UI to display
+ * available events.
+ */
+declare const ClientHookEventDeclarationSchema: z.ZodObject<{
+  name: z.ZodString;
+  frameworkSubject: z.ZodOptional<z.ZodString>;
+  responseCapabilities: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+type ClientHookEventDeclaration = z.infer<typeof ClientHookEventDeclarationSchema>;
+/**
+ * Derives the transport mode solely from whether the event has response
+ * capabilities.
+ *
+ * Events with at least one response capability use `'request'` mode
+ * (blocking request/response), while events with an empty capabilities
+ * array use `'event'` mode (fire-and-forget).
+ * @param event - The parsed hook event declaration.
+ * @returns `'request'` when the event has response capabilities, `'event'` otherwise.
+ */
+declare function deriveHookEventTransportMode(event: ClientHookEventDeclaration): 'event' | 'request';
+/**
+ * Schema for the config isolation descriptor on a client definition.
+ *
+ * Describes the environment variable and default path the client binary uses
+ * for config isolation. Most clients accept a directory path. Some clients only
+ * expose a file-level override, so `pathKind` records which value shape the env
+ * var expects.
+ */
+declare const ConfigIsolationSchema: z.ZodObject<{
+  envVar: z.ZodString;
+  defaultPath: z.ZodString;
+  pathKind: z.ZodDefault<z.ZodEnum<{
+    file: "file";
+    directory: "directory";
+  }>>;
+}, z.core.$strip>;
+type ConfigIsolation = z.infer<typeof ConfigIsolationSchema>;
+/**
+ * Install descriptor for the `npm` strategy.
+ *
+ * The manager runs a sandboxed `npm install --prefix <targetDir>` for the
+ * pinned package version so managed installs do not mutate global npm state.
+ * An exact version pin is required; floating ranges are not accepted so the
+ * framework can reproduce the same binary across machines and time.
+ */
+declare const NpmInstallDescriptorSchema: z.ZodObject<{
+  type: z.ZodLiteral<"npm">;
+  package: z.ZodString;
+  version: z.ZodString;
+}, z.core.$strip>;
+type NpmInstallDescriptor = z.infer<typeof NpmInstallDescriptorSchema>;
+/**
+ * Install descriptor for the `signed-binary-bucket` strategy.
+ *
+ * The manager fetches a GPG-signed manifest from a versioned bucket path,
+ * verifies the manifest signature against the declared public key, selects the
+ * per-platform binary, downloads it, and verifies its checksum before
+ * activating the install.
+ *
+ * All bucket paths are Go-style templates: `{version}` is replaced with the
+ * resolved version string and `{platform}` / `{binary}` are replaced with the
+ * per-platform values from the `platforms` map.
+ */
+declare const SignedBinaryBucketInstallDescriptorSchema: z.ZodObject<{
+  type: z.ZodLiteral<"signed-binary-bucket">;
+  version: z.ZodString;
+  config: z.ZodObject<{
+    baseUrl: z.ZodString;
+    manifestPathTemplate: z.ZodString;
+    manifestSignaturePathTemplate: z.ZodString;
+    publicKeyUrl: z.ZodString;
+    publicKeyFingerprint: z.ZodString;
+    binaryPathTemplate: z.ZodString;
+    platforms: z.ZodRecord<z.ZodString, z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+type SignedBinaryBucketInstallDescriptor = z.infer<typeof SignedBinaryBucketInstallDescriptorSchema>;
+/**
+ * Discriminated union of all supported managed install descriptors.
+ *
+ * Two strategies are supported:
+ * - `npm`                  — npm registry installation with an exact version pin.
+ * - `signed-binary-bucket` — signed static bucket download with an exact version pin.
+ *
+ * The descriptor is purely declarative; no runtime logic lives here.
+ */
+declare const ManagedInstallDescriptorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"npm">;
+  package: z.ZodString;
+  version: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"signed-binary-bucket">;
+  version: z.ZodString;
+  config: z.ZodObject<{
+    baseUrl: z.ZodString;
+    manifestPathTemplate: z.ZodString;
+    manifestSignaturePathTemplate: z.ZodString;
+    publicKeyUrl: z.ZodString;
+    publicKeyFingerprint: z.ZodString;
+    binaryPathTemplate: z.ZodString;
+    platforms: z.ZodRecord<z.ZodString, z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+type ManagedInstallDescriptor = z.infer<typeof ManagedInstallDescriptorSchema>;
+/**
+ * Platform-aware command descriptor for querying the installed binary version.
+ *
+ * The `executable` field may be a single relative path string (used on all
+ * platforms) or a platform-keyed object that overrides the `default` executable
+ * on specific operating systems.
+ *
+ * All executable values are resolved relative to the managed install directory
+ * — absolute paths and parent-directory traversals (`..`) are rejected by the
+ * `ClientDefinitionSchema` refinement.
+ */
+declare const VersionCommandSchema: z.ZodObject<{
+  executable: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    default: z.ZodString;
+    darwin: z.ZodOptional<z.ZodString>;
+    linux: z.ZodOptional<z.ZodString>;
+    win32: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>]>;
+  args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type VersionCommand = z.infer<typeof VersionCommandSchema>;
+/**
+ * Optional post-install action descriptor.
+ *
+ * Carries an open-ended `kind` string so the runtime can dispatch to a
+ * registered post-install handler without the contracts layer enumerating
+ * every possible action.
+ */
+declare const PostInstallDescriptorSchema: z.ZodObject<{
+  kind: z.ZodString;
+  payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type PostInstallDescriptor = z.infer<typeof PostInstallDescriptorSchema>;
+/**
+ * Declarative runtime capability flags for a client package.
+ *
+ * These flags are static declarations contributed by the client package.
+ * They inform Makaio which observation and launch mechanisms the client
+ * supports so the framework can activate the appropriate producers and
+ * adapt its behaviour without runtime probing.
+ *
+ * All flags default to `false` so packages only need to opt in to what they
+ * actually support.
+ */
+declare const ClientRuntimeCapabilitiesSchema: z.ZodObject<{
+  supportsHooks: z.ZodDefault<z.ZodBoolean>;
+  supportsStatusline: z.ZodDefault<z.ZodBoolean>;
+  supportsSupervisorLaunch: z.ZodDefault<z.ZodBoolean>;
+  supportsManagedBinary: z.ZodDefault<z.ZodBoolean>;
+  hookEvents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    frameworkSubject: z.ZodOptional<z.ZodString>;
+    responseCapabilities: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+  }, z.core.$strict>>>;
+}, z.core.$strip>;
+type ClientRuntimeCapabilities = z.infer<typeof ClientRuntimeCapabilitiesSchema>;
+/**
+ * Binary compatibility descriptor for a client definition.
+ *
+ * Groups all binary-related compatibility information: the executable name
+ * used for PATH detection and the version range the framework supports.
+ */
+interface ClientBinaryCompatibility {
+  /** Binary name used for CLI detection (e.g. `'claude'` for the `claude` binary on `PATH`). */
+  readonly name: string;
+  /**
+   * npm semver range of supported binary versions
+   * (e.g. `'>=1.0.0'`, `'^2.0.0'`).
+   */
+  readonly supportedVersions: VersionRange;
+}
+/** Zod schema for {@link ClientBinaryCompatibility}. */
+declare const ClientBinaryCompatibilitySchema: z.ZodObject<{
+  name: z.ZodString;
+  supportedVersions: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Static definition for a Makaio client package.
+ *
+ * Each client package (e.g. `@makaio/client-claude-code`) exports exactly one
+ * `ClientDefinition` object. The bootstrap service discovers and seeds these
+ * definitions into the `clients` storage table on startup.
+ *
+ * Key fields:
+ * - `runtimeCapabilities` — capability flags (hooks, managed binary, etc.)
+ * - `managedInstall` — install descriptor when Makaio manages the binary.
+ * - `configIsolation` — env var and default path for config isolation.
+ *   Used by both managed and global binaries; see {@link ConfigIsolationSchema}.
+ */
+declare const ClientDefinitionSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  version: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  binary: z.ZodOptional<z.ZodObject<{
+    name: z.ZodString;
+    supportedVersions: z.ZodString;
+  }, z.core.$strict>>;
+  nativeTools: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    friendlyName: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      tag: z.ZodString;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>>;
+  defaultApprovalPolicy: z.ZodEnum<{
+    reject: "reject";
+    "always-ask": "always-ask";
+    "full-access": "full-access";
+  }>;
+  logSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  authMethods: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodLiteral<"explicit">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    fields: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      label: z.ZodString;
+      description: z.ZodOptional<z.ZodString>;
+      required: z.ZodBoolean;
+      secret: z.ZodBoolean;
+      sourceHints: z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"environment">;
+        variable: z.ZodString;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodLiteral<"inferred">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodLiteral<"none">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>], "mode">>;
+  defaultAuth: z.ZodOptional<z.ZodObject<{
+    providerDefinitionId: z.ZodString;
+    methodId: z.ZodString;
+  }, z.core.$strict>>;
+  runtimeCapabilities: z.ZodPipe<z.ZodOptional<z.ZodObject<{
+    supportsHooks: z.ZodDefault<z.ZodBoolean>;
+    supportsStatusline: z.ZodDefault<z.ZodBoolean>;
+    supportsSupervisorLaunch: z.ZodDefault<z.ZodBoolean>;
+    supportsManagedBinary: z.ZodDefault<z.ZodBoolean>;
+    hookEvents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      frameworkSubject: z.ZodOptional<z.ZodString>;
+      responseCapabilities: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>>;
+  }, z.core.$strip>>, z.ZodTransform<{
+    supportsHooks: boolean;
+    supportsStatusline: boolean;
+    supportsSupervisorLaunch: boolean;
+    supportsManagedBinary: boolean;
+    hookEvents: {
+      name: string;
+      responseCapabilities: readonly string[];
+      frameworkSubject?: string | undefined;
+    }[];
+  }, {
+    supportsHooks: boolean;
+    supportsStatusline: boolean;
+    supportsSupervisorLaunch: boolean;
+    supportsManagedBinary: boolean;
+    hookEvents: {
+      name: string;
+      responseCapabilities: readonly string[];
+      frameworkSubject?: string | undefined;
+    }[];
+  } | undefined>>;
+  managedInstall: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"npm">;
+    package: z.ZodString;
+    version: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"signed-binary-bucket">;
+    version: z.ZodString;
+    config: z.ZodObject<{
+      baseUrl: z.ZodString;
+      manifestPathTemplate: z.ZodString;
+      manifestSignaturePathTemplate: z.ZodString;
+      publicKeyUrl: z.ZodString;
+      publicKeyFingerprint: z.ZodString;
+      binaryPathTemplate: z.ZodString;
+      platforms: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+  }, z.core.$strip>], "type">>;
+  versionCommand: z.ZodOptional<z.ZodObject<{
+    executable: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      default: z.ZodString;
+      darwin: z.ZodOptional<z.ZodString>;
+      linux: z.ZodOptional<z.ZodString>;
+      win32: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>;
+  postInstall: z.ZodOptional<z.ZodObject<{
+    kind: z.ZodString;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+  configIsolation: z.ZodOptional<z.ZodObject<{
+    envVar: z.ZodString;
+    defaultPath: z.ZodString;
+    pathKind: z.ZodDefault<z.ZodEnum<{
+      file: "file";
+      directory: "directory";
+    }>>;
+  }, z.core.$strip>>;
+}, z.core.$strict>;
+type ClientDefinitionInput = z.input<typeof ClientDefinitionSchema>;
+type ClientDefinition = z.infer<typeof ClientDefinitionSchema>;
+//#endregion
+//#region core/contracts/src/client/hook-responses.d.ts
+/**
+ * Client hook response contribution contracts.
+ *
+ * Defines the two typed contribution lanes that extensions use to respond to
+ * client hook events:
+ *
+ * 1. **Canonical effects** — portable, provider-agnostic effects like
+ *    `context.append` that any extension can contribute without knowing the
+ *    active provider.
+ *
+ * 2. **Provider contribution envelopes** — opaque containers keyed by
+ *    `clientId` and `contractId` that only provider-owned typed builders can
+ *    fill with provider-specific effects.
+ *
+ * Extensions declare contributors via
+ * {@link MakaioExtension.clientHookResponses}, which supplies a
+ * {@link ContributorActivationContext} and returns
+ * {@link ContributorDefinition} instances validated at activation time.
+ * @packageDocumentation
+ */
+/**
+ * A canonical `context.append` effect — a simple string-append that works
+ * across all providers.
+ *
+ * This is the minimum portable contribution any extension can make. The
+ * runtime appends the value to the hook event's context payload without
+ * provider-specific serialization.
+ */
+interface CanonicalAppendEffect {
+  /** Discriminant identifying this as a canonical append effect. */
+  readonly kind: 'context.append';
+  /** The string value to append to the hook event context. */
+  readonly value: string;
+}
+/**
+ * Union of all canonical effects.
+ *
+ * Currently contains only `context.append`. New canonical effects are added
+ * to this union as the framework evolves.
+ */
+type CanonicalEffect = CanonicalAppendEffect;
+/**
+ * Create a canonical `context.append` effect.
+ * @param value - The string value to append.
+ * @returns A frozen {@link CanonicalAppendEffect}.
+ */
+declare function createAppendEffect(value: string): CanonicalAppendEffect;
+/**
+ * Opaque provider contribution envelope keyed by client and contract identity.
+ *
+ * Contracts defines the shape; providers fill it via typed builders (not
+ * defined in this file). The `effects` record is intentionally typed as
+ * `Record<string, unknown>` — concrete effect shapes are constructible only
+ * through provider-owned builders that narrow the generic at build time.
+ * @typeParam TEffects - Concrete effects record type, narrowed by
+ *   provider-owned builders. Defaults to `Record<string, unknown>` for
+ *   contract-level usage.
+ */
+interface ProviderContributionEnvelope<TEffects extends Record<string, unknown> = Record<string, unknown>> {
+  /** Client identifier this contribution targets (e.g. `'claude-code'`). */
+  readonly clientId: string;
+  /**
+   * Versioned contract identifier from the provider contract catalog
+   * (e.g. `'anthropic.tool-response@1'`).
+   */
+  readonly contractId: string;
+  /** Provider-specific effects, opaque at the contracts layer. */
+  readonly effects: TEffects;
+}
+/**
+ * Blockability metadata for a single interaction within a provider contract.
+ *
+ * Used at activation time to validate whether a contributor may declare
+ * `failurePolicy: 'closed'` for a given interaction.
+ */
+interface InteractionBlockability {
+  /** Interaction name (matches hook event name or capability). */
+  readonly interaction: string;
+  /**
+   * Whether this interaction can block or deny execution.
+   *
+   * When `false`, contributors must not declare `failurePolicy: 'closed'`
+   * for this interaction — doing so is an activation-time validation error.
+   */
+  readonly blockable: boolean;
+}
+/**
+ * Generic interface for provider contract catalog entries.
+ *
+ * Used by clients-core to register provider contracts. Concrete effect
+ * schemas live in provider packages, not here.
+ * @typeParam TValidationContext - Context type passed to the validation
+ *   hook. Defaults to `Record<string, unknown>` for contract-level usage.
+ */
+interface ProviderContractCatalogEntry<TValidationContext extends Record<string, unknown> = Record<string, unknown>> {
+  /** Client identifier this contract targets (e.g. `'claude-code'`). */
+  readonly clientId: string;
+  /** Stable contract identifier (e.g. `'anthropic.tool-response'`). */
+  readonly contractId: string;
+  /** Semantic version of the contract (e.g. `'1.0.0'`). */
+  readonly version: string;
+  /** Interactions this contract supports. */
+  readonly supportedInteractions: readonly string[];
+  /** Blockability metadata for each supported interaction. */
+  readonly blockability: readonly InteractionBlockability[];
+  /**
+   * Runtime validation hook called to validate contributor callback output
+   * against this contract's schema.
+   *
+   * Returns `true` when the output is valid, or a string describing the
+   * validation error. Every provider contract must supply a validator so
+   * native output is never accepted unchecked at runtime.
+   * @param output - The callback output to validate.
+   * @param ctx - Provider-specific validation context.
+   * @returns `true` on success, or an error description string.
+   */
+  readonly validate: (output: unknown, ctx: TValidationContext) => true | string;
+}
+/**
+ * Selector that matches hook events by event name.
+ */
+interface EventNameSelector {
+  /** Discriminant identifying this as an event-name selector. */
+  readonly kind: 'event-name';
+  /** Hook event name to match (e.g. `'PreToolUse'`). */
+  readonly name: string;
+}
+/**
+ * Selector that matches hook events by response capability.
+ */
+interface CapabilitySelector {
+  /** Discriminant identifying this as a capability selector. */
+  readonly kind: 'capability';
+  /** Response capability to match (e.g. `'context.append'`). */
+  readonly capability: string;
+}
+/**
+ * Union of interaction selectors that determine which hook events a
+ * contributor responds to.
+ */
+type InteractionSelector = EventNameSelector | CapabilitySelector;
+/**
+ * Context supplied to a contributor's callback when a matching hook event
+ * fires.
+ *
+ * Provides deadline-aware execution metadata and an abort signal for
+ * cooperative cancellation.
+ */
+interface ContributorCallbackContext {
+  /** Client receiving the hook event. */
+  readonly clientId: string;
+  /**
+   * Absolute deadline timestamp (epoch milliseconds) by which the callback
+   * must complete.
+   */
+  readonly deadline: number;
+  /**
+   * Remaining time budget in milliseconds, computed from the deadline at
+   * context creation time.
+   *
+   * Consumers should treat this as an approximate upper bound — actual
+   * remaining time decreases as the callback executes.
+   */
+  readonly remainingBudgetMs: number;
+  /**
+   * Abort signal that fires when the deadline is reached or the hook
+   * invocation is cancelled by the runtime.
+   */
+  readonly signal: AbortSignal;
+  /** The hook event name that triggered this callback. */
+  readonly eventName: string;
+  /** The hook event payload, opaque at the contracts layer. */
+  readonly eventPayload: unknown;
+}
+/**
+ * Failure policy determining how the runtime handles contributor failures.
+ *
+ * - `'open'` — on failure (timeout, rejection, error), omit this
+ *   contributor's result and record the failure, but do not block the
+ *   overall hook event response. This is the default.
+ * - `'closed'` — on failure, discard all contributor results for this
+ *   hook event and render a blocking response. Only valid for interactions
+ *   whose provider contract declares the interaction as blockable.
+ */
+type FailurePolicy = 'open' | 'closed';
+/** Default failure policy applied when none is specified. */
+declare const DEFAULT_FAILURE_POLICY: FailurePolicy;
+/**
+ * Contributor definition declared by an extension via
+ * {@link MakaioExtension.clientHookResponses}.
+ *
+ * Each contributor represents a single extension callback that responds to
+ * matching hook events with canonical or provider-specific effects.
+ */
+interface ContributorDefinitionBase {
+  /**
+   * Unique contributor identifier, namespaced by extension.
+   *
+   * Must be a non-empty string. The runtime prefixes this with the extension
+   * name during registration to ensure global uniqueness.
+   */
+  readonly id: string;
+  /**
+   * Priority determining execution order. Higher values execute earlier in
+   * the reduction pipeline.
+   */
+  readonly priority: number;
+  /**
+   * Callback timeout in milliseconds. Must be a positive number.
+   *
+   * When the callback exceeds this timeout, the failure policy determines
+   * the outcome.
+   */
+  readonly timeoutMs: number;
+  /**
+   * Failure policy for this contributor.
+   *
+   * Defaults to `'open'` when omitted. `'closed'` is only valid for
+   * interactions whose provider contract declares the interaction as
+   * blockable; this is validated at activation time.
+   * @defaultValue `'open'`
+   */
+  readonly failurePolicy?: FailurePolicy;
+  /**
+   * Interaction selectors determining which hook events this contributor
+   * responds to.
+   *
+   * At least one selector must be provided. A contributor is invoked when
+   * any selector matches the incoming hook event.
+   */
+  readonly selectors: readonly [InteractionSelector, ...InteractionSelector[]];
+  /**
+   * Contributor callback invoked when a matching hook event fires.
+   *
+   * Returns effects for this contributor's declared lane.
+   * Returning `undefined` or an empty result is a valid no-op.
+   * @param ctx - Deadline-aware callback context.
+   * @returns Contribution result, `undefined` for a no-op, or a promise
+   *   resolving to either.
+   */
+  readonly respond: (ctx: ContributorCallbackContext) => ContributorResponse | undefined | Promise<ContributorResponse | undefined>;
+}
+/**
+ * Portable contributor lane.
+ *
+ * Canonical contributors produce provider-agnostic effects. When `clientIds`
+ * is omitted, they are eligible for every active client; otherwise they are
+ * eligible only for the listed clients.
+ */
+interface CanonicalContributorDefinition extends ContributorDefinitionBase {
+  /** Discriminant selecting the portable canonical lane. */
+  readonly lane: 'canonical';
+  /** Optional client allow-list for this portable contributor. */
+  readonly clientIds?: readonly string[];
+}
+/**
+ * Provider-specific contributor lane.
+ *
+ * Provider contributors are eligible only for the exact client and contract
+ * pair declared here.
+ */
+interface ProviderContributorDefinition extends ContributorDefinitionBase {
+  /** Discriminant selecting the provider-specific lane. */
+  readonly lane: 'provider';
+  /** Exact client this provider contribution targets. */
+  readonly clientId: string;
+  /** Exact active provider contract this contribution targets. */
+  readonly contractId: string;
+}
+/**
+ * Contributor definition declared by an extension.
+ *
+ * The lane discriminant makes client targeting explicit: portable canonical
+ * contributors may target multiple clients, while provider contributors are
+ * bound to one exact provider contract.
+ */
+type ContributorDefinition = CanonicalContributorDefinition | ProviderContributorDefinition;
+/**
+ * Response returned by a contributor callback.
+ *
+ * A contributor may produce canonical effects, a provider envelope, or a
+ * no-op. The runtime rejects responses that mix the two lanes.
+ */
+interface ContributorResponse {
+  /** Canonical effects to apply, if any. */
+  readonly canonicalEffects?: readonly CanonicalEffect[];
+  /** Provider-specific contribution envelope, if any. */
+  readonly providerEnvelope?: ProviderContributionEnvelope;
+}
+/**
+ * Context supplied to the `createContributors` factory during extension
+ * activation.
+ *
+ * Provides the extension identity and a lookup for active provider contracts
+ * so the factory can validate contributor selectors and failure policies.
+ */
+interface ContributorActivationContext {
+  /** Name of the activating extension. */
+  readonly extensionName: string;
+  /**
+   * Look up a provider contract catalog entry by its exact client and
+   * contract identifiers.
+   * @param clientId - Client identifier that owns the contract.
+   * @param contractId - The contract ID to look up.
+   * @returns The catalog entry, or `undefined` when no matching contract is registered.
+   */
+  readonly getProviderContract: (clientId: string, contractId: string) => ProviderContractCatalogEntry | undefined;
+}
+/**
+ * Client hook response contribution surface declared by an extension.
+ *
+ * Added to {@link MakaioExtension.clientHookResponses}. The runtime calls
+ * `createContributors` once during extension activation; the returned batch
+ * is validated before installation.
+ */
+interface ExtensionClientHookResponsesContribution {
+  /**
+   * Factory that produces contributor definitions for this extension.
+   *
+   * Called once during extension activation. The returned contributors are
+   * validated against the active provider contract catalog before being
+   * installed in the hook response pipeline.
+   * @param ctx - Activation context supplying extension identity and
+   *   provider contract lookup.
+   * @returns Contributor definitions or a promise resolving to them.
+   */
+  readonly createContributors: (ctx: ContributorActivationContext) => ContributorDefinition[] | Promise<ContributorDefinition[]>;
+}
+/**
+ * Activation-time validation error codes.
+ *
+ * These errors are detected when validating contributor definitions during
+ * extension activation, before any runtime hook event is fired.
+ */
+type ActivationErrorCode = /** Contributor ID is empty or otherwise invalid. */'invalid-contributor-id' /** Contributor timeout value is non-positive, non-finite, or otherwise invalid. */ | 'invalid-timeout-ms' /** Contributor priority is not a finite number. */ | 'invalid-priority' /** Contributor lane or its target identity is invalid. */ | 'invalid-contributor-lane' /** Contributor selectors are missing or malformed. */ | 'invalid-selectors' /** Contributor callback is not callable. */ | 'invalid-respond' /** The referenced provider contract is not registered or not active. */ | 'inactive-provider-contract' /** A selector references an interaction not supported by the provider contract. */ | 'unsupported-interaction'
+/**
+ * A contributor declares `failurePolicy: 'closed'` for an interaction
+ * that is not blockable according to the provider contract catalog.
+ */
+| 'closed-policy-on-non-blockable';
+/**
+ * Activation-time validation error raised when a contributor definition
+ * fails validation during extension activation.
+ */
+interface ActivationValidationError {
+  /** Error code identifying the class of validation failure. */
+  readonly code: ActivationErrorCode;
+  /** Human-readable error message. */
+  readonly message: string;
+  /** Contributor ID that caused the error, when available. */
+  readonly contributorId?: string;
+  /** Extension name that owns the contributor. */
+  readonly extensionName: string;
+}
+/**
+ * Runtime outcome codes for contributor callback execution.
+ *
+ * These outcomes are recorded after a hook event fires and a contributor
+ * callback completes (or fails to complete).
+ */
+type RuntimeOutcomeCode = /** The callback completed within the deadline and returned a valid response. */'success' /** The callback exceeded its timeout. */ | 'timeout' /** The callback threw an error or returned an invalid response. */ | 'rejection'
+/**
+ * Closed failure: all contributors' results for this hook event are
+ * discarded, and a blocking response is rendered.
+ */
+| 'closed-failure';
+/**
+ * Runtime outcome record for a single contributor callback execution.
+ */
+interface RuntimeOutcome {
+  /** Outcome code. */
+  readonly code: RuntimeOutcomeCode;
+  /** Contributor ID that produced this outcome. */
+  readonly contributorId: string;
+  /** Human-readable detail message, if any. */
+  readonly detail?: string;
+  /** Duration of the callback execution in milliseconds. */
+  readonly durationMs?: number;
+}
+/**
+ * Validate that a contributor definition has a non-empty ID.
+ * @param id - The contributor ID to validate.
+ * @returns `true` when the ID is a non-empty string.
+ */
+declare function isValidContributorId(id: string): boolean;
+/**
+ * Validate that a timeout value is a positive finite number.
+ * @param timeoutMs - The timeout in milliseconds.
+ * @returns `true` when the timeout is positive and finite.
+ */
+declare function isValidTimeoutMs(timeoutMs: number): boolean;
+/**
+ * Validate that a `failurePolicy: 'closed'` declaration is permitted for
+ * the given interaction selectors against a provider contract catalog entry.
+ *
+ * For each selector, the function first verifies that the interaction is
+ * listed in the catalog's `supportedInteractions`. If it is not, an
+ * "unsupported interaction" error is produced instead of the more specific
+ * "not blockable" error — this avoids misleading diagnostics when the
+ * interaction simply does not exist in the contract.
+ *
+ * Returns an array of validation errors. An empty array means the policy
+ * is valid.
+ * @param selectors - The contributor's interaction selectors.
+ * @param catalog - The provider contract catalog entry to validate against.
+ * @returns Array of validation error messages; empty when valid.
+ */
+declare function validateClosedPolicy(selectors: readonly InteractionSelector[], catalog: ProviderContractCatalogEntry): string[];
+//#endregion
+export { VersionLiteralSchema as $, ClientHookEventDeclarationSchema as A, LogSourceDefinitionSchema as B, validateClosedPolicy as C, ClientDefinitionInput as D, ClientDefinition as E, ClientToolDefinition as F, PostInstallDescriptor as G, ManagedInstallDescriptorSchema as H, ClientToolDefinitionSchema as I, SignedBinaryBucketInstallDescriptorSchema as J, PostInstallDescriptorSchema as K, ConfigIsolation as L, ClientRuntimeCapabilitiesSchema as M, ClientToolCapabilityAnnotation as N, ClientDefinitionSchema as O, ClientToolCapabilityAnnotationSchema as P, VersionLiteral as Q, ConfigIsolationSchema as R, isValidTimeoutMs as S, ClientBinaryCompatibilitySchema as T, NpmInstallDescriptor as U, ManagedInstallDescriptor as V, NpmInstallDescriptorSchema as W, VersionCommandSchema as X, VersionCommand as Y, deriveHookEventTransportMode as Z, ProviderContributionEnvelope as _, CapabilitySelector as a, createAppendEffect as b, ContributorDefinition as c, EventNameSelector as d, VersionRange as et, ExtensionClientHookResponsesContribution as f, ProviderContractCatalogEntry as g, InteractionSelector as h, CanonicalEffect as i, ClientRuntimeCapabilities as j, ClientHookEventDeclaration as k, ContributorResponse as l, InteractionBlockability as m, ActivationValidationError as n, isUniversalRange as nt, ContributorActivationContext as o, FailurePolicy as p, SignedBinaryBucketInstallDescriptor as q, CanonicalAppendEffect as r, versionSatisfies as rt, ContributorCallbackContext as s, ActivationErrorCode as t, VersionRangeSchema as tt, DEFAULT_FAILURE_POLICY as u, RuntimeOutcome as v, ClientBinaryCompatibility as w, isValidContributorId as x, RuntimeOutcomeCode as y, LogSourceDefinition as z };