@makaio/framework 1.0.0-dev-1790614475240 → 1.0.0-dev-1790624115602

package/dist/.makaio-build.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "fingerprint": "02099fc14700c8fd141dc3449adbc6c5e6c2f2bfb8d9f88975d94e31a00888ad",
-  "builtAt": "2026-09-28T16:55:26.154Z",
+  "fingerprint": "12cfa25b43c1d0b6ceffbfc306b6c65b8a121b97d4326c03b26904dd23fae81a",
+  "builtAt": "2026-09-28T19:36:01.348Z",
   "declarations": true,
   "declarationBackend": "tsc"
 }

package/dist/clients/hook-subjects.d.mts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { EventMessagePayload, RequestMessagePayload, SubjectDefinition, SubjectRecord } from "@makaio/framework/core";
+
+//#region subsystems/client/src/hook-subjects.d.ts
+/**
+ * Canonical schema for the raw catch-all hook payload delivered on
+ * `client:<id>.hook.received`.
+ *
+ * Client ingress CLIs are dumb bridges: they accept any native hook event and
+ * publish it verbatim on this subject.  Downstream normalizers are responsible
+ * for interpreting `eventName` and mapping the `payload` to structured
+ * `client.session.*` observations.
+ *
+ * Fields:
+ * - `eventName`   — the hook event name as reported by the client CLI
+ *   (e.g. `'PreToolUse'`, `'Stop'`).
+ * - `receivedAt`  — Unix epoch timestamp in milliseconds when the bridge
+ *   received the hook call.
+ * - `payload`     — raw JSON object forwarded verbatim from the client CLI.
+ * - `metadata`    — optional pass-through metadata added by the bridge (e.g.
+ *   process PID, invocation arguments).
+ */
+declare const RawClientHookPayloadSchema: z.ZodObject<{
+  eventName: z.ZodString;
+  receivedAt: z.ZodNumber;
+  payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Parsed raw catch-all hook payload; see {@link RawClientHookPayloadSchema}. */
+type RawClientHookPayload = z.infer<typeof RawClientHookPayloadSchema>;
+/**
+ * Normalize user-provided client identifiers to the stable suffix used in
+ * `client:<id>` namespaces.
+ * @param clientId - Raw client identifier, optionally prefixed with `client:`
+ * @param caller - Optional function name used in thrown error messages
+ * @returns Canonical lowercase client identifier without the `client:` prefix
+ */
+declare function canonicalizeClientId(clientId: string, caller?: string): string;
+type RawClientHookSubjectRecord = SubjectRecord<'hook.received', EventMessagePayload<RawClientHookPayload>>;
+/**
+ * Subject definition for the raw catch-all hook event in a concrete
+ * `client:<id>` namespace.
+ */
+type RawClientHookReceivedSubject = SubjectDefinition<RawClientHookSubjectRecord, 'hook.received', `client:${string}`>;
+/**
+ * Build a non-owning subject definition for `client:<id>.hook.received`.
+ *
+ * This is intentionally not a namespace registration. Concrete client packages
+ * own their full `client:<id>` namespace via `createClientNamespace`; the
+ * generic CLI bridge only needs to emit the shared hook subject and must not
+ * accidentally register a narrower namespace before the concrete owner loads.
+ * When the concrete owner is loaded, normal bus schema validation applies. When
+ * it is not loaded, the ad-hoc subject still allows the raw event to traverse
+ * transports to a process that owns the namespace.
+ * @param clientId - Stable client identifier, optionally prefixed with `client:`
+ * @returns Non-owning subject definition for the client's raw hook ingress
+ */
+declare function createRawClientHookReceivedSubject(clientId: string): RawClientHookReceivedSubject;
+/**
+ * Default timeout in milliseconds for hook handle requests.
+ *
+ * Shared between the CLI schema default (client-hooks extension) and the
+ * wiring descriptor trailing flags (claude-code client) so both always agree
+ * on the configured wait budget without independent magic numbers.
+ */
+declare const DEFAULT_HOOK_HANDLE_TIMEOUT_MS = 5000;
+/**
+ * Schema for the response payload returned by a `makaio hook handle` command.
+ *
+ * The client binary reads this from the command's stdout after the process
+ * exits.  All fields default to safe zero-values so partial responses are
+ * still valid.
+ *
+ * Fields:
+ * - `exitCode` — process exit code the binary should use (0–255). Defaults to `0`.
+ * - `stdout`   — text written to stdout, forwarded verbatim to the client.
+ *   Defaults to `''`.
+ * - `stderr`   — text written to stderr, forwarded verbatim to the client.
+ *   Defaults to `''`.
+ */
+declare const ClientHookHandleResponseSchema: z.ZodObject<{
+  exitCode: z.ZodDefault<z.ZodNumber>;
+  stdout: z.ZodDefault<z.ZodString>;
+  stderr: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/** Parsed hook handle response; see {@link ClientHookHandleResponseSchema}. */
+type ClientHookHandleResponse = z.infer<typeof ClientHookHandleResponseSchema>;
+/**
+ * Frozen no-op hook handle response shared across all client composers.
+ *
+ * exitCode 0 with empty stdout/stderr is the provider-valid passthrough
+ * that permits the tool invocation to proceed unchanged.  A single frozen
+ * instance avoids per-client duplication and per-call object allocation.
+ */
+declare const NOOP_HOOK_HANDLE_RESPONSE: ClientHookHandleResponse;
+type RawClientHookHandleSubjectRecord = SubjectRecord<'hook.handle', RequestMessagePayload<RawClientHookPayload, ClientHookHandleResponse>>;
+/**
+ * Subject definition for the raw hook handle request/response subject in a
+ * concrete `client:<id>` namespace.
+ *
+ * Carries `RequestMessagePayload<RawClientHookPayload, ClientHookHandleResponse>`
+ * as a phantom type so `bus.requestOptional` infers the correct generics without
+ * additional type annotations at the call site.
+ */
+type RawClientHookHandleSubject = SubjectDefinition<RawClientHookHandleSubjectRecord, 'hook.handle', `client:${string}`>;
+/**
+ * Build a non-owning subject definition for `client:<id>.hook.handle`.
+ *
+ * The returned definition uses `isRequest: true` so the bus dispatches it
+ * through the request/response pipeline, and `hostLocalRequest: true` so the
+ * bus accepts direct remote ingress but never relays the request onward to
+ * other transports.  This matches the owning namespace registration in
+ * `createClientNamespace`, which wraps the schema with `hostLocalRequest()`.
+ *
+ * Concrete client packages own their full `client:<id>` namespace via
+ * `createClientNamespace`; this helper is intentionally non-owning for
+ * the same reasons as {@link createRawClientHookReceivedSubject} — see that
+ * function's doc for the full rationale.
+ * @param rawClientId - Stable client identifier, optionally prefixed with `client:`
+ * @returns Non-owning subject definition for the client's raw hook handle ingress
+ */
+declare function createRawClientHookHandleSubject(rawClientId: string): RawClientHookHandleSubject;
+//#endregion
+export { ClientHookHandleResponse, ClientHookHandleResponseSchema, DEFAULT_HOOK_HANDLE_TIMEOUT_MS, NOOP_HOOK_HANDLE_RESPONSE, RawClientHookHandleSubject, RawClientHookPayload, RawClientHookPayloadSchema, RawClientHookReceivedSubject, canonicalizeClientId, createRawClientHookHandleSubject, createRawClientHookReceivedSubject };

package/dist/clients/hook-subjects.mjs

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.object({eventName:e.string(),receivedAt:e.number().int().finite().nonnegative().describe(`Unix epoch timestamp in milliseconds`),payload:e.record(e.string(),e.unknown()),metadata:e.record(e.string(),e.unknown()).optional()}),n=/^[a-z0-9-]+$/;function r(e,t=`canonicalizeClientId`){let r=e.trim().toLowerCase(),i=r.startsWith(`client:`)?r.slice(7):r;if(i.length===0)throw Error(`[${t}] clientId must be a non-empty string`);if(!n.test(i))throw Error(`[${t}] clientId must contain only lowercase letters, numbers, and hyphens after an optional client: prefix`);return i}function i(e){return{subject:`hook.received`,$meta:{namespace:`client:${r(e,`createRawClientHookReceivedSubject`)}`,isRequest:!1,local:!1,channel:!1}}}const a=5e3,o=e.object({exitCode:e.number().int().min(0).max(255).default(0),stdout:e.string().default(``),stderr:e.string().default(``)}),s=Object.freeze({exitCode:0,stdout:``,stderr:``});function c(e){return{subject:`hook.handle`,$meta:{namespace:`client:${r(e,`createRawClientHookHandleSubject`)}`,isRequest:!0,local:!1,channel:!1,hostLocalRequest:!0}}}export{o as ClientHookHandleResponseSchema,a as DEFAULT_HOOK_HANDLE_TIMEOUT_MS,s as NOOP_HOOK_HANDLE_RESPONSE,t as RawClientHookPayloadSchema,r as canonicalizeClientId,c as createRawClientHookHandleSubject,i as createRawClientHookReceivedSubject};

package/dist/clients/index.d.mts

@@ -1,8 +1,9 @@
+import { ClientHookHandleResponse, ClientHookHandleResponseSchema, DEFAULT_HOOK_HANDLE_TIMEOUT_MS, NOOP_HOOK_HANDLE_RESPONSE, RawClientHookHandleSubject, RawClientHookPayload, RawClientHookPayloadSchema, RawClientHookReceivedSubject, canonicalizeClientId, createRawClientHookHandleSubject, createRawClientHookReceivedSubject } from "./hook-subjects.mjs";
 import { a as StrategyDependencies, i as InstallStrategy, n as createStrategy, r as InstallArtifact, t as verifyInstalledVersion } from "../client-binary-version-verifier-C8gtKQFO.mjs";
 import * as _$zod from "zod";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";
-import { EventMessagePayload, RequestMessagePayload, SchemaRecord, SubjectDefinition, SubjectRecord } from "@makaio/framework/core";
+import { RequestMessagePayload, SchemaRecord, SubjectDefinition, SubjectRecord } from "@makaio/framework/core";
 import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
 import { ClientDefinition, ExtensionServiceLifecycle, MakaioNodeExtension } from "@makaio/framework/contracts";
 import { IMakaioBus } from "@makaio/framework/bus";
@@ -1400,123 +1401,6 @@ declare class ClientSessionTokenService extends BaseService implements ClientSes
 }
 //#endregion
 //#region subsystems/client/src/client-session-observed-semantics.d.ts
-/**
- * Canonical schema for the raw catch-all hook payload delivered on
- * `client:<id>.hook.received`.
- *
- * Client ingress CLIs are dumb bridges: they accept any native hook event and
- * publish it verbatim on this subject.  Downstream normalizers are responsible
- * for interpreting `eventName` and mapping the `payload` to structured
- * `client.session.*` observations.
- *
- * Fields:
- * - `eventName`   — the hook event name as reported by the client CLI
- *   (e.g. `'PreToolUse'`, `'Stop'`).
- * - `receivedAt`  — Unix epoch timestamp in milliseconds when the bridge
- *   received the hook call.
- * - `payload`     — raw JSON object forwarded verbatim from the client CLI.
- * - `metadata`    — optional pass-through metadata added by the bridge (e.g.
- *   process PID, invocation arguments).
- */
-declare const RawClientHookPayloadSchema: z.ZodObject<{
-  eventName: z.ZodString;
-  receivedAt: z.ZodNumber;
-  payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-type RawClientHookPayload = z.infer<typeof RawClientHookPayloadSchema>;
-/**
- * Normalize user-provided client identifiers to the stable suffix used in
- * `client:<id>` namespaces.
- * @param clientId - Raw client identifier, optionally prefixed with `client:`
- * @param caller - Optional function name used in thrown error messages
- * @returns Canonical lowercase client identifier without the `client:` prefix
- */
-declare function canonicalizeClientId(clientId: string, caller?: string): string;
-type RawClientHookSubjectRecord = SubjectRecord<'hook.received', EventMessagePayload<RawClientHookPayload>>;
-/**
- * Subject definition for the raw catch-all hook event in a concrete
- * `client:<id>` namespace.
- */
-type RawClientHookReceivedSubject = SubjectDefinition<RawClientHookSubjectRecord, 'hook.received', `client:${string}`>;
-/**
- * Build a non-owning subject definition for `client:<id>.hook.received`.
- *
- * This is intentionally not a namespace registration. Concrete client packages
- * own their full `client:<id>` namespace via {@link createClientNamespace}; the
- * generic CLI bridge only needs to emit the shared hook subject and must not
- * accidentally register a narrower namespace before the concrete owner loads.
- * When the concrete owner is loaded, normal bus schema validation applies. When
- * it is not loaded, the ad-hoc subject still allows the raw event to traverse
- * transports to a process that owns the namespace.
- * @param clientId - Stable client identifier, optionally prefixed with `client:`
- * @returns Non-owning subject definition for the client's raw hook ingress
- */
-declare function createRawClientHookReceivedSubject(clientId: string): RawClientHookReceivedSubject;
-/**
- * Default timeout in milliseconds for hook handle requests.
- *
- * Shared between the CLI schema default (client-hooks extension) and the
- * wiring descriptor trailing flags (claude-code client) so both always agree
- * on the configured wait budget without independent magic numbers.
- */
-declare const DEFAULT_HOOK_HANDLE_TIMEOUT_MS = 5000;
-/**
- * Schema for the response payload returned by a `makaio hook handle` command.
- *
- * The client binary reads this from the command's stdout after the process
- * exits.  All fields default to safe zero-values so partial responses are
- * still valid.
- *
- * Fields:
- * - `exitCode` — process exit code the binary should use (0–255). Defaults to `0`.
- * - `stdout`   — text written to stdout, forwarded verbatim to the client.
- *   Defaults to `''`.
- * - `stderr`   — text written to stderr, forwarded verbatim to the client.
- *   Defaults to `''`.
- */
-declare const ClientHookHandleResponseSchema: z.ZodObject<{
-  exitCode: z.ZodDefault<z.ZodNumber>;
-  stdout: z.ZodDefault<z.ZodString>;
-  stderr: z.ZodDefault<z.ZodString>;
-}, z.core.$strip>;
-type ClientHookHandleResponse = z.infer<typeof ClientHookHandleResponseSchema>;
-/**
- * Frozen no-op hook handle response shared across all client composers.
- *
- * exitCode 0 with empty stdout/stderr is the provider-valid passthrough
- * that permits the tool invocation to proceed unchanged.  A single frozen
- * instance avoids per-client duplication and per-call object allocation.
- */
-declare const NOOP_HOOK_HANDLE_RESPONSE: ClientHookHandleResponse;
-type RawClientHookHandleSubjectRecord = SubjectRecord<'hook.handle', RequestMessagePayload<RawClientHookPayload, ClientHookHandleResponse>>;
-/**
- * Subject definition for the raw hook handle request/response subject in a
- * concrete `client:<id>` namespace.
- *
- * Carries `RequestMessagePayload<RawClientHookPayload, ClientHookHandleResponse>`
- * as a phantom type so `bus.requestOptional` infers the correct generics without
- * additional type annotations at the call site.
- */
-type RawClientHookHandleSubject = SubjectDefinition<RawClientHookHandleSubjectRecord, 'hook.handle', `client:${string}`>;
-/**
- * Build a non-owning subject definition for `client:<id>.hook.handle`.
- *
- * The returned definition uses `isRequest: true` so the bus dispatches it
- * through the request/response pipeline, and `hostLocalRequest: true` so the
- * bus accepts direct remote ingress but never relays the request onward to
- * other transports.  This matches the owning namespace registration in
- * {@link createClientNamespace}, which wraps the schema with
- * `hostLocalRequest()`.
- *
- * Concrete client packages own their full `client:<id>` namespace via
- * {@link createClientNamespace}; this helper is intentionally non-owning for
- * the same reasons as {@link createRawClientHookReceivedSubject} — see that
- * function's doc for the full rationale.
- * @param rawClientId - Stable client identifier, optionally prefixed with `client:`
- * @returns Non-owning subject definition for the client's raw hook handle ingress
- */
-declare function createRawClientHookHandleSubject(rawClientId: string): RawClientHookHandleSubject;
 /**
  * Trim and return a string value when non-empty, otherwise `undefined`.
  *