@volter-ai-dev/supercode-ui 0.1.65 → 0.1.67

package/README.md

@@ -243,6 +243,11 @@ heartbeat churn, treats compaction as a new baseline, and returns the delay for
 settlement timer. This keeps unread and finished semantics identical in an editor, extension,
 desktop app, or mobile companion without moving file persistence into the UI package.
 
+`createNativeMessengerState` wraps that ledger with bounded per-conversation drafts and per-harness
+Terminal/Headless preferences. It emits one serializable snapshot, so native hosts do not need to
+duplicate state parsing or coordinate several independent maps. The host still owns where that
+snapshot is stored, its debounce and encryption policy, and any multi-device synchronization.
+
 Native continuation exposes one action and a quiet execution-transport selector. A host with a real
 terminal provider can add `terminal` to `continuationModes` and handle `onResumeTerminal`; Terminal
 is then the initial choice and Headless remains available from the selector. The UI never infers

package/activity.mjs

@@ -66,7 +66,12 @@ var EMPTY_UI_STATE = Object.freeze({
   subagentInspector: null,
   attached: null,
   owned: null,
-  attachError: null
+  attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null
 });
 var ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool", "reasoning", "request", "notice"]);
 var MODES = /* @__PURE__ */ new Set(["none", "control", "mirror"]);
@@ -79,6 +84,10 @@ var AUTHENTICATION_PHASES = /* @__PURE__ */ new Set(["idle", "checking", "requir
 var MAX_TOOL_FIELDS = 8;
 var MAX_TOOL_FIELD_CHARS = 800;
 var MAX_TOOL_PREVIEW_CHARS = 4e3;
+var MAX_CONTRIBUTIONS = 64;
+var MAX_CONTRIBUTION_JSON_DEPTH = 12;
+var MAX_CONTRIBUTION_COLLECTION = 100;
+var MAX_CONTRIBUTION_STRING_CHARS = 16e3;
 function record(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -111,6 +120,126 @@ function number(value, fallback = 0) {
 function nullableNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function relativeContributionPath(value) {
+  if (typeof value !== "string" || value.startsWith("/") || /^[a-z]:[\\/]/i.test(value)) return null;
+  return value.replaceAll("\\", "/").split("/").some((segment) => segment === "..") ? null : boundedString(value, 1e3);
+}
+function contributionJson(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return typeof value === "string" ? boundedString(value, MAX_CONTRIBUTION_STRING_CHARS) : value;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+  if (depth >= MAX_CONTRIBUTION_JSON_DEPTH || !value || typeof value !== "object" || seen.has(value)) {
+    return void 0;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result2 = [];
+    for (const item of value.slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+      const normalized = contributionJson(item, depth + 1, seen);
+      if (normalized !== void 0) result2.push(normalized);
+    }
+    seen.delete(value);
+    return result2;
+  }
+  const source = record(value);
+  if (!source) return void 0;
+  const result = {};
+  for (const [key, item] of Object.entries(source).slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+    const normalized = contributionJson(item, depth + 1, seen);
+    if (normalized !== void 0) result[boundedString(key, 200)] = normalized;
+  }
+  seen.delete(value);
+  return result;
+}
+function normalizeContributions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, MAX_CONTRIBUTIONS).flatMap((candidate) => {
+    const item = record(candidate);
+    const placement = record(item?.placement);
+    const source = relativeContributionPath(item?.source);
+    if (item?.schema !== "supercode/contribution-v1" || typeof item.id !== "string" || !item.id.trim() || typeof item.kind !== "string" || !item.kind.trim() || source === null) return [];
+    const data = contributionJson(item.data);
+    if (data === void 0) return [];
+    return [{
+      schema: "supercode/contribution-v1",
+      id: boundedString(item.id, 200),
+      kind: boundedString(item.kind, 100),
+      ...typeof item.title === "string" ? { title: boundedString(item.title, 500) } : {},
+      ...placement ? { placement: {
+        ...typeof placement.surface === "string" ? { surface: boundedString(placement.surface, 100) } : {},
+        ...typeof placement.region === "string" ? { region: boundedString(placement.region, 100) } : {}
+      } } : {},
+      data,
+      source
+    }];
+  });
+}
+function readAgentPackage(value) {
+  const agentPackage = record(value);
+  const capabilities = record(agentPackage?.capabilities);
+  const storage = record(agentPackage?.storage);
+  const relativePath = relativeContributionPath(storage?.relativePath);
+  if (agentPackage?.schemaVersion !== 1 || typeof agentPackage.id !== "string" || typeof agentPackage.name !== "string" || typeof agentPackage.version !== "string" || !capabilities || !Array.isArray(capabilities.required) || !Array.isArray(capabilities.optional) || !storage || relativePath === null) return null;
+  const resources = record(agentPackage.resources);
+  return {
+    id: boundedString(agentPackage.id, 200),
+    name: boundedString(agentPackage.name, 500),
+    version: boundedString(agentPackage.version, 100),
+    description: typeof agentPackage.description === "string" ? boundedString(agentPackage.description, 2e3) : null,
+    capabilities: {
+      required: capabilities.required.filter((item) => typeof item === "string").slice(0, 100).map((item) => boundedString(item, 200)),
+      optional: capabilities.optional.filter((item) => typeof item === "string").slice(0, 100).map((item) => boundedString(item, 200))
+    },
+    storage: { relativePath },
+    resources: resources ? Object.fromEntries(Object.entries(resources).flatMap(([id, candidate]) => {
+      const state = record(candidate);
+      if (state?.schema !== "supercode/package-resource-state-v1") return [];
+      if (state.status === "absent" && typeof state.contributionId === "string") {
+        return [[boundedString(id, 200), {
+          schema: "supercode/package-resource-state-v1",
+          status: "absent",
+          contributionId: boundedString(state.contributionId, 200)
+        }]];
+      }
+      if (state.status === "error" && typeof state.contributionId === "string" && typeof state.message === "string") {
+        return [[boundedString(id, 200), {
+          schema: "supercode/package-resource-state-v1",
+          status: "error",
+          contributionId: boundedString(state.contributionId, 200),
+          message: boundedString(state.message)
+        }]];
+      }
+      const resource = record(state?.resource);
+      const data = contributionJson(resource?.data);
+      if (state?.status !== "ready" || resource?.schema !== "supercode/package-resource-v1" || typeof resource.contributionId !== "string" || !["json", "text"].includes(resource.format) || typeof resource.mediaType !== "string" || data === void 0) return [];
+      return [[boundedString(id, 200), {
+        schema: "supercode/package-resource-state-v1",
+        status: "ready",
+        resource: {
+          schema: "supercode/package-resource-v1",
+          contributionId: boundedString(resource.contributionId, 200),
+          format: resource.format,
+          mediaType: boundedString(resource.mediaType, 200),
+          data
+        }
+      }]];
+    })) : {}
+  };
+}
+function readAgentPackageCapabilityState(value) {
+  const state = record(value);
+  if (!state) return null;
+  const fields = ["availableRequired", "missingRequired", "enabledOptional", "unavailableOptional"];
+  if (!fields.every((field) => Array.isArray(state[field]))) return null;
+  return {
+    ready: state.ready === true,
+    ...Object.fromEntries(fields.map((field) => [
+      field,
+      state[field].filter((item) => typeof item === "string").slice(0, 100).map((item) => boundedString(item, 200))
+    ]))
+  };
+}
 function boundedString(value, max = 2e3) {
   if (typeof value !== "string") return "";
   return value.length <= max ? value : `${value.slice(0, max)}\u2026`;
@@ -819,7 +948,12 @@ function normalizeUiState(value) {
     subagentInspector: readSubagentInspector(raw.subagentInspector),
     attached: readAttached(raw.attached),
     owned: readAttached(raw.owned),
-    attachError: attachError && typeof attachError.key === "string" && typeof attachError.message === "string" ? { key: attachError.key, message: attachError.message } : null
+    attachError: attachError && typeof attachError.key === "string" && typeof attachError.message === "string" ? { key: attachError.key, message: attachError.message } : null,
+    agentPackage: readAgentPackage(raw.agentPackage),
+    contributions: normalizeContributions(raw.contributions),
+    agentPackageError: typeof raw.agentPackageError === "string" ? boundedString(raw.agentPackageError) : null,
+    agentPackageCapabilityState: readAgentPackageCapabilityState(raw.agentPackageCapabilityState),
+    agentPackageCapabilityError: typeof raw.agentPackageCapabilityError === "string" ? boundedString(raw.agentPackageCapabilityError) : null
   };
 }
 function harnessDisplayName(id) {

package/components.mjs

@@ -69,7 +69,12 @@ var EMPTY_UI_STATE = Object.freeze({
   subagentInspector: null,
   attached: null,
   owned: null,
-  attachError: null
+  attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null
 });
 var ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool", "reasoning", "request", "notice"]);
 var MODES = /* @__PURE__ */ new Set(["none", "control", "mirror"]);
@@ -82,6 +87,10 @@ var AUTHENTICATION_PHASES = /* @__PURE__ */ new Set(["idle", "checking", "requir
 var MAX_TOOL_FIELDS = 8;
 var MAX_TOOL_FIELD_CHARS = 800;
 var MAX_TOOL_PREVIEW_CHARS = 4e3;
+var MAX_CONTRIBUTIONS = 64;
+var MAX_CONTRIBUTION_JSON_DEPTH = 12;
+var MAX_CONTRIBUTION_COLLECTION = 100;
+var MAX_CONTRIBUTION_STRING_CHARS = 16e3;
 function record(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -114,6 +123,126 @@ function number(value, fallback = 0) {
 function nullableNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function relativeContributionPath(value) {
+  if (typeof value !== "string" || value.startsWith("/") || /^[a-z]:[\\/]/i.test(value)) return null;
+  return value.replaceAll("\\", "/").split("/").some((segment) => segment === "..") ? null : boundedString(value, 1e3);
+}
+function contributionJson(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return typeof value === "string" ? boundedString(value, MAX_CONTRIBUTION_STRING_CHARS) : value;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+  if (depth >= MAX_CONTRIBUTION_JSON_DEPTH || !value || typeof value !== "object" || seen.has(value)) {
+    return void 0;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result2 = [];
+    for (const item of value.slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+      const normalized = contributionJson(item, depth + 1, seen);
+      if (normalized !== void 0) result2.push(normalized);
+    }
+    seen.delete(value);
+    return result2;
+  }
+  const source = record(value);
+  if (!source) return void 0;
+  const result = {};
+  for (const [key, item] of Object.entries(source).slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+    const normalized = contributionJson(item, depth + 1, seen);
+    if (normalized !== void 0) result[boundedString(key, 200)] = normalized;
+  }
+  seen.delete(value);
+  return result;
+}
+function normalizeContributions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, MAX_CONTRIBUTIONS).flatMap((candidate) => {
+    const item = record(candidate);
+    const placement = record(item?.placement);
+    const source = relativeContributionPath(item?.source);
+    if (item?.schema !== "supercode/contribution-v1" || typeof item.id !== "string" || !item.id.trim() || typeof item.kind !== "string" || !item.kind.trim() || source === null) return [];
+    const data = contributionJson(item.data);
+    if (data === void 0) return [];
+    return [{
+      schema: "supercode/contribution-v1",
+      id: boundedString(item.id, 200),
+      kind: boundedString(item.kind, 100),
+      ...typeof item.title === "string" ? { title: boundedString(item.title, 500) } : {},
+      ...placement ? { placement: {
+        ...typeof placement.surface === "string" ? { surface: boundedString(placement.surface, 100) } : {},
+        ...typeof placement.region === "string" ? { region: boundedString(placement.region, 100) } : {}
+      } } : {},
+      data,
+      source
+    }];
+  });
+}
+function readAgentPackage(value) {
+  const agentPackage = record(value);
+  const capabilities = record(agentPackage?.capabilities);
+  const storage = record(agentPackage?.storage);
+  const relativePath = relativeContributionPath(storage?.relativePath);
+  if (agentPackage?.schemaVersion !== 1 || typeof agentPackage.id !== "string" || typeof agentPackage.name !== "string" || typeof agentPackage.version !== "string" || !capabilities || !Array.isArray(capabilities.required) || !Array.isArray(capabilities.optional) || !storage || relativePath === null) return null;
+  const resources = record(agentPackage.resources);
+  return {
+    id: boundedString(agentPackage.id, 200),
+    name: boundedString(agentPackage.name, 500),
+    version: boundedString(agentPackage.version, 100),
+    description: typeof agentPackage.description === "string" ? boundedString(agentPackage.description, 2e3) : null,
+    capabilities: {
+      required: capabilities.required.filter((item) => typeof item === "string").slice(0, 100).map((item) => boundedString(item, 200)),
+      optional: capabilities.optional.filter((item) => typeof item === "string").slice(0, 100).map((item) => boundedString(item, 200))
+    },
+    storage: { relativePath },
+    resources: resources ? Object.fromEntries(Object.entries(resources).flatMap(([id, candidate]) => {
+      const state = record(candidate);
+      if (state?.schema !== "supercode/package-resource-state-v1") return [];
+      if (state.status === "absent" && typeof state.contributionId === "string") {
+        return [[boundedString(id, 200), {
+          schema: "supercode/package-resource-state-v1",
+          status: "absent",
+          contributionId: boundedString(state.contributionId, 200)
+        }]];
+      }
+      if (state.status === "error" && typeof state.contributionId === "string" && typeof state.message === "string") {
+        return [[boundedString(id, 200), {
+          schema: "supercode/package-resource-state-v1",
+          status: "error",
+          contributionId: boundedString(state.contributionId, 200),
+          message: boundedString(state.message)
+        }]];
+      }
+      const resource = record(state?.resource);
+      const data = contributionJson(resource?.data);
+      if (state?.status !== "ready" || resource?.schema !== "supercode/package-resource-v1" || typeof resource.contributionId !== "string" || !["json", "text"].includes(resource.format) || typeof resource.mediaType !== "string" || data === void 0) return [];
+      return [[boundedString(id, 200), {
+        schema: "supercode/package-resource-state-v1",
+        status: "ready",
+        resource: {
+          schema: "supercode/package-resource-v1",
+          contributionId: boundedString(resource.contributionId, 200),
+          format: resource.format,
+          mediaType: boundedString(resource.mediaType, 200),
+          data
+        }
+      }]];
+    })) : {}
+  };
+}
+function readAgentPackageCapabilityState(value) {
+  const state = record(value);
+  if (!state) return null;
+  const fields = ["availableRequired", "missingRequired", "enabledOptional", "unavailableOptional"];
+  if (!fields.every((field) => Array.isArray(state[field]))) return null;
+  return {
+    ready: state.ready === true,
+    ...Object.fromEntries(fields.map((field) => [
+      field,
+      state[field].filter((item) => typeof item === "string").slice(0, 100).map((item) => boundedString(item, 200))
+    ]))
+  };
+}
 function relativeAge(updatedAt, now = Date.now()) {
   if (typeof updatedAt !== "number" || !Number.isFinite(updatedAt) || updatedAt <= 0) return "";
   const delta = Math.max(0, now - updatedAt);
@@ -831,7 +960,12 @@ function normalizeUiState(value) {
     subagentInspector: readSubagentInspector(raw.subagentInspector),
     attached: readAttached(raw.attached),
     owned: readAttached(raw.owned),
-    attachError: attachError && typeof attachError.key === "string" && typeof attachError.message === "string" ? { key: attachError.key, message: attachError.message } : null
+    attachError: attachError && typeof attachError.key === "string" && typeof attachError.message === "string" ? { key: attachError.key, message: attachError.message } : null,
+    agentPackage: readAgentPackage(raw.agentPackage),
+    contributions: normalizeContributions(raw.contributions),
+    agentPackageError: typeof raw.agentPackageError === "string" ? boundedString(raw.agentPackageError) : null,
+    agentPackageCapabilityState: readAgentPackageCapabilityState(raw.agentPackageCapabilityState),
+    agentPackageCapabilityError: typeof raw.agentPackageCapabilityError === "string" ? boundedString(raw.agentPackageCapabilityError) : null
   };
 }
 function harnessDisplayName(id) {

package/composer.mjs

@@ -69,7 +69,12 @@ var EMPTY_UI_STATE = Object.freeze({
   subagentInspector: null,
   attached: null,
   owned: null,
-  attachError: null
+  attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null
 });
 function harnessDisplayName(id) {
   return HARNESS_NAMES[id] ?? id;

package/controller.mjs

@@ -608,6 +608,11 @@ function projectClientSnapshotInternal(snapshot, options, imageRegistry) {
     reductionReceipt: options.reductionReceipt ?? snapshot.reductionReceipt ?? null,
     interopSettings: snapshot.interopSettings ?? null,
     interopSettingsError: snapshot.interopSettingsError ?? null,
+    agentPackage: snapshot.agentPackage ?? null,
+    contributions: snapshot.agentPackage?.contributions ?? [],
+    agentPackageError: snapshot.agentPackageError ?? null,
+    agentPackageCapabilityState: snapshot.agentPackageCapabilityState ?? null,
+    agentPackageCapabilityError: snapshot.agentPackageCapabilityError ?? null,
     error: snapshot.error?.message ?? null,
     recoverable: snapshot.error?.recoverable === true,
     harnesses: (snapshot.harnesses ?? []).map((harness) => ({

package/conversation.mjs

@@ -70,7 +70,12 @@ var EMPTY_UI_STATE = Object.freeze({
   subagentInspector: null,
   attached: null,
   owned: null,
-  attachError: null
+  attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null
 });
 var TOOL_CATEGORIES = /* @__PURE__ */ new Set(["read", "search", "edit", "command", "test", "web", "agent", "plan", "other"]);
 var MAX_TOOL_FIELDS = 8;

package/core.d.ts

@@ -1,6 +1,11 @@
 export type {
   AttachedSessionModel,
   AgentActivityModel,
+  AgentContributionModel,
+  AgentPackageModel,
+  AgentPackageResourceModel,
+  AgentPackageResourceStateModel,
+  AgentPackageCapabilityStateModel,
   ContinuationMode,
   ControlStrategy,
   HarnessId,
@@ -36,6 +41,7 @@ export {
   groupConversation,
   harnessDisplayName,
   isSendKey,
+  normalizeContributions,
   normalizeUiState,
   operationLabel,
   projectAgentActivity,
@@ -43,6 +49,7 @@ export {
   relativeAge,
   sessionActivity,
   sessionDisplayName,
+  selectContributions,
   terminalCommand,
   toolCategory,
   toolTarget,

package/core.mjs

@@ -68,6 +68,11 @@ export const EMPTY_UI_STATE = Object.freeze({
   attached: null,
   owned: null,
   attachError: null,
+  agentPackage: null,
+  contributions: Object.freeze([]),
+  agentPackageError: null,
+  agentPackageCapabilityState: null,
+  agentPackageCapabilityError: null,
 });
 
 const ROLES = new Set(['system', 'user', 'assistant', 'tool', 'reasoning', 'request', 'notice']);
@@ -81,6 +86,10 @@ const AUTHENTICATION_PHASES = new Set(['idle', 'checking', 'required', 'configur
 const MAX_TOOL_FIELDS = 8;
 const MAX_TOOL_FIELD_CHARS = 800;
 const MAX_TOOL_PREVIEW_CHARS = 4_000;
+const MAX_CONTRIBUTIONS = 64;
+const MAX_CONTRIBUTION_JSON_DEPTH = 12;
+const MAX_CONTRIBUTION_COLLECTION = 100;
+const MAX_CONTRIBUTION_STRING_CHARS = 16_000;
 
 function record(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
@@ -121,6 +130,165 @@ function nullableNumber(value) {
   return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
 
+function relativeContributionPath(value) {
+  if (typeof value !== 'string' || value.startsWith('/') || /^[a-z]:[\\/]/i.test(value)) return null;
+  return value.replaceAll('\\', '/').split('/').some((segment) => segment === '..')
+    ? null
+    : boundedString(value, 1_000);
+}
+
+function contributionJson(value, depth = 0, seen = new WeakSet()) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return typeof value === 'string' ? boundedString(value, MAX_CONTRIBUTION_STRING_CHARS) : value;
+  }
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (depth >= MAX_CONTRIBUTION_JSON_DEPTH || !value || typeof value !== 'object' || seen.has(value)) {
+    return undefined;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = [];
+    for (const item of value.slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+      const normalized = contributionJson(item, depth + 1, seen);
+      if (normalized !== undefined) result.push(normalized);
+    }
+    seen.delete(value);
+    return result;
+  }
+  const source = record(value);
+  if (!source) return undefined;
+  const result = {};
+  for (const [key, item] of Object.entries(source).slice(0, MAX_CONTRIBUTION_COLLECTION)) {
+    const normalized = contributionJson(item, depth + 1, seen);
+    if (normalized !== undefined) result[boundedString(key, 200)] = normalized;
+  }
+  seen.delete(value);
+  return result;
+}
+
+export function normalizeContributions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, MAX_CONTRIBUTIONS).flatMap((candidate) => {
+    const item = record(candidate);
+    const placement = record(item?.placement);
+    const source = relativeContributionPath(item?.source);
+    if (
+      item?.schema !== 'supercode/contribution-v1' ||
+      typeof item.id !== 'string' || !item.id.trim() ||
+      typeof item.kind !== 'string' || !item.kind.trim() ||
+      source === null
+    ) return [];
+    const data = contributionJson(item.data);
+    if (data === undefined) return [];
+    return [{
+      schema: 'supercode/contribution-v1',
+      id: boundedString(item.id, 200),
+      kind: boundedString(item.kind, 100),
+      ...(typeof item.title === 'string' ? { title: boundedString(item.title, 500) } : {}),
+      ...(placement ? { placement: {
+        ...(typeof placement.surface === 'string' ? { surface: boundedString(placement.surface, 100) } : {}),
+        ...(typeof placement.region === 'string' ? { region: boundedString(placement.region, 100) } : {}),
+      } } : {}),
+      data,
+      source,
+    }];
+  });
+}
+
+export function selectContributions(contributions, query = {}) {
+  return normalizeContributions(contributions).filter((contribution) => (
+    (query.kind === undefined || contribution.kind === query.kind) &&
+    (query.surface === undefined || contribution.placement?.surface === query.surface) &&
+    (query.region === undefined || contribution.placement?.region === query.region)
+  ));
+}
+
+function readAgentPackage(value) {
+  const agentPackage = record(value);
+  const capabilities = record(agentPackage?.capabilities);
+  const storage = record(agentPackage?.storage);
+  const relativePath = relativeContributionPath(storage?.relativePath);
+  if (
+    agentPackage?.schemaVersion !== 1 ||
+    typeof agentPackage.id !== 'string' ||
+    typeof agentPackage.name !== 'string' ||
+    typeof agentPackage.version !== 'string' ||
+    !capabilities ||
+    !Array.isArray(capabilities.required) ||
+    !Array.isArray(capabilities.optional) ||
+    !storage ||
+    relativePath === null
+  ) return null;
+  const resources = record(agentPackage.resources);
+  return {
+    id: boundedString(agentPackage.id, 200),
+    name: boundedString(agentPackage.name, 500),
+    version: boundedString(agentPackage.version, 100),
+    description: typeof agentPackage.description === 'string'
+      ? boundedString(agentPackage.description, 2_000)
+      : null,
+    capabilities: {
+      required: capabilities.required.filter((item) => typeof item === 'string').slice(0, 100).map((item) => boundedString(item, 200)),
+      optional: capabilities.optional.filter((item) => typeof item === 'string').slice(0, 100).map((item) => boundedString(item, 200)),
+    },
+    storage: { relativePath },
+    resources: resources ? Object.fromEntries(Object.entries(resources).flatMap(([id, candidate]) => {
+      const state = record(candidate);
+      if (state?.schema !== 'supercode/package-resource-state-v1') return [];
+      if (state.status === 'absent' && typeof state.contributionId === 'string') {
+        return [[boundedString(id, 200), {
+          schema: 'supercode/package-resource-state-v1',
+          status: 'absent',
+          contributionId: boundedString(state.contributionId, 200),
+        }]];
+      }
+      if (state.status === 'error' && typeof state.contributionId === 'string' && typeof state.message === 'string') {
+        return [[boundedString(id, 200), {
+          schema: 'supercode/package-resource-state-v1',
+          status: 'error',
+          contributionId: boundedString(state.contributionId, 200),
+          message: boundedString(state.message),
+        }]];
+      }
+      const resource = record(state?.resource);
+      const data = contributionJson(resource?.data);
+      if (
+        state?.status !== 'ready' ||
+        resource?.schema !== 'supercode/package-resource-v1' ||
+        typeof resource.contributionId !== 'string' ||
+        !['json', 'text'].includes(resource.format) ||
+        typeof resource.mediaType !== 'string' ||
+        data === undefined
+      ) return [];
+      return [[boundedString(id, 200), {
+        schema: 'supercode/package-resource-state-v1',
+        status: 'ready',
+        resource: {
+          schema: 'supercode/package-resource-v1',
+          contributionId: boundedString(resource.contributionId, 200),
+          format: resource.format,
+          mediaType: boundedString(resource.mediaType, 200),
+          data,
+        },
+      }]];
+    })) : {},
+  };
+}
+
+function readAgentPackageCapabilityState(value) {
+  const state = record(value);
+  if (!state) return null;
+  const fields = ['availableRequired', 'missingRequired', 'enabledOptional', 'unavailableOptional'];
+  if (!fields.every((field) => Array.isArray(state[field]))) return null;
+  return {
+    ready: state.ready === true,
+    ...Object.fromEntries(fields.map((field) => [
+      field,
+      state[field].filter((item) => typeof item === 'string').slice(0, 100).map((item) => boundedString(item, 200)),
+    ])),
+  };
+}
+
 export function relativeAge(updatedAt, now = Date.now()) {
   if (typeof updatedAt !== 'number' || !Number.isFinite(updatedAt) || updatedAt <= 0) return '';
   const delta = Math.max(0, now - updatedAt);
@@ -896,6 +1064,13 @@ export function normalizeUiState(value) {
     attached: readAttached(raw.attached),
     owned: readAttached(raw.owned),
     attachError: attachError && typeof attachError.key === 'string' && typeof attachError.message === 'string' ? { key: attachError.key, message: attachError.message } : null,
+    agentPackage: readAgentPackage(raw.agentPackage),
+    contributions: normalizeContributions(raw.contributions),
+    agentPackageError: typeof raw.agentPackageError === 'string' ? boundedString(raw.agentPackageError) : null,
+    agentPackageCapabilityState: readAgentPackageCapabilityState(raw.agentPackageCapabilityState),
+    agentPackageCapabilityError: typeof raw.agentPackageCapabilityError === 'string'
+      ? boundedString(raw.agentPackageCapabilityError)
+      : null,
   };
 }