@volter-ai-dev/supercode-ui 0.1.66 → 0.1.68

package/index.d.ts

@@ -10,6 +10,51 @@ export type ExecutionMode = 'headless' | 'terminal';
 export type ContinuationMode = ExecutionMode;
 export type SessionActivity = 'idle' | 'recent' | 'running' | 'working' | 'needs-input' | 'finished' | 'failed' | 'unseen';
 
+export type ContributionJson = null | boolean | number | string | ContributionJson[] | { [key: string]: ContributionJson };
+
+export interface AgentContributionModel {
+  schema: 'supercode/contribution-v1';
+  id: string;
+  kind: string;
+  title?: string;
+  placement?: { surface?: string; region?: string };
+  data: ContributionJson;
+  /** Workspace-relative declaration path; never an absolute host path. */
+  source: string;
+}
+
+export interface AgentPackageModel {
+  id: string;
+  name: string;
+  version: string;
+  description: string | null;
+  capabilities: { required: string[]; optional: string[] };
+  /** Workspace-relative durable data location. */
+  storage: { relativePath: string };
+  resources: Record<string, AgentPackageResourceStateModel>;
+}
+
+export interface AgentPackageResourceModel {
+  schema: 'supercode/package-resource-v1';
+  contributionId: string;
+  format: 'json' | 'text';
+  mediaType: string;
+  data: ContributionJson;
+}
+
+export type AgentPackageResourceStateModel =
+  | { schema: 'supercode/package-resource-state-v1'; status: 'ready'; resource: AgentPackageResourceModel }
+  | { schema: 'supercode/package-resource-state-v1'; status: 'absent'; contributionId: string }
+  | { schema: 'supercode/package-resource-state-v1'; status: 'error'; contributionId: string; message: string };
+
+export interface AgentPackageCapabilityStateModel {
+  ready: boolean;
+  availableRequired: string[];
+  missingRequired: string[];
+  enabledOptional: string[];
+  unavailableOptional: string[];
+}
+
 export interface AgentActivityModel {
   harness: HarnessId | '';
   sessionKey: string | null;
@@ -45,6 +90,66 @@ export interface HarnessOption {
   preferredLaunchMode?: ExecutionMode | null;
 }
 
+/** UNI-8: whose conversation a session is. */
+export interface ParticipantModel {
+  kind: 'local-user' | 'foreign' | 'unknown';
+  /** The human ("@jane"), when known. */
+  label: string | null;
+  /** The surface the participant reached the agent through ("slack", "acp", ...). */
+  origin: string | null;
+}
+
+/** UNI-9: a typed workspace. `none` is a first-class value, not an empty path. */
+export interface WorkspaceRefModel {
+  kind: 'repo' | 'none' | 'channel';
+  /** Path for `repo`, channel label for `channel`, null for `none`. */
+  value: string | null;
+}
+
+/** UNI-10: a bounded/truncated mirror of a session canonical in another store. */
+export interface MirrorModel {
+  canonicalHarness: HarnessId;
+  /** Session key to cross-link to, when the host can resolve it. */
+  canonicalKey: string | null;
+  bounded: boolean;
+  truncated: boolean;
+  origin: string | null;
+}
+
+/** UNI-11: which surface holds this session now; take-over is the transition. */
+export interface HolderModel {
+  /** 'supercode' = held here; any other string = that surface; null = unheld. */
+  surface: string | null;
+  /** Take-over offered (flows through confirmIntent with action 'take_over'). */
+  canTakeOver: boolean;
+}
+
+/** UNI-12/ORCH-6: why a session exists — the server's own `Trigger` enum.
+ * `manual` is the pre-ORCH-6 spelling of `human`, accepted on input and
+ * normalized to `human`. */
+export type TriggerKind = 'human' | 'channel' | 'cron' | 'heartbeat' | 'webhook' | 'parent' | 'api' | 'unknown';
+export interface TriggerModel {
+  kind: TriggerKind;
+  label: string | null;
+  /** ORCH-6: the compact surface key this conversation is reached on
+   * (`telegram:dm:123456`), when it has one. */
+  surface?: string | null;
+}
+
+/** ORCH-6: a conversation that moved to another surface (Hermes `handoff_*`). */
+export interface CrossSurfaceModel {
+  state: string;
+  platform: string | null;
+  error: string | null;
+}
+
+/** UNI-12: one row representing N runs of a recurring trigger. */
+export interface RecurringModel {
+  groupKey: string;
+  runs: number;
+  lastStatus: 'ok' | 'failed' | 'mixed' | null;
+}
+
 export interface SessionRowModel {
   key: string;
   harness: HarnessId;
@@ -67,6 +172,18 @@ export interface SessionRowModel {
   subagentCount?: number;
   /** Explicit activity used for child rows in the on-demand inspector. */
   activity?: SessionActivity;
+  /** UNI-8: whose conversation this is (absent = local user). */
+  participant?: ParticipantModel;
+  /** UNI-9: typed workspace (derived from `cwd` when a host omits it). */
+  workspaceRef?: WorkspaceRefModel;
+  /** UNI-10: canonical-elsewhere provenance. */
+  mirror?: MirrorModel;
+  /** UNI-12: trigger provenance. */
+  trigger?: TriggerModel;
+  /** UNI-12: recurring-run grouping. */
+  recurring?: RecurringModel;
+  /** ORCH-6: moved-to-another-surface state, when the harness publishes one. */
+  crossSurface?: CrossSurfaceModel;
 }
 
 export interface SubagentInspectorModel {
@@ -315,6 +432,14 @@ export interface SupercodeUiState {
   canConfigureSettings: boolean;
   messaging: 'live_peer' | null;
   workspace: string;
+  /** UNI-9: typed workspace for the attached conversation (always present after normalization). */
+  workspaceRef?: WorkspaceRefModel;
+  /** UNI-8: whose conversation the attached session is (defaults to local-user). */
+  participant?: ParticipantModel;
+  /** UNI-10: set when the attached session is a mirror. */
+  mirror?: MirrorModel | null;
+  /** UNI-11: which surface holds the attached session now. */
+  holder?: HolderModel | null;
   taskPlan: TaskPlanModel;
   semantics: SessionSemanticsModel;
   terminalHandoff: { program: string; arguments: string[]; cwd: string } | null;
@@ -347,6 +472,12 @@ export interface SupercodeUiState {
   attached: AttachedSessionModel | null;
   owned: AttachedSessionModel | null;
   attachError: { key: string; message: string } | null;
+  /** Browser-safe package metadata; host filesystem paths are deliberately omitted. */
+  agentPackage: AgentPackageModel | null;
+  contributions: AgentContributionModel[];
+  agentPackageError: string | null;
+  agentPackageCapabilityState: AgentPackageCapabilityStateModel | null;
+  agentPackageCapabilityError: string | null;
 }
 
 export type SupercodeUiIntent =
@@ -561,8 +692,36 @@ export interface MessengerProps {
 export const EMPTY_UI_STATE: Readonly<SupercodeUiState>;
 export const DEFAULT_LABELS: Readonly<MessengerLabels>;
 export function normalizeUiState(value: unknown): SupercodeUiState;
+export function normalizeContributions(value: unknown): AgentContributionModel[];
+export function selectContributions(
+  contributions: unknown,
+  query?: { kind?: string; surface?: string; region?: string },
+): AgentContributionModel[];
 export function harnessDisplayName(id: string): string;
 export function sessionDisplayName(session: Pick<SessionRowModel, 'name' | 'title'>): string;
+/** ORCH-6: one `harness.v1.sessions.discover` / `sessions.load` row, as the
+ * service publishes it. Structurally the SDK's `SessionDescriptor`; declared
+ * here so the UI package stays dependency-free. */
+export interface HarnessSessionDescriptorModel {
+  locator: { harness: string; session_id: string; storage?: unknown };
+  cwd?: string | null;
+  title?: string | null;
+  updated_at_ms?: number | null;
+  message_count?: number | null;
+  model?: string | null;
+  child_session_count?: number;
+  trigger?: TriggerKind | 'manual';
+  surface?: { key?: string; platform?: string; kind?: string; chat_id?: string; thread_id?: string; participant_id?: string };
+  profile?: string;
+  recurrence?: { job_id: string; kind: string };
+  cross_surface?: { state: string; platform?: string; error?: string };
+  workspace?: WorkspaceRefModel | { kind: 'repo' | 'channel' | 'none'; value?: string };
+}
+/** ORCH-6: `telegram:dm:123456` — the compact surface key a person reads. */
+export function surfaceLabel(surface: unknown): string;
+/** ORCH-6: project service rows into list rows. The conversation nouns are
+ * read off the server's derivation, never re-derived on the client. */
+export function sessionRowsFromDescriptors(descriptors: readonly HarnessSessionDescriptorModel[] | unknown): SessionRowModel[];
 export function relativeAge(updatedAt: number | null | undefined, now?: number): string;
 export function sessionActivity(state: SupercodeUiState, row: SessionRowModel): SessionActivity;
 export function projectAgentActivity(state: SupercodeUiState | unknown): AgentActivityModel;