@ggui-ai/protocol 0.1.0-rc.1

package/dist/types/contract-inference.d.ts

@@ -0,0 +1,401 @@
+import type { DataContract, JsonObject, JsonValue } from './data-contract';
+/**
+ * Extract the JSON Schema `required` array from a schema literal as a
+ * string union. Resolves to `never` when `required` is absent, empty,
+ * or non-string-typed.
+ *
+ * Used by {@link SchemaToType} to split an object's `properties` into
+ * required + optional sub-maps. Honors the spec's `required: string[]`
+ * array; properties NOT listed are optional.
+ */
+export type RequiredKeysOf<S> = S extends {
+    readonly required: readonly (infer R)[];
+} ? R extends string ? R : never : never;
+/**
+ * Flatten an intersection of object types into a single object type.
+ *
+ * Why this exists: the required/optional split in {@link SchemaToType}
+ * (and the parallel split in {@link InferProps}) emits an intersection
+ * `{ required keys } & { optional keys }`. TypeScript's `Equal` helper
+ * (used in our type tests) treats `A & B` and the equivalent flat
+ * shape as DIFFERENT types under its `[<T>() => …]` conditional
+ * distribution trick, even though they're assignable in both
+ * directions. `Prettify` walks every key one level deep and rebuilds
+ * a flat shape, so `Equal` resolves correctly.
+ *
+ * Note: only one level deep — nested object properties keep their
+ * own structure (which is fine because nested objects flow back
+ * through `SchemaToType` themselves and emerge already-prettified).
+ */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Map a JSON Schema literal type to its corresponding TypeScript type.
+ *
+ * Works with `as const` literals to preserve exact types:
+ * - `{ type: 'string' }` -> `string`
+ * - `{ type: 'number' }` -> `number`
+ * - `{ type: 'boolean' }` -> `boolean`
+ * - `{ type: 'null' }` -> `null`
+ * - `{ type: 'array', items: S }` -> `SchemaToType<S>[]`
+ * - `{ type: 'object', properties: { k: S }, required: ['k'] }` -> `{ k: SchemaToType<S> }`
+ * - `{ type: 'object', properties: { k: S } }` -> `{ k?: SchemaToType<S> }` (no `required` ⇒ all optional, per JSON Schema draft-07)
+ * - `{ type: 'object' }` (no properties) -> {@link JsonObject}
+ * - `{ enum: ['a', 'b'] }` -> `'a' | 'b'`
+ * - `{ const: 42 }` -> `42`
+ * - `{ oneOf: [S1, S2] }` -> `SchemaToType<S1> | SchemaToType<S2>`
+ *
+ * Falls back to `unknown` for non-literal or unrecognized schemas.
+ * Objects without explicit `properties` resolve to {@link JsonObject} (not `unknown`).
+ *
+ * Required-array honor: per JSON Schema draft-07, an object schema's
+ * `required` array names the keys that MUST be present; properties NOT
+ * listed are optional. The mapping splits `properties` into a required
+ * sub-map (keys in `required`) and an
+ * optional sub-map (the rest), then intersects them. When `required` is
+ * absent or empty, all properties are optional.
+ */
+export type SchemaToType<S> = S extends {
+    readonly const: infer V;
+} ? V : S extends {
+    readonly enum: readonly (infer E)[];
+} ? E : S extends {
+    readonly type: 'string';
+} ? string : S extends {
+    readonly type: 'number';
+} ? number : S extends {
+    readonly type: 'integer';
+} ? number : S extends {
+    readonly type: 'boolean';
+} ? boolean : S extends {
+    readonly type: 'null';
+} ? null : S extends {
+    readonly type: 'array';
+    readonly items: infer I;
+} ? SchemaToType<I>[] : S extends {
+    readonly type: 'object';
+    readonly properties: infer P;
+} ? Prettify<{
+    -readonly [K in keyof P as K extends RequiredKeysOf<S> ? K : never]: SchemaToType<P[K]>;
+} & {
+    -readonly [K in keyof P as K extends RequiredKeysOf<S> ? never : K]?: SchemaToType<P[K]>;
+}> : S extends {
+    readonly type: 'object';
+} ? JsonObject : S extends {
+    readonly oneOf: readonly (infer U)[];
+} ? SchemaToType<U> : S extends {
+    readonly anyOf: readonly (infer U)[];
+} ? SchemaToType<U> : unknown;
+/**
+ * Infer the TypeScript props type from a `PropsSpec` literal.
+ *
+ * Given `{ properties: { city: { schema: { type: 'string' }, required: true }, temp: { schema: { type: 'number' } } } }`,
+ * infers `{ city: string; temp?: number }`.
+ *
+ * Falls back to {@link JsonObject} when no props spec is present (untyped usage).
+ *
+ * Required honor: each {@link PropEntry} carries a per-property
+ * `required?: boolean` flag (NOT a `required: string[]` at the props
+ * level — that's the JSON Schema convention used elsewhere by
+ * {@link SchemaToType}). Entries with `required: true` map to
+ * required keys; everything else (`required: false`, `required` omitted,
+ * or any non-`true` value) maps to optional `?:` keys. The split uses
+ * a key-remap, mirroring the JSON-Schema `required: string[]` handling
+ * in {@link SchemaToType}.
+ */
+export type InferProps<T> = T extends {
+    readonly propsSpec: {
+        readonly properties: infer P;
+    };
+} ? Prettify<{
+    -readonly [K in keyof P as P[K] extends {
+        readonly required: true;
+    } ? K : never]: P[K] extends {
+        readonly schema: infer S;
+    } ? SchemaToType<S> : unknown;
+} & {
+    -readonly [K in keyof P as P[K] extends {
+        readonly required: true;
+    } ? never : K]?: P[K] extends {
+        readonly schema: infer S;
+    } ? SchemaToType<S> : unknown;
+}> : JsonObject;
+/**
+ * Extract action names as a string literal union from a contract.
+ *
+ * `DataContract.actionSpec` is a flat `Record<actionName, ActionEntry>`;
+ * this type matches that shape directly.
+ *
+ * The fallback (no `actionSpec` key on `T`) resolves to `never`, not
+ * `string`. A `string` fallback would silently let generated code
+ * pattern-match against arbitrary names when no contract was declared;
+ * `never` makes `useAction('nonExistent')` a compile error instead.
+ * Consumers that still need a broad name/payload shape (e.g. the
+ * server-side untyped-handler default) keep it by going through
+ * `TypedAction<T>`, which falls back to `{ name: string; data: JsonValue }`
+ * when Names narrows to `never`.
+ */
+export type InferActionNames<T> = T extends {
+    readonly actionSpec: infer A;
+} ? Extract<keyof A, string> : never;
+/**
+ * Infer the payload type for a specific action.
+ * Actions without a `schema` field have `void` payload (fire-and-forget).
+ */
+export type InferActionPayload<T, N extends string> = T extends {
+    readonly actionSpec: infer A;
+} ? N extends keyof A ? A[N] extends {
+    readonly schema: infer S;
+} ? SchemaToType<S> : void : never : unknown;
+/**
+ * Extract stream channel names as a string literal union from a contract.
+ *
+ * `DataContract.streamSpec` is a flat
+ * `Record<channelName, StreamChannelEntry>`; this type matches that
+ * shape directly.
+ *
+ * The fallback (no `streamSpec` key on `T`) resolves to `never`, not
+ * `string`. Parallel to `InferActionNames` — `useStream('nonExistent')`
+ * becomes a compile error when no contract is declared.
+ * `TypedStreamEvent<T>` preserves the broad
+ * `{ channel: string; payload: JsonValue; … }` fallback when names
+ * narrow to `never`, so untyped-handler defaults still work.
+ */
+export type InferStreamNames<T> = T extends {
+    readonly streamSpec: infer C;
+} ? Extract<keyof C, string> : never;
+/** Infer the payload type for a specific stream channel. */
+export type InferStreamPayload<T, N extends string> = T extends {
+    readonly streamSpec: infer C;
+} ? N extends keyof C ? C[N] extends {
+    readonly schema: infer S;
+} ? SchemaToType<S> : unknown : never : unknown;
+/**
+ * Extract contextSpec slot names as a string literal union from a contract.
+ *
+ * Mirrors {@link InferActionNames} / {@link InferStreamNames}: when the
+ * contract declares a `contextSpec` map, returns the keys as a literal
+ * union; absent → `never` (so a context-slot lookup for a `'nonExistent'`
+ * key against an empty contract is a compile error rather than a silent
+ * broad-string fallback).
+ */
+export type InferContextNames<T> = T extends {
+    readonly contextSpec: infer S;
+} ? Extract<keyof S, string> : never;
+/**
+ * Infer the value type for a specific contextSpec slot, narrowed by
+ * its declared `schema`. Mirrors {@link InferActionPayload} /
+ * {@link InferStreamPayload}.
+ *
+ * - Present `contextSpec` + known slot name → `SchemaToType<schema>`.
+ * - Present `contextSpec` + unknown slot name → `never`.
+ * - Absent `contextSpec` entirely → `unknown` (parallel to the
+ *   payload-fallback posture on actionSpec / streamSpec).
+ */
+export type InferContextValue<T, N extends string> = T extends {
+    readonly contextSpec: infer S;
+} ? N extends keyof S ? S[N] extends {
+    readonly schema: infer Sch;
+} ? SchemaToType<Sch> : unknown : never : unknown;
+/**
+ * Extract agent-tool names as a string literal union. Used by the
+ * generator's `AllWires<T>` completeness manifest to enumerate the
+ * catalog at type-time.
+ *
+ * The catalog is invoked by the AGENT, not the component — there is no
+ * payload-type inference for component callers because the component
+ * never calls these tools. The catalog is referenced from
+ * `actionSpec[*].nextStep` and `streamSpec[*].source.tool`.
+ */
+export type InferAgentToolNames<T> = T extends {
+    readonly agentCapabilities: {
+        readonly tools: infer Tools;
+    };
+} ? Extract<keyof Tools, string> : string;
+/**
+ * Extract gadget EXPORT names as a string literal union — the union
+ * of every export name across every package the contract declares on
+ * `clientCapabilities.gadgets` (which is package-keyed:
+ * `Record<package, Record<exportName, GadgetExportUse>>` — there is no
+ * `exports` wrapper; a package entry IS its export map).
+ *
+ * Gadgets are declarations, not RPC, so they have no input/output
+ * schemas to narrow against. The value type for a declared gadget is
+ * consumed via the runtime hook / rendered component (e.g.,
+ * `useMicrophone()` returns `GadgetHook<TOutput>`), not via a
+ * contract-level type query — so the export NAME is the unit the
+ * completeness manifest enumerates.
+ */
+export type InferGadgetNames<T> = T extends {
+    readonly clientCapabilities: {
+        readonly gadgets: infer Pkgs;
+    };
+} ? {
+    [K in keyof Pkgs]: Extract<keyof Pkgs[K], string>;
+}[keyof Pkgs] : string;
+/**
+ * Discriminated union of all stream emissions in a contract.
+ *
+ * Each member has `{ channel: ChannelName; payload: PayloadType; complete?: boolean; stackItemId?: string }`
+ * — the agent-supplied fields of {@link GguiEmitInput} minus `sessionId`
+ * (which is caller context, not per-delivery).
+ *
+ * `mode` / `seq` / transport details are intentionally NOT on this union:
+ * `mode` is derived from `streamSpec[channel].mode` server-side,
+ * and `seq` is server-assigned via `SessionStreamBuffer`. Producers that
+ * try to set either are drifting against the streamSpec design lock.
+ *
+ * Falls back to `{ channel: string; payload: JsonValue; complete?: boolean; stackItemId?: string }`
+ * when the contract has no `streamSpec` declared.
+ */
+export type TypedStreamEvent<T> = [
+    InferStreamNames<T>
+] extends [never] ? {
+    channel: string;
+    payload: JsonValue;
+    complete?: boolean;
+    stackItemId?: string;
+} : InferStreamNames<T> extends infer Names extends string ? {
+    [N in Names]: {
+        channel: N;
+        payload: InferStreamPayload<T, N>;
+        complete?: boolean;
+        stackItemId?: string;
+    };
+}[Names] : {
+    channel: string;
+    payload: JsonValue;
+    complete?: boolean;
+    stackItemId?: string;
+};
+/**
+ * Discriminated union of all action events in a contract.
+ * Each member has `{ name: ActionName; data: PayloadType }`.
+ *
+ * Falls back to `{ name: string; data: JsonValue }` when no action spec is present.
+ */
+export type TypedAction<T> = [
+    InferActionNames<T>
+] extends [never] ? {
+    name: string;
+    data: JsonValue;
+} : InferActionNames<T> extends infer Names extends string ? {
+    [N in Names]: {
+        name: N;
+        data: InferActionPayload<T, N>;
+    };
+}[Names] : {
+    name: string;
+    data: JsonValue;
+};
+/**
+ * Define a data contract with full type inference.
+ *
+ * The `const` type parameter preserves literal types from `as const`,
+ * enabling automatic TypeScript type inference from JSON Schema definitions.
+ *
+ * @example
+ * ```typescript
+ * const contract = defineContract({
+ *   intent: 'Show weather for a city with refresh control',
+ *   props: { properties: {
+ *     city: { schema: { type: 'string' } },
+ *     temp: { schema: { type: 'number' } },
+ *   }},
+ *   actionSpec: {
+ *     refresh: { label: 'Refresh' },
+ *     changeUnit: { label: 'Unit', schema: { type: 'object', properties: { unit: { type: 'string' } } } },
+ *   },
+ *   streamSpec: {
+ *     weatherUpdate: { schema: { type: 'object', properties: { temp: { type: 'number' }, conditions: { type: 'string' } } } },
+ *   },
+ * } as const);
+ *
+ * // TypeScript infers:
+ * //   InferProps<typeof contract> = { city: string; temp: number }
+ * //   InferActionNames<typeof contract> = 'refresh' | 'changeUnit'
+ * //   InferActionPayload<typeof contract, 'changeUnit'> = { unit: string }
+ * //   InferStreamPayload<typeof contract, 'weatherUpdate'> = { temp: number; conditions: string }
+ * ```
+ */
+export declare function defineContract<const T extends DataContract>(contract: T): T;
+/**
+ * Manual type map for cases where `SchemaToType` can't infer
+ * (complex unions, conditional schemas, branded types, etc.).
+ *
+ * Both paths (auto-inferred via `defineContract` and manual via `ContractTypeMap`)
+ * work with `useContract`, typed handlers, and typed MCP client methods.
+ *
+ * All map slots default to {@link JsonObject} (props, actions, streams) or
+ * `Record<string, { request/args: JsonValue; response: JsonValue }>` (tools)
+ * when not overridden.
+ *
+ * @example
+ * ```typescript
+ * interface MyContract extends ContractTypeMap {
+ *   props: { city: string; temperature: number };
+ *   actions: { refresh: void; changeUnit: { unit: 'C' | 'F' } };
+ *   streams: { weatherUpdate: { temp: number; conditions: string } };
+ * }
+ * ```
+ */
+export interface ContractTypeMap {
+    props?: JsonObject;
+    actions?: JsonObject;
+    streams?: JsonObject;
+    agentCapabilities?: Record<string, {
+        input: JsonValue;
+        output: JsonValue;
+    }>;
+    /**
+     * Per-gadget binding-name set. Values are intentionally typed
+     * `unknown` — gadget hooks own their own typed `value` / `start()`
+     * shape (see `GadgetHook` in `./gadget.ts`), which
+     * is not derivable from a contract-level type query.
+     */
+    clientCapabilities?: Record<string, unknown>;
+}
+/** Extract props from a manual ContractTypeMap. */
+export type PropsOf<C extends ContractTypeMap> = C extends {
+    props: infer P;
+} ? P : JsonObject;
+/** Extract action names from a manual ContractTypeMap. */
+export type ActionNames<C extends ContractTypeMap> = C extends {
+    actions: infer A;
+} ? Extract<keyof A, string> : string;
+/** Extract action payload from a manual ContractTypeMap. */
+export type ActionPayload<C extends ContractTypeMap, N extends ActionNames<C>> = C extends {
+    actions: infer A;
+} ? N extends keyof A ? A[N] : unknown : unknown;
+/** Extract stream event names from a manual ContractTypeMap. */
+export type StreamNames<C extends ContractTypeMap> = C extends {
+    streams: infer S;
+} ? Extract<keyof S, string> : string;
+/** Extract stream payload from a manual ContractTypeMap. */
+export type StreamPayloadOf<C extends ContractTypeMap, N extends StreamNames<C>> = C extends {
+    streams: infer S;
+} ? N extends keyof S ? S[N] : unknown : unknown;
+/**
+ * Extract agent-tool names from a manual ContractTypeMap. Used by the
+ * generator's `AllWires<T>` completeness manifest to enumerate the
+ * catalog at type-time.
+ *
+ * The catalog is invoked by the AGENT, never a component-side hook
+ * surface, so there is no payload-type inference for component callers.
+ */
+export type AgentToolNames<C extends ContractTypeMap> = C extends {
+    agentCapabilities: infer T;
+} ? Extract<keyof T, string> : string;
+/**
+ * Extract gadget binding names from a manual ContractTypeMap.
+ *
+ * Libraries are declarations, not RPC, so there is no payload-type
+ * inference. Value types are consumed via the runtime hook
+ * (`GadgetHook<TOutput>`), not via a contract-level query.
+ */
+export type GadgetNames<C extends ContractTypeMap> = C extends {
+    clientCapabilities: infer T;
+} ? Extract<keyof T, string> : string;
+export {};
+//# sourceMappingURL=contract-inference.d.ts.map

package/dist/types/contract-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-inference.d.ts","sourceRoot":"","sources":["../../src/types/contract-inference.ts"],"names":[],"mappings":"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"}

package/dist/types/contract-inference.js

@@ -0,0 +1,44 @@
+// packages/protocol/src/types/contract-inference.ts
+//
+// Compile-time type inference from JSON Schema contract literals.
+//
+// Agents write a single `defineContract({ ... } as const)` call.
+// TypeScript infers all prop types, action names/payloads, stream events,
+// and tool signatures automatically from the JSON Schema literal — no
+// parallel type definitions needed.
+// =============================================================================
+// defineContract — zero-cost identity that locks literal types
+// =============================================================================
+/**
+ * Define a data contract with full type inference.
+ *
+ * The `const` type parameter preserves literal types from `as const`,
+ * enabling automatic TypeScript type inference from JSON Schema definitions.
+ *
+ * @example
+ * ```typescript
+ * const contract = defineContract({
+ *   intent: 'Show weather for a city with refresh control',
+ *   props: { properties: {
+ *     city: { schema: { type: 'string' } },
+ *     temp: { schema: { type: 'number' } },
+ *   }},
+ *   actionSpec: {
+ *     refresh: { label: 'Refresh' },
+ *     changeUnit: { label: 'Unit', schema: { type: 'object', properties: { unit: { type: 'string' } } } },
+ *   },
+ *   streamSpec: {
+ *     weatherUpdate: { schema: { type: 'object', properties: { temp: { type: 'number' }, conditions: { type: 'string' } } } },
+ *   },
+ * } as const);
+ *
+ * // TypeScript infers:
+ * //   InferProps<typeof contract> = { city: string; temp: number }
+ * //   InferActionNames<typeof contract> = 'refresh' | 'changeUnit'
+ * //   InferActionPayload<typeof contract, 'changeUnit'> = { unit: string }
+ * //   InferStreamPayload<typeof contract, 'weatherUpdate'> = { temp: number; conditions: string }
+ * ```
+ */
+export function defineContract(contract) {
+    return contract;
+}

package/dist/types/credential.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Credential injection — cross-process wire protocol between the
+ * open @ggui-ai/server auth relay (which writes placeholders) and
+ * the closed cloud mcp-proxy service (which resolves them).
+ *
+ * Shared between:
+ *   - packages/server/src/mcp-auth-middleware.ts (writes placeholders)
+ *   - cloud/amplify/functions/rest-api/mcp-proxy/handler.ts (resolves placeholders)
+ *   - cloud/services/mcp-proxy/src/* (resolves placeholders)
+ *
+ * Hosted-overlay shapes for the `auth` block inside per-app
+ * config files are a hosting concept and not a portable wire
+ * protocol. What remains here is the runtime placeholder /
+ * injection-mode protocol, which is legitimately cross-process.
+ */
+/** How the proxy injects a credential into the outbound request. */
+export type CredentialInjection = 'bearer_header' | 'api_key_header' | 'query_param' | 'custom_header';
+/** Full injection config — resolved from app config or McpServiceConfig. */
+export interface CredentialInjectionConfig {
+    mode: CredentialInjection;
+    /** Header name for api_key_header / custom_header. Default: 'X-API-Key'. */
+    headerName?: string;
+    /** Query param name for query_param. Default: 'api_key'. */
+    paramName?: string;
+}
+/**
+ * Placeholder regex — matches `<ggui:credential:{serviceId}>`.
+ * The placeholder is always the raw credential slot value.
+ * The proxy applies injection formatting (Bearer prefix, header name, etc.).
+ */
+export declare const CREDENTIAL_PLACEHOLDER_RE: RegExp;
+/**
+ * Internal control header for placeholder pre-injection.
+ * - Writer: auth relay middleware only
+ * - Consumer: proxy only (reads, resolves, strips before forwarding)
+ * - Never forwarded upstream
+ */
+export declare const CREDENTIAL_HEADER = "x-ggui-credential";
+/** Build a placeholder string for a given serviceId. */
+export declare function credentialPlaceholder(serviceId: string): string;
+//# sourceMappingURL=credential.d.ts.map

package/dist/types/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../../src/types/credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,eAAe,CAAC;AAEpB,4EAA4E;AAC5E,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAyC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,wDAAwD;AACxD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/types/credential.js

@@ -0,0 +1,32 @@
+/**
+ * Credential injection — cross-process wire protocol between the
+ * open @ggui-ai/server auth relay (which writes placeholders) and
+ * the closed cloud mcp-proxy service (which resolves them).
+ *
+ * Shared between:
+ *   - packages/server/src/mcp-auth-middleware.ts (writes placeholders)
+ *   - cloud/amplify/functions/rest-api/mcp-proxy/handler.ts (resolves placeholders)
+ *   - cloud/services/mcp-proxy/src/* (resolves placeholders)
+ *
+ * Hosted-overlay shapes for the `auth` block inside per-app
+ * config files are a hosting concept and not a portable wire
+ * protocol. What remains here is the runtime placeholder /
+ * injection-mode protocol, which is legitimately cross-process.
+ */
+/**
+ * Placeholder regex — matches `<ggui:credential:{serviceId}>`.
+ * The placeholder is always the raw credential slot value.
+ * The proxy applies injection formatting (Bearer prefix, header name, etc.).
+ */
+export const CREDENTIAL_PLACEHOLDER_RE = /^<ggui:credential:([a-zA-Z0-9_-]+)>$/;
+/**
+ * Internal control header for placeholder pre-injection.
+ * - Writer: auth relay middleware only
+ * - Consumer: proxy only (reads, resolves, strips before forwarding)
+ * - Never forwarded upstream
+ */
+export const CREDENTIAL_HEADER = 'x-ggui-credential';
+/** Build a placeholder string for a given serviceId. */
+export function credentialPlaceholder(serviceId) {
+    return `<ggui:credential:${serviceId}>`;
+}