@cosmicdrift/kumiko-types 0.235.2 → 0.235.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.235.2",
+  "version": "0.235.4",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -233,6 +233,10 @@
     "./snapshot-types": {
       "types": "./src/snapshot-types.ts",
       "default": "./src/snapshot-types.ts"
+    },
+    "./agent-exposure": {
+      "types": "./src/agent-exposure.ts",
+      "default": "./src/agent-exposure.ts"
     }
   },
   "devDependencies": {

package/src/agent-exposure.ts

@@ -0,0 +1,14 @@
+import type { AgentExposure, AgentHandlerHints } from "./handlers";
+
+/** Fail-closed: a handler without a `description` stays invisible to the agent
+ *  unless it opts in explicitly. `kind` is a parameter because write and query
+ *  handler definitions are structurally indistinguishable at runtime. */
+export function resolveAgentExposure(
+  def: { readonly description?: string; readonly agent?: AgentHandlerHints },
+  kind: "query" | "write",
+): AgentExposure {
+  return {
+    expose: def.agent?.expose ?? def.description !== undefined,
+    risk: def.agent?.risk ?? (kind === "query" ? "low" : "mid"),
+  };
+}

package/src/define-handler.ts

@@ -2,6 +2,7 @@ import type { ZodType, z } from "zod";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type {
   AccessRule,
+  AgentHandlerHints,
   HandlerContext,
   QueryEvent,
   RateLimitOption,
@@ -34,6 +35,8 @@ export type WriteHandlerDefinition<
   readonly name: TName;
   readonly schema: TSchema;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
   readonly handler: (
@@ -59,6 +62,8 @@ export type WriteHandlerInput<
   readonly name: TName;
   readonly schema: TSchema;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
 } & (
@@ -86,6 +91,8 @@ export type QueryHandlerDefinition<
   readonly name: TName;
   readonly schema: TSchema;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   readonly handler: (
     query: QueryEvent<z.infer<TSchema>>,

package/src/feature.ts

@@ -27,6 +27,7 @@ import type { EntityTableMeta } from "./entity-table-meta-types";
 import type { EntityDefinition } from "./fields";
 import type {
   AccessRule,
+  AgentHandlerHints,
   AuthClaimsFn,
   AuthClaimsHookDef,
   ClaimKeyDefinition,
@@ -453,7 +454,12 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     name: string,
     schema: TSchema,
     handler: WriteHandlerFn<z.infer<TSchema>>,
-    options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+    options?: {
+      access?: AccessRule;
+      rateLimit?: RateLimitOption;
+      description?: string;
+      agent?: AgentHandlerHints;
+    },
   ): HandlerRef;
 
   queryHandler<TName extends string, TSchema extends ZodType>(
@@ -463,7 +469,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     name: string,
     schema: TSchema,
     handler: QueryHandlerFn<z.infer<TSchema>>,
-    options?: { access?: AccessRule; rateLimit?: RateLimitOption; outputSchema?: ZodType },
+    options?: {
+      access?: AccessRule;
+      rateLimit?: RateLimitOption;
+      outputSchema?: ZodType;
+      description?: string;
+      agent?: AgentHandlerHints;
+    },
   ): HandlerRef;
 
   streamHandler<TName extends string, TSchema extends ZodType>(
@@ -865,6 +877,7 @@ export type Registry = {
   getWriteHandler(name: string): WriteHandlerDef | undefined;
   getQueryHandler(name: string): QueryHandlerDef | undefined;
   getAllQueryHandlers(): ReadonlyMap<string, QueryHandlerDef>;
+  getAllWriteHandlers(): ReadonlyMap<string, WriteHandlerDef>;
   getStreamHandler(name: string): StreamHandlerDef | undefined;
   getAllStreamHandlers(): ReadonlyMap<string, StreamHandlerDef>;
   getSearchableFields(entityName: string): readonly string[];

package/src/fields.ts

@@ -237,6 +237,9 @@ export type RetentionDef = {
 
 export type TextFieldDef = {
   readonly type: "text";
+  /** Optional free-text semantics for the AI agent manifest — never rendered;
+   *  the i18n label is what users see. */
+  readonly description?: string;
   readonly maxLength?: number;
   readonly required?: boolean;
   readonly searchable?: boolean;
@@ -279,6 +282,7 @@ export type TextFieldDef = {
  */
 export type LongTextFieldDef = {
   readonly type: "longText";
+  readonly description?: string;
   /** Optionale soft-Cap. Default unbounded (= Postgres-text-limit, 1 GB).
    *  Nützlich für defensive Caps wie 1 MB damit ein verirrter Browser-
    *  Paste nicht die DB sprengt. */
@@ -293,6 +297,7 @@ export type LongTextFieldDef = {
 
 export type BooleanFieldDef = {
   readonly type: "boolean";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -303,6 +308,7 @@ export type BooleanFieldDef = {
 
 export type SelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
   readonly type: "select";
+  readonly description?: string;
   readonly options: TOptions;
   readonly required?: boolean;
   readonly sortable?: boolean;
@@ -327,6 +333,7 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
 // rejected Duplikate erst wenn Bedarf da ist.
 export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
   readonly type: "multiSelect";
+  readonly description?: string;
   readonly options: TOptions;
   readonly required?: boolean;
   readonly filterable?: boolean;
@@ -359,6 +366,7 @@ export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly st
  */
 export type NumberFieldDef = {
   readonly type: "number";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -390,6 +398,7 @@ export type NumberFieldDef = {
  */
 export type BigIntFieldDef = {
   readonly type: "bigInt";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -412,6 +421,7 @@ export type BigIntFieldDef = {
  */
 export type DecimalFieldDef = {
   readonly type: "decimal";
+  readonly description?: string;
   readonly precision: number;
   readonly scale: number;
   readonly required?: boolean;
@@ -424,6 +434,7 @@ export type DecimalFieldDef = {
 
 export type MoneyFieldDef = {
   readonly type: "money";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -446,6 +457,7 @@ export type MoneyFieldDef = {
 // ist ein menschlich-lesbares Feld wie "name", "title", "email".
 export type ReferenceFieldDef = {
   readonly type: "reference";
+  readonly description?: string;
   readonly entity: string;
   readonly required?: boolean;
   readonly filterable?: boolean;
@@ -528,6 +540,7 @@ export type EmbeddedDerivedCellDef = {
 
 export type EmbeddedFieldDef = {
   readonly type: "embedded";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sensitive?: boolean;
   readonly schema: Readonly<Record<string, EmbeddedSubFieldDef>>;
@@ -574,6 +587,7 @@ export type EmbeddedFieldDef = {
 // + NOT NULL, identisch zu embedded.
 export type JsonbFieldDef = {
   readonly type: "jsonb";
+  readonly description?: string;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
 } & ResolvedPiiFlags;
@@ -587,6 +601,7 @@ export type JsonbFieldDef = {
 // Siehe docs/plans/architecture/timezones.md
 export type DateFieldDef = {
   readonly type: "date";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -615,6 +630,7 @@ export type DateFieldDef = {
 // Feld statt eines lose verdrahteten Pairs (siehe LocatedTimestampFieldDef).
 export type TimestampFieldDef = {
   readonly type: "timestamp";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -645,6 +661,7 @@ export type TimestampFieldDef = {
 // (TEXT-Spalte) korrekt sind und der `locatedBy`-Marker eindeutig auflöst.
 export type TzFieldDef = {
   readonly type: "tz";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
@@ -670,6 +687,7 @@ export type TzFieldDef = {
 // Siehe docs/plans/architecture/timezones.md.
 export type LocatedTimestampFieldDef = {
   readonly type: "locatedTimestamp";
+  readonly description?: string;
   readonly required?: boolean;
   readonly sortable?: boolean;
   readonly filterable?: boolean;
@@ -687,6 +705,7 @@ export type LocatedTimestampFieldDef = {
 
 export type FileFieldDef = {
   readonly type: "file";
+  readonly description?: string;
   readonly required?: boolean;
   readonly maxSize?: string;
   readonly accept?: readonly string[];
@@ -695,6 +714,7 @@ export type FileFieldDef = {
 
 export type ImageFieldDef = {
   readonly type: "image";
+  readonly description?: string;
   readonly required?: boolean;
   readonly maxSize?: string;
   readonly accept?: readonly string[];
@@ -710,6 +730,7 @@ export type ImageFieldDef = {
 
 export type FilesFieldDef = {
   readonly type: "files";
+  readonly description?: string;
   readonly maxSize?: string;
   readonly accept?: readonly string[];
   readonly maxCount?: number;
@@ -718,6 +739,7 @@ export type FilesFieldDef = {
 
 export type ImagesFieldDef = {
   readonly type: "images";
+  readonly description?: string;
   readonly maxSize?: string;
   readonly accept?: readonly string[];
   readonly maxCount?: number;
@@ -921,4 +943,6 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
    * nameable as a column in a declarative `entityList`. See DerivedFieldDef.
    */
   readonly derivedFields?: DerivedFieldsMap;
+  /** Optional free-text semantics for the AI agent manifest — see TextFieldDef.description. */
+  readonly description?: string;
 };

package/src/handlers.ts

@@ -929,11 +929,27 @@ export type RateLimitOption = {
   readonly cost?: number;
 };
 
+export type AgentRisk = "low" | "mid" | "high";
+
+/** Per-handler hints for the AI-agent manifest. `expose` overrides the
+ *  default derived from `description`; `risk` overrides the per-kind default. */
+export type AgentHandlerHints = {
+  readonly expose?: boolean;
+  readonly risk?: AgentRisk;
+};
+
+export type AgentExposure = {
+  readonly expose: boolean;
+  readonly risk: AgentRisk;
+};
+
 export type WriteHandlerDef = {
   readonly name: string;
   readonly schema: ZodType;
   readonly handler: WriteHandlerFn;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
   // Set when the author wrote a `perform: stepsPipeline(...)` block. Boot-
@@ -951,6 +967,8 @@ export type QueryHandlerDef = {
   readonly schema: ZodType;
   readonly handler: QueryHandlerFn;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   /** Zod schema of the handler's actual return value — the paged envelope
    *  `{ rows, nextCursor, total? }` for a `definePagedQueryHandler`, or the

package/src/screen.ts

@@ -326,6 +326,7 @@ export type EntityListScreenDefinition = {
   readonly type: "entityList";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   readonly entity: string;
   readonly columns: readonly ListColumnSpec[];
   // Row renderer (Desktop) — when omitted, renderer draws the default table
@@ -404,6 +405,7 @@ export type ProjectionListScreenDefinition = {
   readonly type: "projectionList";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   readonly query: string;
   readonly columns: readonly ListColumnSpec[];
   readonly rowRenderer?: PlatformComponent;
@@ -464,6 +466,7 @@ export type ProjectionDetailScreenDefinition = {
   readonly type: "projectionDetail";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   readonly query: string;
   /** Query-payload key for the row-id. Default "id". */
   readonly idParam?: string;
@@ -632,6 +635,7 @@ export type DashboardScreenDefinition = {
   readonly type: "dashboard";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   readonly panels: readonly DashboardPanelDefinition[];
   readonly filter?: DashboardFilterDefinition;
   readonly slots?: ScreenSlots;
@@ -767,6 +771,7 @@ export type EntityEditScreenDefinition = {
   readonly type: "entityEdit";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   readonly entity: string;
   readonly layout: EditLayout;
   /** Optionaler i18n-Key (oder Roh-String) für den Submit-Button. Default
@@ -846,6 +851,7 @@ export type ActionFormScreenDefinition = {
   readonly type: "actionForm";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   /** Write-Handler-QN der bei Submit gerufen wird. Form-Object landet
    *  1:1 als payload — Handler-Schema (Zod) validiert weiter. */
   readonly handler: string;
@@ -901,6 +907,7 @@ export type CustomScreenDefinition = {
   readonly type: "custom";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   readonly renderer: PlatformComponent;
   readonly routes?: readonly CustomScreenRoute[];
   /** Parent list screen for breadcrumb when this detail is not in nav. */
@@ -956,6 +963,7 @@ export type ConfigEditScreenDefinition = {
   readonly type: "configEdit";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   /** scope für config:write:set Calls. Muss zur Scope-Deklaration der
    *  in `configKeys` referenzierten Keys passen — Boot-Validator
    *  prüft das gegen die Registry. */
@@ -998,6 +1006,7 @@ export type SecretsEditScreenDefinition = {
   readonly type: "secretsEdit";
   readonly nav?: ScreenNavSugar;
   readonly detailFor?: string;
+  readonly description?: string;
   /** field id -> qualified secret name (`<feature>:secret:<kebab>`). */
   readonly secretKeys: Readonly<Record<string, string>>;
   /** field id -> i18n key for the label. */
@@ -1035,10 +1044,10 @@ export type ScreenNavSugar = {
   readonly order?: number;
 };
 
-// `nav`/`detailFor` live directly on every variant (not only via this
+// `nav`/`detailFor`/`description` live directly on every variant (not only via this
 // union) so a screen typed as its own concrete kind — e.g. `const screen:
 // CustomScreenDefinition = {...}` in a module split out of `feature.ts` —
-// still accepts both fields; a union-only intersection drops them the
+// still accepts all three; a union-only intersection drops them the
 // moment a caller narrows to one member.
 //
 // `detailFor` applies to any screen kind because any kind can be the