@makaio/framework 1.0.0-dev-1789404058608 → 1.0.0-dev-1789642522820

package/dist/client-DqfP7BeX.mjs

@@ -0,0 +1 @@
+import{o as e,s as t}from"./definitions-Do7bP-u7.mjs";import{t as n}from"./schemas-BmoFWBdh.mjs";import{_ as r,a as i,g as a,h as o,m as s,n as ee,o as te}from"./profile-1fvMljlJ.mjs";import{n as ne,t as c}from"./version-PuU2KG3I.mjs";import{c as re,d as ie,n as ae,o as oe,s as se,t as ce,u as le}from"./account-identity-C-v4mHq3.mjs";import{z as l}from"zod";import{createBusNamespace as ue,observability as u}from"@makaio/framework/core";const d=l.object({tag:l.string(),description:l.string().optional()}),f=l.object({name:l.string(),friendlyName:l.string(),description:l.string().optional(),category:l.string().optional(),capabilities:l.array(d).default([])}),de=l.object({id:l.string(),name:l.string(),description:l.string().optional(),glob:l.string().optional()}),p=l.object({name:l.string().min(1),frameworkSubject:l.string().min(1).optional(),responseCapabilities:l.array(l.string().min(1)).readonly().default([]),minimumVersion:c.optional()}).strict();function fe(e){return e.responseCapabilities.length>0?`request`:`event`}const m=l.object({envVar:a.regex(/^[A-Za-z_][A-Za-z0-9_]*$/,{message:`envVar must be a valid environment variable name (letters, digits, underscores)`}),defaultPath:a.refine(e=>e===`~`||e.startsWith(`~/`)||r(e),{message:`defaultPath must be absolute, '~', or start with '~/'`}),pathKind:l.enum([`directory`,`file`]).default(`directory`)});function pe(e){if(!e.startsWith(`@`))return!e.includes(`@`);let t=e.indexOf(`/`);return t>1&&!e.slice(t+1).includes(`@`)}const h=l.object({type:l.literal(`npm`),package:l.string().min(1).refine(pe,{message:"package must not include an inline `@version` suffix; use the version field instead"}),version:c}),g=l.object({type:l.literal(`signed-binary-bucket`),version:c,config:l.object({baseUrl:l.string().url(),manifestPathTemplate:l.string().min(1),manifestSignaturePathTemplate:l.string().min(1),publicKeyUrl:l.string().url(),publicKeyFingerprint:l.string().min(1),binaryPathTemplate:l.string().min(1),platforms:l.record(l.string().min(1),l.string().min(1))})}),_=l.discriminatedUnion(`type`,[h,g]),v=l.object({executable:l.union([l.string().min(1),l.object({default:l.string().min(1),darwin:l.string().min(1).optional(),linux:l.string().min(1).optional(),win32:l.string().min(1).optional()}).strict()]),args:l.array(l.string()).default([])}).strict(),y=l.object({kind:l.string().min(1),payload:l.record(l.string(),l.unknown()).optional()}),b=l.object({supportsHooks:l.boolean().default(!1),supportsStatusline:l.boolean().default(!1),supportsSupervisorLaunch:l.boolean().default(!1),supportsManagedBinary:l.boolean().default(!1),hookEvents:l.array(p).default([])}).refine(e=>e.supportsHooks||e.hookEvents.length===0,{message:`hookEvents must be empty when supportsHooks is false`,path:[`hookEvents`]}),x=l.object({name:l.string().min(1),supportedVersions:ne}).strict(),S=l.object({id:l.string(),name:l.string(),version:c,description:l.string().optional(),binary:x.optional(),nativeTools:l.array(f).default([]),defaultApprovalPolicy:n,logSources:l.array(de).optional(),authMethods:e,defaultAuth:t.optional(),runtimeCapabilities:b.optional().transform(e=>b.parse(e??{})),managedInstall:_.optional(),versionCommand:v.optional(),postInstall:y.optional(),configIsolation:m.optional()}).strict().refine(e=>!e.runtimeCapabilities.supportsManagedBinary||e.managedInstall!==void 0,{message:`managedInstall is required when runtimeCapabilities.supportsManagedBinary is true`,path:[`managedInstall`]}).refine(e=>e.managedInstall===void 0||e.runtimeCapabilities.supportsManagedBinary,{message:`runtimeCapabilities.supportsManagedBinary must be true when managedInstall is provided`,path:[`runtimeCapabilities`,`supportsManagedBinary`]}).refine(e=>e.managedInstall===void 0||e.versionCommand!==void 0,{message:`versionCommand is required when managedInstall is provided`,path:[`versionCommand`]}).superRefine((e,t)=>{e.defaultAuth!==void 0&&e.authMethods.find(({id:t})=>t===e.defaultAuth?.methodId)?.mode!==`inferred`&&t.addIssue({code:l.ZodIssueCode.custom,message:`defaultAuth.methodId must reference an inferred method declared by this client.`,path:[`defaultAuth`,`methodId`]})}).superRefine((e,t)=>{if(e.managedInstall===void 0||e.versionCommand===void 0)return;let{executable:n}=e.versionCommand,r=typeof n==`string`?[{path:n,issuePath:[`versionCommand`,`executable`]}]:[{path:n.default,issuePath:[`versionCommand`,`executable`,`default`]},...n.darwin===void 0?[]:[{path:n.darwin,issuePath:[`versionCommand`,`executable`,`darwin`]}],...n.linux===void 0?[]:[{path:n.linux,issuePath:[`versionCommand`,`executable`,`linux`]}],...n.win32===void 0?[]:[{path:n.win32,issuePath:[`versionCommand`,`executable`,`win32`]}]];for(let{path:e,issuePath:n}of r){let r=e.startsWith(`/`),i=/^[A-Za-z]:/.test(e),a=e.startsWith(`\\`);if(r||i||a){t.addIssue({code:l.ZodIssueCode.custom,path:n,message:`${n.join(`.`)} must be a relative path within the install directory`});continue}e.split(/[/\\]/).some(e=>e===`..`)&&t.addIssue({code:l.ZodIssueCode.custom,path:n,message:`${n.join(`.`)} must be a relative path within the install directory`})}}),C=l.object({binaryPath:s.nullable(),env:l.record(l.string(),l.string()),configDir:s.nullable(),source:l.enum([`managed`,`global`]),version:a.nullable()}),w={request:l.object({clientId:a,sessionId:a.optional(),projectDir:s.optional(),preferSource:l.enum([`managed`,`global`]).optional(),harnessId:a.optional()}),response:C},T=l.enum([`npm`,`signed-binary-bucket`]),E=l.object({version:a,installPath:s,installedAt:o,isActive:l.boolean()}),D=l.object({clientId:a,installedVersions:l.array(E),activeVersion:a.nullable(),pinnedVersion:c,updateAvailable:l.boolean()}).strict(),O={request:l.object({forceRefresh:l.boolean().optional()}),response:l.object({clients:l.array(D)})},k={request:l.object({clientId:a,version:c.optional()}),response:l.object({jobId:a,requestedVersion:c.nullable(),resolvedVersion:c.nullable()})},A={request:l.object({clientId:a,version:a}),response:l.object({clientId:a,removedVersion:a,activeVersion:a.nullable()})},j={request:l.object({clientId:a}),response:l.object({jobId:a,resolvedVersion:c.nullable()})},M={request:l.object({clientId:a,version:a}),response:l.object({clientId:a,activeVersion:a})},N=l.enum([`resolving`,`downloading`,`verifying`,`extracting`,`installing`,`post-install`,`activating`]),P=l.object({jobId:a,clientId:a,version:a.optional(),strategy:T,stage:N,progress:l.number().min(0).max(100).nullable(),installPath:s.optional(),activeAfterCompletion:l.boolean().optional(),metadata:l.record(l.string(),l.unknown()).optional()}),F=l.object({message:l.string(),code:l.string().optional()}),I=l.object({jobId:a,clientId:a,version:a.optional(),strategy:T,status:l.enum([`success`,`error`]),installPath:s.optional(),activeVersion:a.nullable(),error:F.optional(),metadata:l.record(l.string(),l.unknown()).optional()}),L=l.object({clientId:a,previousActiveVersion:a.nullable(),activeVersion:a.nullable(),reason:l.enum([`install`,`update`,`set-active`,`uninstall`])}),R=l.enum([`supervisor`,`adapter`,`client-hook`,`statusline`,`cli-wrapper`]),z=l.object({layer:R,producer:a}),B=l.object({supervisorSessionId:a.optional(),pid:l.number().int().positive().optional(),parentPid:l.number().int().positive().optional(),adapterSessionId:a.optional(),sessionId:a.optional(),cwd:l.string().optional(),argv:l.array(l.string()).optional(),metadata:l.record(l.string(),l.unknown()).optional()}),V={request:l.object({clientId:a,source:z,observedAt:o}).merge(B).refine(e=>e.supervisorSessionId!==void 0||e.pid!==void 0||e.adapterSessionId!==void 0,{message:`At least one hard-evidence field is required (supervisorSessionId, pid, or adapterSessionId)`}),response:l.object({clientRuntimeId:a,created:l.boolean(),promoted:l.boolean()})},H=B.extend({clientRuntimeId:a,clientId:a,status:l.enum([`observed`,`started`]),source:z,observedAt:o}),U={request:l.object({adapterSessionId:a,clientId:a}),response:l.object({managed:l.boolean()})},W=l.object({clientId:u.attribute(a,`makaio.client.id`),source:u.attribute(a,`makaio.client.lifecycle.source`),observedAt:u.attribute(o,`event.observed_at`),sessionId:u.attribute(l.string(),`makaio.session.id`).optional(),adapterSessionId:u.attribute(l.string(),`makaio.adapter.session_id`).optional(),metadata:l.record(l.string(),l.unknown()).optional()}),G=[`fresh`,`fork`,`resume`,`clear`,`compact`],K=l.enum(G),q=W.extend({transcriptPath:l.string().optional(),cwd:l.string().optional(),machineId:u.attribute(l.string(),`makaio.machine.id`).optional(),startMode:u.attribute(K,`makaio.session.start_mode`).optional(),parentAdapterSessionId:u.attribute(l.string(),`makaio.session.parent_adapter_session_id`).optional()}),J=W.extend({prompt:a.optional()}),me=W.extend({}),he=W.extend({transcriptPath:l.string().optional()}),ge=W.extend({toolName:u.attribute(a,`tool.name`).optional(),toolCallId:u.attribute(a,`tool.call_id`).optional()}),_e=W.extend({toolName:u.attribute(a,`tool.name`).optional(),toolCallId:u.attribute(a,`tool.call_id`).optional(),success:u.attribute(l.boolean(),`tool.success`).optional()}),ve=[`manual`,`auto`],ye=l.enum(ve),be=W.extend({trigger:u.attribute(ye,`makaio.session.compaction_trigger`).optional(),transcriptPath:l.string().optional()}),Y=W.extend({agentId:u.attribute(a,`makaio.client.agent_id`),agentType:u.attribute(a,`makaio.client.agent_type`).optional(),turnId:u.attribute(a,`makaio.client.turn_id`).optional()}),xe=Y.extend({agentTranscriptPath:l.string().optional()}),Se=l.object({group:a,name:a,installed:l.boolean(),command:a}),Ce=l.enum([`provider-reported`,`client-reported`,`estimated`]),X=l.number().finite().nonnegative(),we=l.number().finite().min(0).max(100),Te=l.object({clientId:u.attribute(a,`makaio.client.id`),clientAccountId:u.attribute(a,`makaio.client.account_id`).optional(),sessionId:u.attribute(a,`makaio.session.id`).optional(),adapterSessionId:u.attribute(a,`makaio.adapter.session_id`).optional(),source:u.attribute(a,`makaio.client.usage.source`),observedAt:u.attribute(o,`event.observed_at`),clientVersion:u.attribute(a,`makaio.client.version`).optional(),modelId:u.attribute(a,`llm.model`).optional(),modelDisplayName:u.attribute(a,`llm.model.display_name`).optional(),modelFamily:u.attribute(a,`llm.model.family`).optional(),latestRequestInputTokens:u.attribute(X,`llm.tokens.latest_request.input`).optional(),latestRequestOutputTokens:u.attribute(X,`llm.tokens.latest_request.output`).optional(),latestRequestCacheReadTokens:u.attribute(X,`llm.tokens.latest_request.cache_read`).optional(),latestRequestCacheWriteTokens:u.attribute(X,`llm.tokens.latest_request.cache_write`).optional(),currentContextInputTokens:u.attribute(X,`llm.context.tokens.input`).optional(),currentContextOutputTokens:u.attribute(X,`llm.context.tokens.output`).optional(),contextWindowSizeTokens:u.attribute(X,`llm.context.window_size`).optional(),contextUsedPercentage:u.attribute(we,`llm.context.used_percentage`).optional(),contextRemainingPercentage:u.attribute(we,`llm.context.remaining_percentage`).optional(),contextThresholdExceeded:u.attribute(l.boolean(),`llm.context.threshold_exceeded`).optional(),totalCost:u.attribute(X,`llm.cost.total`).optional(),costCurrency:u.attribute(a,`llm.cost.currency`).optional(),costProvenance:u.attribute(Ce,`llm.cost.provenance`).optional(),totalDurationMs:u.attribute(X,`makaio.session.duration_ms`).optional(),totalApiDurationMs:u.attribute(X,`llm.duration.total_api_ms`).optional(),totalLinesAdded:u.attribute(X,`code.lines_added`).optional(),totalLinesRemoved:u.attribute(X,`code.lines_removed`).optional(),totalEdits:u.attribute(X,`code.edits`).optional()}).strict().superRefine((e,t)=>{let n=[`totalCost`,`costCurrency`,`costProvenance`],r=n.filter(t=>e[t]!==void 0).length;if(!(r===0||r===n.length))for(let r of n)e[r]===void 0&&t.addIssue({code:l.ZodIssueCode.custom,path:[r],message:`totalCost, costCurrency, and costProvenance must be supplied together`})}),Z=l.object({clientId:l.string().min(1),adapterSessionId:l.string().min(1),agentId:l.string().min(1).optional()}),Ee=Z,De=l.object({token:l.string().nullable()}),Oe={"runtime.observe":V,"runtime.started":H,"runtime.isAdapterManaged":U,scan:{request:l.object({targets:l.array(se).optional()}),response:l.object({results:l.array(oe)})},"session.account.observe":re,"account.observe":ae,"account.activate":{request:l.object({clientId:a,clientAccountId:a,identifiers:l.array(ce).min(1),displayLabel:l.string().optional()}),response:l.object({accepted:l.boolean()})},"account.getActive":{request:l.object({clientId:a}),response:l.object({identity:l.object({clientAccountId:a,identifiers:l.array(ce).min(1),displayLabel:l.string().optional()}).nullable()})},"usage.ingest":le,"usage.snapshot":ie,"session.usage.snapshot":Te,"session.started":q,"session.userPrompt.submitted":J,"session.turn.started":me,"session.turn.completed":he,"session.tool.pre":ge,"session.tool.post":_e,"session.compaction.pre":be,"session.subagent.started":Y,"session.subagent.completed":xe,"session.token.get":{request:Ee,response:De},"wiring.list":{request:l.object({clientId:a.optional(),projectDir:s.optional(),makaioCommand:a}),response:l.object({results:l.array(l.object({clientId:a,entries:l.array(Se)}))})},list:O,install:k,uninstall:A,update:j,setActive:M,"installJob.progress":P,"installJob.completed":I,"version.changed":L,resolveBinary:w,...i,...te,"config.prime":ee},Q=ue(`client`,Oe),ke=Q.subjects;function $(e){if(Array.isArray(e)){for(let t of e)$(t);return Object.freeze(e)}if(e&&typeof e==`object`){for(let t of Object.values(e))$(t);return Object.freeze(e)}return e}function Ae(e){return $(S.parse(e))}const je=Object.freeze({contextAppend:`context.append`,sessionToken:`session.token`});function Me(e){return Object.freeze({kind:`context.append`,value:e})}function Ne(e){return Object.freeze({kind:`session.token`,value:e})}const Pe=`open`;function Fe(e){return typeof e==`string`&&e.trim().length>0}function Ie(e){return typeof e==`number`&&Number.isFinite(e)&&e>0}function Le(e,t){let n=[];for(let r of e){let e=r.kind===`event-name`?r.name:r.capability;if(!t.supportedInteractions.includes(e)){n.push(`Interaction '${e}' is not a supported interaction in contract '${t.contractId}'; failurePolicy 'closed' is not permitted`);continue}let i=t.blockability.find(t=>t.interaction===e);(!i||!i.blockable)&&n.push(`Interaction '${e}' is not blockable in contract '${t.contractId}'; failurePolicy 'closed' is not permitted`)}return n}export{x as $,J as A,P as B,q as C,ge as D,_e as E,R as F,j as G,O as H,z as I,N as J,L as K,H as L,B as M,U as N,he as O,V as P,w as Q,D as R,K as S,Y as T,M as U,k as V,A as W,T as X,E as Y,C as Z,ve as _,Fe as a,m as at,ye as b,Ae as c,h as ct,Oe as d,v as dt,S as et,Ee as f,fe as ft,Te as g,Ce as h,Ne as i,f as it,Se as j,me as k,Q as l,y as lt,Z as m,Pe as n,b as nt,Ie as o,de as ot,De as p,F as q,Me as r,d as rt,Le as s,_ as st,je as t,p as tt,ke as u,g as ut,G as v,xe as w,W as x,be as y,I as z};

package/dist/clients/index.d.mts

@@ -13,7 +13,7 @@ import * as _$drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
 import * as _$_makaio_storage_drizzle0 from "@makaio/framework/storage/drizzle";
 import { MakaioDatabase } from "@makaio/framework/storage/drizzle";
 import * as _$drizzle_orm0 from "drizzle-orm";
-import { ActivationValidationError, CanonicalEffect, ClientAccountIdentifier, ClientDefinition as ClientDefinition$1, ClientExecutionContext, ClientInstallCompleted, ClientInstallProgress, ClientRuntimeObserveRequest, ClientSessionObservedBase, ClientSubjects, ClientUsageSnapshot, ClientWiringEntry, ClientWiringEntrySchema, ContributorDefinition, ManagedInstallDescriptor, ManagedInstallStrategy, PostInstallDescriptor, ProviderContractCatalogEntry, ProviderContributionEnvelope, RuntimeOutcomeCode } from "@makaio/framework/contracts/client";
+import { ActivationValidationError, CanonicalEffect, ClientAccountIdentifier, ClientDefinition as ClientDefinition$1, ClientExecutionContext, ClientInstallCompleted, ClientInstallProgress, ClientRuntimeObserveRequest, ClientSessionObservedBase, ClientSessionTokenScope, ClientSubjects, ClientUsageSnapshot, ClientWiringEntry, ClientWiringEntrySchema, ContributorDefinition, ManagedInstallDescriptor, ManagedInstallStrategy, PostInstallDescriptor, ProviderContractCatalogEntry, ProviderContributionEnvelope, RuntimeOutcomeCode } from "@makaio/framework/contracts/client";
 import * as _$zod_v4_core0 from "zod/v4/core";
 
 //#region subsystems/client/src/atomic-modify-file.d.ts
@@ -1270,6 +1270,103 @@ declare class ClientSessionConfigService extends BaseService {
   private listClientIds;
 }
 //#endregion
+//#region subsystems/client/src/client-session-token-service.d.ts
+/**
+ * Narrow write-only interface for recording session correlation tokens.
+ *
+ * Client services receive this interface injected from clients-core and call
+ * it directly — the token is never placed on the bus so the `MAKAIO_DEBUG`
+ * bus logger never sees the token value.
+ */
+interface ClientSessionTokenSink {
+  /**
+   * Upsert a correlation token for the given scope.
+   *
+   * A later call for the same scope overwrites the previous entry — the
+   * intended compaction path when `SessionStart` fires again with
+   * `startMode: 'compact'`.
+   */
+  record(scope: ClientSessionTokenScope, token: string): void;
+}
+/**
+ * In-process token store for `client.session.token.*` subjects.
+ *
+ * Tokens are written via the public {@link record} method (called directly by
+ * the client service that produced the token, never over the bus) and read via
+ * the `client.session.token.get` bus handler (reachable by remote MCP servers
+ * over the WebSocket bus).
+ *
+ * Keeps tokens in memory keyed by adapter session id and an optional agent id.
+ * A later {@link record} call for the same key overwrites the previous entry —
+ * the intended compaction path when `SessionStart` fires again with
+ * `startMode: 'compact'`.
+ *
+ * Access (both {@link record} and `get`) refreshes `lastActivity` and reorders
+ * the entry to the Map tail so Map insertion order always reflects recency: the
+ * first Map entry is the least recently active (LRU) and is evicted first when
+ * the store exceeds {@link MAX_SESSION_TOKEN_COUNT}.
+ *
+ * The `agentId` dimension in the key builder is retained even though no client
+ * currently declares `session.token` on `SubagentStart`. A client whose MCP
+ * consumers can learn an agent id may declare `SubagentStart` later without a
+ * contract change; the completion-cleanup handler would come back with it.
+ */
+declare class ClientSessionTokenService extends BaseService implements ClientSessionTokenSink {
+  /**
+   * In-memory token store.
+   *
+   * Key: output of {@link buildKey}.
+   * Value: the stored token entry.
+   *
+   * Map insertion order is used as an LRU indicator: every access calls
+   * {@link touchEntry}, which deletes and re-inserts the entry to move it to
+   * the tail. The head of the Map is therefore always the LRU entry.
+   */
+  private readonly store;
+  /**
+   * @param bus - Bus instance used for handler registration
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Upsert a correlation token for the given scope.
+   *
+   * Called in-process by the client service that received the hook — the token
+   * is handed over directly so no bus payload (and no `MAKAIO_DEBUG` bus
+   * logger) ever sees it.
+   *
+   * A later call for the same scope overwrites the previous entry — the
+   * intended compaction path when `SessionStart` fires again with
+   * `startMode: 'compact'`. Never log the token value.
+   * @param scope - Scope identifying the session (or subagent) that produced
+   *   the token.
+   * @param token - The opaque correlation token to store.
+   */
+  record(scope: ClientSessionTokenScope, token: string): void;
+  /**
+   * Register bus handlers and start the TTL sweep timer.
+   */
+  protected onInit(): void;
+  /**
+   * Clear the in-memory store on teardown.
+   */
+  protected onDestroy(): void;
+  /**
+   * Build the lookup key for the in-memory store.
+   *
+   * The key always includes the client id so that two client providers that
+   * share the same provider-local session id cannot collide in the store, and
+   * a subagent-completion event for one client cannot delete the entry of
+   * another. When an agent id is present, it is appended so that a subagent
+   * token does not collide with or shadow the parent-session token.
+   * @param clientId - Stable client identity (e.g. `'claude-code'`, `'codex'`).
+   * @param adapterSessionId - Hook payload `session_id` from the client runtime.
+   * @param agentId - Present for SubagentStart events; absent for top-level
+   *   SessionStart events.
+   * @returns Composite key string for use in {@link store}.
+   */
+  private buildKey;
+}
+//#endregion
 //#region subsystems/client/src/client-session-observed-semantics.d.ts
 /**
  * Canonical schema for the raw catch-all hook payload delivered on
@@ -1880,16 +1977,18 @@ declare class ClientHookResponseRegistry {
 /**
  * Composite service that initialises and destroys the
  * {@link ClientRuntimeService}, the {@link ClientBinaryManager}, the
- * {@link ClientConfigPrimeService}, the {@link ClientProfileService}, and the
- * {@link ClientSessionConfigService}
+ * {@link ClientConfigPrimeService}, the {@link ClientProfileService}, the
+ * {@link ClientSessionConfigService}, and the {@link ClientSessionTokenService}
  * under a single {@link ExtensionServiceLifecycle} handle.
  *
- * Also exposes the client hook response pipeline registries so other
- * subsystems (provider runtimes, contribution processors) can register
- * and unregister provider contracts and query contributor snapshots.
+ * Also exposes the client hook response pipeline registries and the
+ * {@link ClientSessionTokenSink} so other subsystems (provider runtimes,
+ * contribution processors) can register and unregister provider contracts,
+ * query contributor snapshots, and record session correlation tokens
+ * in-process without the token ever appearing on the bus.
  *
  * The host coordinator calls `init()` once and `destroy()` once; this class
- * ensures all five services participate in the same lifecycle without any
+ * ensures all six services participate in the same lifecycle without any
  * requiring knowledge of the others.
  */
 declare class ClientsCoreService implements ExtensionServiceLifecycle {
@@ -1898,22 +1997,34 @@ declare class ClientsCoreService implements ExtensionServiceLifecycle {
   private readonly configPrimeService;
   private readonly profileService;
   private readonly sessionConfigService;
+  private readonly sessionTokenService;
   /** Provider contract catalog registry for the hook response pipeline. */
   readonly providerContractRegistry: ClientHookProviderContractRegistry;
   /** Contributor definition registry for the hook response pipeline. */
   readonly hookResponseRegistry: ClientHookResponseRegistry;
+  /**
+   * In-process sink for session correlation tokens.
+   *
+   * Client runtime services receive this and call {@link ClientSessionTokenSink.record}
+   * directly — the token is never placed on the bus so the `MAKAIO_DEBUG`
+   * bus logger never sees it. MCP servers retrieve the stored token via the
+   * normal `client.session.token.get` bus request.
+   */
+  readonly sessionTokens: ClientSessionTokenSink;
   /**
    * @param runtimeService - Handles `client.*` runtime observation subjects
    * @param binaryManager - Handles `client.*` binary-management subjects
    * @param configPrimeService - Handles generic `client.config.prime` delegation
    * @param profileService - Handles `client.profile.*` CRUD subjects
    * @param sessionConfigService - Handles `client.sessionConfig.*` isolation subjects
+   * @param sessionTokenService - Handles `client.session.token.get` and stores
+   *   tokens written via its {@link ClientSessionTokenSink} interface
    * @param providerContractRegistry - Provider contract catalog for activation-time validation
    * @param hookResponseRegistry - Contributor definition registry for the hook response pipeline
    */
-  constructor(runtimeService: ClientRuntimeService, binaryManager: ClientBinaryManager, configPrimeService: ClientConfigPrimeService, profileService: ClientProfileService, sessionConfigService: ClientSessionConfigService, providerContractRegistry: ClientHookProviderContractRegistry, hookResponseRegistry: ClientHookResponseRegistry);
+  constructor(runtimeService: ClientRuntimeService, binaryManager: ClientBinaryManager, configPrimeService: ClientConfigPrimeService, profileService: ClientProfileService, sessionConfigService: ClientSessionConfigService, sessionTokenService: ClientSessionTokenService, providerContractRegistry: ClientHookProviderContractRegistry, hookResponseRegistry: ClientHookResponseRegistry);
   /**
-   * Initialize all five sub-services in parallel.
+   * Initialize all six sub-services in parallel.
    *
    * Uses {@link Promise.allSettled} so every service always attempts
    * initialisation — matching the resilience pattern used by {@link destroy}.
@@ -1922,7 +2033,7 @@ declare class ClientsCoreService implements ExtensionServiceLifecycle {
    */
   init(): Promise<void>;
   /**
-   * Destroy all five sub-services in parallel.
+   * Destroy all six sub-services in parallel.
    *
    * Uses {@link Promise.allSettled} to guarantee every cleanup runs even when
    * one rejects, then reports every rejection together. Reporting is not
@@ -2937,6 +3048,14 @@ interface SessionEventDescriptor {
    * - `'request'` — request/response: install `makaio hook handle ...`
    */
   readonly mode: 'event' | 'request';
+  /**
+   * Lowest client binary version that fires this event, as a semver literal.
+   *
+   * Absent when the event is available across the whole `supportedVersions`
+   * range of the client. The wiring layer uses this to skip events whose
+   * minimum lies above the detected binary version.
+   */
+  readonly minimumVersion?: string;
 }
 /**
  * Build a shell-safe client command string from an executable and argv tokens.
@@ -2985,6 +3104,28 @@ declare function buildHookCommand(makaioCommand: string, sentinel: string, event
  * @returns Read-only array of `{ eventName, mode }` descriptors in declaration order.
  */
 declare function deriveSessionEventDescriptors(clientDefinition: ClientDefinition$1): ReadonlyArray<SessionEventDescriptor>;
+/**
+ * Determine whether a session event should be wired given the detected binary
+ * version.
+ *
+ * Enforcement semantics:
+ * - When `descriptor.minimumVersion` is absent the event is supported across
+ *   the whole `supportedVersions` range — always return `true`.
+ * - When `binaryVersion` is `null`, `undefined`, or any non-semver string
+ *   (for example the literal `'unknown'` that the CLI version detector emits
+ *   on parse failure, or a partial version such as `'2.1'`) the installed
+ *   version is unknown; treat the event as supported — return `true`.
+ * - Otherwise return `true` only when `binaryVersion >= minimumVersion`.
+ * @param descriptor - Session-event descriptor to test. Only `eventName` and
+ *   `minimumVersion` are inspected; the full descriptor is accepted for
+ *   convenience so callers need not destructure.
+ * @param binaryVersion - Detected binary version string, or `null`/`undefined`
+ *   when the version could not be determined. Any value that is not a valid
+ *   exact semver (no leading `v`, no range syntax) is treated as unknown.
+ * @returns `true` when the event should be wired, `false` when it should be
+ *   skipped because the binary is too old.
+ */
+declare function isSessionEventSupported(descriptor: Pick<SessionEventDescriptor, 'eventName' | 'minimumVersion'>, binaryVersion: string | null | undefined): boolean;
 //#endregion
 //#region subsystems/client/src/client-hook-response-contribution-processor.d.ts
 /**
@@ -3122,4 +3263,4 @@ interface RegisteredContributor {
  */
 declare function collectContributions(snapshot: ReadonlyArray<RegisteredContributor>, clientId: string, requestDeadline: number | undefined, requestSignal: AbortSignal | undefined, eventName: string, eventPayload: unknown, providerContract?: ProviderContractCatalogEntry): Promise<CollectionResult>;
 //#endregion
-export { AbsolutePathSchema, type AtomicContentParser, type AtomicModifier, type AtomicModifyOutcome, BinaryNotFoundError, type BuildClientSessionBaseOpts, CLIENT_RUNTIME_STATUSES, ClientAccountRegistry, type ClientAccountUpsertResult, ClientBinaryJobRunner, ClientBinaryManager, type ClientBinaryManagerConfig, type ClientBinaryResolutionPolicy, type ClientBinaryStateRecord, ClientBinaryStateRecordSchema, ClientBinaryStorageNamespace, ClientBinaryStorageSubjects, type ClientBinaryVersionRecord, ClientBinaryVersionRecordSchema, ClientBinaryVersionResolver, ClientConfigPrimeService, type ClientDefinitionLookup, ClientDefinitionRegistry, type ClientHookHandleResponse, ClientHookHandleResponseSchema, ClientHookProviderContractRegistry, ClientHookResponseRegistry, type ClientNamespaceResult, type ClientProfileRecord, ClientProfileRecordSchema, ClientProfileService, ClientProfileStorageNamespace, ClientProfileStorageSubjects, type ClientRuntimeRecord, ClientRuntimeRegistry, ClientRuntimeService, type ClientRuntimeStatus, ClientRuntimeStorageNamespace, ClientRuntimeStorageSubjects, ClientSessionConfigService, ClientSubjects, type ClientWiringAggregatedResult, ClientWiringAggregatedResultSchema, type ClientWiringApplyResponse, ClientWiringApplyResponseSchema, type ClientWiringEntry, ClientWiringEntrySchema, type ClientWiringListResponse, ClientWiringListResponseSchema, type ClientWiringListSubjectDef, type ClientWiringRemoveResponse, ClientWiringRemoveResponseSchema, type ClientWiringSubjectDefBase, type ClientsCorePackageOptions, ClientsCoreService, ClientsCoreToken, type ClosedFailureResult, type CollectionDiagnostic, type CollectionResult, type ContributorInstallResult, type ContributorOutcome, DEFAULT_HOOK_HANDLE_TIMEOUT_MS, type DiagnosticSeverity, type InstallArtifact, type InstallJob, type InstallStrategy, type JobCompletedCallback, type JobCompletionCallback, type JobCompletionResult, type JobProgressCallback, NOOP_HOOK_HANDLE_RESPONSE, type PostInstallContext, type PostInstallHandler, type RawClientHookHandleSubject, type RawClientHookPayload, RawClientHookPayloadSchema, type RawClientHookReceivedSubject, type RegisteredContributor, type RegisteredContributor$1 as RegistryContributor, type ResolvedInstallVersion, RuntimeRecordSchema, type RuntimeUpsertResult, type SessionEventDescriptor, type StrategyDependencies, assertAbsoluteProjectDir, atomicModifyFile, buildClientCommand, buildClientSessionBase, buildHookCommand, canonicalizeClientId, clientRuntimesDual, collectContributions, createClientHookResponseContributionProcessor, createClientNamespace, createClientWiringListSubjectDef, createClientWiringSubjectDef, createClientsCorePackage, createRawClientHookHandleSubject, createRawClientHookReceivedSubject, createStrategy, deriveSessionEventDescriptors, emitBestEffort, isPathWithinBase, pickNonEmptyString, pickNonEmptyStringValue, registerDrizzleClientBinaryStorage, registerDrizzleProfileStorage, registerDrizzleRuntimeStorage, registerStorageHandlersWithRollback, resolveAndValidateBasePath, resolveClientBinary, verifyInstalledVersion };
+export { AbsolutePathSchema, type AtomicContentParser, type AtomicModifier, type AtomicModifyOutcome, BinaryNotFoundError, type BuildClientSessionBaseOpts, CLIENT_RUNTIME_STATUSES, ClientAccountRegistry, type ClientAccountUpsertResult, ClientBinaryJobRunner, ClientBinaryManager, type ClientBinaryManagerConfig, type ClientBinaryResolutionPolicy, type ClientBinaryStateRecord, ClientBinaryStateRecordSchema, ClientBinaryStorageNamespace, ClientBinaryStorageSubjects, type ClientBinaryVersionRecord, ClientBinaryVersionRecordSchema, ClientBinaryVersionResolver, ClientConfigPrimeService, type ClientDefinitionLookup, ClientDefinitionRegistry, type ClientHookHandleResponse, ClientHookHandleResponseSchema, ClientHookProviderContractRegistry, ClientHookResponseRegistry, type ClientNamespaceResult, type ClientProfileRecord, ClientProfileRecordSchema, ClientProfileService, ClientProfileStorageNamespace, ClientProfileStorageSubjects, type ClientRuntimeRecord, ClientRuntimeRegistry, ClientRuntimeService, type ClientRuntimeStatus, ClientRuntimeStorageNamespace, ClientRuntimeStorageSubjects, ClientSessionConfigService, ClientSessionTokenService, type ClientSessionTokenSink, ClientSubjects, type ClientWiringAggregatedResult, ClientWiringAggregatedResultSchema, type ClientWiringApplyResponse, ClientWiringApplyResponseSchema, type ClientWiringEntry, ClientWiringEntrySchema, type ClientWiringListResponse, ClientWiringListResponseSchema, type ClientWiringListSubjectDef, type ClientWiringRemoveResponse, ClientWiringRemoveResponseSchema, type ClientWiringSubjectDefBase, type ClientsCorePackageOptions, ClientsCoreService, ClientsCoreToken, type ClosedFailureResult, type CollectionDiagnostic, type CollectionResult, type ContributorInstallResult, type ContributorOutcome, DEFAULT_HOOK_HANDLE_TIMEOUT_MS, type DiagnosticSeverity, type InstallArtifact, type InstallJob, type InstallStrategy, type JobCompletedCallback, type JobCompletionCallback, type JobCompletionResult, type JobProgressCallback, NOOP_HOOK_HANDLE_RESPONSE, type PostInstallContext, type PostInstallHandler, type RawClientHookHandleSubject, type RawClientHookPayload, RawClientHookPayloadSchema, type RawClientHookReceivedSubject, type RegisteredContributor, type RegisteredContributor$1 as RegistryContributor, type ResolvedInstallVersion, RuntimeRecordSchema, type RuntimeUpsertResult, type SessionEventDescriptor, type StrategyDependencies, assertAbsoluteProjectDir, atomicModifyFile, buildClientCommand, buildClientSessionBase, buildHookCommand, canonicalizeClientId, clientRuntimesDual, collectContributions, createClientHookResponseContributionProcessor, createClientNamespace, createClientWiringListSubjectDef, createClientWiringSubjectDef, createClientsCorePackage, createRawClientHookHandleSubject, createRawClientHookReceivedSubject, createStrategy, deriveSessionEventDescriptors, emitBestEffort, isPathWithinBase, isSessionEventSupported, pickNonEmptyString, pickNonEmptyStringValue, registerDrizzleClientBinaryStorage, registerDrizzleProfileStorage, registerDrizzleRuntimeStorage, registerStorageHandlersWithRollback, resolveAndValidateBasePath, resolveClientBinary, verifyInstalledVersion };