@ikenga/contract 0.13.0 → 0.14.0

package/dist/host-context.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * Identity of the human operating the shell, injected into `hostContext` at
+ * the AppBridge handshake (`buildHostContext()` in
+ * `shell/src/lib/pkg/host-context.ts`, cast in alongside `royaltiSuite` /
+ * `supabase` / `secrets`). Host-injected, not pkg-declared — there is no
+ * manifest capability gate for it.
+ *
+ * Currently sourced from the free-text onboarding `userName` (shell store),
+ * falling back to the OS username when unset. Treat `id` as a stable
+ * display label, NOT a durable account id or an auth subject.
+ */
+export declare const OperatorIdentitySchema: z.ZodObject<{
+    /** Stable-enough identifier for the operator (today: `userName` or an
+     *  OS-username fallback). Not an auth subject. */
+    id: z.ZodString;
+    /** Human-friendly label, when it differs from `id`. */
+    displayName: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    displayName?: string | undefined;
+}, {
+    id: string;
+    displayName?: string | undefined;
+}>;
+export type OperatorIdentity = z.infer<typeof OperatorIdentitySchema>;
+/**
+ * hostContext fields Ikenga casts onto the MCP-UI-Apps `McpUiHostContext`
+ * base type (imported from `@modelcontextprotocol/ext-apps/app-bridge` —
+ * this package does not redefine that base type, only the Ikenga-specific
+ * extensions layered onto it).
+ *
+ * `operator` is OPTIONAL: older shells and the initial handshake before the
+ * onboarding step has run won't send it. A consumer MUST treat an absent
+ * `operator` as an UNKNOWN operator and fail SAFE — e.g. use a confirming
+ * `ux_mode` ('confirm') rather than auto-approving an operator-scoped
+ * action — never assume a default identity.
+ */
+export interface IkengaHostContextExtensions {
+    operator?: OperatorIdentity;
+}
+//# sourceMappingURL=host-context.d.ts.map

package/dist/host-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-context.d.ts","sourceRoot":"","sources":["../src/host-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB;IAE/B;sDACkD;;IAElD,uDAAuD;;;;;;;;EAGhD,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B"}

package/dist/host-context.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/**
+ * Identity of the human operating the shell, injected into `hostContext` at
+ * the AppBridge handshake (`buildHostContext()` in
+ * `shell/src/lib/pkg/host-context.ts`, cast in alongside `royaltiSuite` /
+ * `supabase` / `secrets`). Host-injected, not pkg-declared — there is no
+ * manifest capability gate for it.
+ *
+ * Currently sourced from the free-text onboarding `userName` (shell store),
+ * falling back to the OS username when unset. Treat `id` as a stable
+ * display label, NOT a durable account id or an auth subject.
+ */
+export const OperatorIdentitySchema = z
+    .object({
+    /** Stable-enough identifier for the operator (today: `userName` or an
+     *  OS-username fallback). Not an auth subject. */
+    id: z.string(),
+    /** Human-friendly label, when it differs from `id`. */
+    displayName: z.string().optional(),
+})
+    .strict();
+//# sourceMappingURL=host-context.js.map

package/dist/host-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-context.js","sourceRoot":"","sources":["../src/host-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN;sDACkD;IAClD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,uDAAuD;IACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './browser.js';
 export * from './pa-actions.js';
 export * from './window.js';
 export * from './action-frontmatter.js';
+export * from './host-context.js';
 /** This package's own version. */
 export declare const CONTRACT_PACKAGE_VERSION: "0.5.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AAExC,kCAAkC;AAClC,eAAO,MAAM,wBAAwB,EAAG,OAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAElC,kCAAkC;AAClC,eAAO,MAAM,wBAAwB,EAAG,OAAgB,CAAC"}

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './browser.js';
 export * from './pa-actions.js';
 export * from './window.js';
 export * from './action-frontmatter.js';
+export * from './host-context.js';
 /** This package's own version. */
 export const CONTRACT_PACKAGE_VERSION = '0.5.0';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AAExC,kCAAkC;AAClC,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAElC,kCAAkC;AAClC,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikenga/contract",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Shared contract for the Ikenga pkg system: manifest schema, RPC types, Engine interface, capability scopes.",
   "license": "Apache-2.0",
   "repository": {
@@ -63,6 +63,10 @@
     "./action-frontmatter": {
       "types": "./dist/action-frontmatter.d.ts",
       "import": "./dist/action-frontmatter.js"
+    },
+    "./host-context": {
+      "types": "./dist/host-context.d.ts",
+      "import": "./dist/host-context.js"
     }
   },
   "files": [

package/src/host-context.test.ts

@@ -0,0 +1,24 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { OperatorIdentitySchema } from './host-context.js';
+
+test('OperatorIdentity: id-only parses, displayName optional', () => {
+  const o = OperatorIdentitySchema.parse({ id: 'nedjamez' });
+  assert.equal(o.id, 'nedjamez');
+  assert.equal(o.displayName, undefined);
+});
+
+test('OperatorIdentity: full shape parses', () => {
+  const o = OperatorIdentitySchema.parse({ id: 'nedjamez', displayName: 'Chinedum' });
+  assert.equal(o.id, 'nedjamez');
+  assert.equal(o.displayName, 'Chinedum');
+});
+
+test('OperatorIdentity: rejects unknown field (.strict)', () => {
+  assert.throws(() => OperatorIdentitySchema.parse({ id: 'nedjamez', bogus: true }));
+});
+
+test('OperatorIdentity: rejects missing id', () => {
+  assert.throws(() => OperatorIdentitySchema.parse({ displayName: 'Chinedum' }));
+});

package/src/host-context.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+/**
+ * Identity of the human operating the shell, injected into `hostContext` at
+ * the AppBridge handshake (`buildHostContext()` in
+ * `shell/src/lib/pkg/host-context.ts`, cast in alongside `royaltiSuite` /
+ * `supabase` / `secrets`). Host-injected, not pkg-declared — there is no
+ * manifest capability gate for it.
+ *
+ * Currently sourced from the free-text onboarding `userName` (shell store),
+ * falling back to the OS username when unset. Treat `id` as a stable
+ * display label, NOT a durable account id or an auth subject.
+ */
+export const OperatorIdentitySchema = z
+  .object({
+    /** Stable-enough identifier for the operator (today: `userName` or an
+     *  OS-username fallback). Not an auth subject. */
+    id: z.string(),
+    /** Human-friendly label, when it differs from `id`. */
+    displayName: z.string().optional(),
+  })
+  .strict();
+export type OperatorIdentity = z.infer<typeof OperatorIdentitySchema>;
+
+/**
+ * hostContext fields Ikenga casts onto the MCP-UI-Apps `McpUiHostContext`
+ * base type (imported from `@modelcontextprotocol/ext-apps/app-bridge` —
+ * this package does not redefine that base type, only the Ikenga-specific
+ * extensions layered onto it).
+ *
+ * `operator` is OPTIONAL: older shells and the initial handshake before the
+ * onboarding step has run won't send it. A consumer MUST treat an absent
+ * `operator` as an UNKNOWN operator and fail SAFE — e.g. use a confirming
+ * `ux_mode` ('confirm') rather than auto-approving an operator-scoped
+ * action — never assume a default identity.
+ */
+export interface IkengaHostContextExtensions {
+  operator?: OperatorIdentity;
+}

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './browser.js';
 export * from './pa-actions.js';
 export * from './window.js';
 export * from './action-frontmatter.js';
+export * from './host-context.js';
 
 /** This package's own version. */
 export const CONTRACT_PACKAGE_VERSION = '0.5.0' as const;