@opengeni/sdk 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -24,6 +24,8 @@ export {
 export type { ProxySessionEventStreamOptions, SseReStreamOptions } from "./proxy";
 export { parseSseStream } from "./sse";
 export type { SseMessage } from "./sse";
+export { normalizeMcpOutput } from "./mcp-output";
+export type { NormalizedMcpOutput } from "./mcp-output";
 // Desktop (noVNC) transport contract — pure, zero-dep (the RFB import lives in
 // @opengeni/react). URL assembler + connection state machine + rotation fence.
 export { desktopSocketUrl, nextDesktopState, applyUrlRotation } from "./desktop";
@@ -235,8 +237,10 @@ export type {
   FileResourceRef,
   FileStatus,
   FileUploadData,
+  FirstPartyMcpToolName,
   GetPackResponse,
   GitHubAppInfo,
+  GitHubAppSetupMode,
   GitHubBindingStatus,
   GitHubInstallationBinding,
   GitHubInstallationLifecycle,
@@ -322,6 +326,7 @@ export type {
   SessionCommandReceipt,
   SteerSessionQueueItemRequest,
   WorkspaceInferenceControlResponse,
+  SessionPendingInputPreview,
   SessionSystemUpdate,
   SessionSystemUpdateKind,
   SessionSystemUpdateState,

package/src/mcp-output.ts

@@ -0,0 +1,161 @@
+/**
+ * A transport-tolerant MCP tool result.
+ *
+ * `value` is the canonical machine-readable payload after recognized MCP/JSON
+ * envelopes are removed. `text` is the best presentation string without
+ * discarding structured data. `raw` always retains the original evidence.
+ */
+export type NormalizedMcpOutput = Readonly<{
+  raw: unknown;
+  value: unknown;
+  text: string;
+  isError: boolean;
+}>;
+
+const MAX_MCP_OUTPUT_DEPTH = 8;
+const RESULT_ENVELOPE_KEYS = new Set(["result", "isError", "jsonrpc", "id", "_meta"]);
+
+/** Normalize common direct, JSON, and standard MCP result envelopes without throwing. */
+export function normalizeMcpOutput(output: unknown): NormalizedMcpOutput {
+  const normalized = normalizeValue(output, 0, new Set<object>());
+  return {
+    raw: output,
+    value: normalized.value,
+    text: normalized.text,
+    isError: normalized.isError,
+  };
+}
+
+type NormalizedValue = Omit<NormalizedMcpOutput, "raw">;
+
+function normalizeValue(value: unknown, depth: number, ancestors: Set<object>): NormalizedValue {
+  if (value === null || value === undefined) {
+    return { value, text: "", isError: false };
+  }
+  if (typeof value === "string") {
+    return normalizeText(value, depth, ancestors);
+  }
+  if (typeof value !== "object") {
+    return { value, text: String(value), isError: false };
+  }
+  if (depth >= MAX_MCP_OUTPUT_DEPTH || ancestors.has(value)) {
+    return { value, text: safeStringify(value), isError: false };
+  }
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return { value, text: safeStringify(value), isError: false };
+    }
+
+    const record = value as Record<string, unknown>;
+    const envelopeError = record.isError === true;
+
+    if (record.type === "text" && typeof record.text === "string") {
+      const normalized = normalizeText(record.text, depth + 1, ancestors);
+      return {
+        value: normalized.value,
+        text: record.text,
+        isError: envelopeError || normalized.isError,
+      };
+    }
+
+    if ("structuredContent" in record) {
+      const normalized = normalizeValue(record.structuredContent, depth + 1, ancestors);
+      return {
+        value: normalized.value,
+        text: firstMcpText(record.content) ?? normalized.text,
+        isError: envelopeError || normalized.isError,
+      };
+    }
+
+    if (isMcpContent(record.content)) {
+      const text = firstMcpText(record.content);
+      if (text !== null) {
+        const normalized = normalizeText(text, depth + 1, ancestors);
+        return {
+          value: normalized.value,
+          text,
+          isError: envelopeError || normalized.isError,
+        };
+      }
+      return {
+        value,
+        text: safeStringify(value),
+        isError: envelopeError,
+      };
+    }
+
+    if (isResultEnvelope(record)) {
+      const normalized = normalizeValue(record.result, depth + 1, ancestors);
+      return {
+        value: normalized.value,
+        text: normalized.text,
+        isError: envelopeError || normalized.isError,
+      };
+    }
+
+    return {
+      value,
+      text: safeStringify(value),
+      isError: envelopeError,
+    };
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function normalizeText(text: string, depth: number, ancestors: Set<object>): NormalizedValue {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    const normalized = normalizeValue(parsed, depth + 1, ancestors);
+    return {
+      value: normalized.value,
+      text,
+      isError: normalized.isError,
+    };
+  } catch {
+    return { value: text, text, isError: false };
+  }
+}
+
+function isMcpContent(value: unknown): value is readonly Record<string, unknown>[] {
+  return (
+    Array.isArray(value) &&
+    value.some(
+      (part) =>
+        part !== null &&
+        typeof part === "object" &&
+        typeof (part as { type?: unknown }).type === "string",
+    )
+  );
+}
+
+function firstMcpText(value: unknown): string | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  for (const part of value) {
+    if (
+      part !== null &&
+      typeof part === "object" &&
+      (part as { type?: unknown }).type === "text" &&
+      typeof (part as { text?: unknown }).text === "string"
+    ) {
+      return (part as { text: string }).text;
+    }
+  }
+  return null;
+}
+
+function isResultEnvelope(record: Record<string, unknown>): boolean {
+  return "result" in record && Object.keys(record).every((key) => RESULT_ENVELOPE_KEYS.has(key));
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}

package/src/types.ts

@@ -272,7 +272,7 @@ export type ToolRef = {
 };
 
 export type SessionToolPolicy = {
-  mode: "workspace_default" | "explicit" | "inherited" | "legacy";
+  mode: "workspace_default" | "explicit" | "inherited";
   inheritedFromSessionId: string | null;
 };
 
@@ -282,9 +282,9 @@ export type UpdateSessionToolPolicyRequest =
       expectedVersion: number;
     }
   | {
-      /** Omitted for compatibility with the original explicit-only API. */
-      mode?: "explicit" | undefined;
+      mode: "explicit";
       tools: ToolRef[];
+      firstPartyMcpTools: FirstPartyMcpToolName[];
       expectedVersion: number;
     };
 
@@ -496,8 +496,8 @@ export type Session = {
   resources: ResourceRef[];
   skills: SessionSkill[];
   tools: ToolRef[];
-  toolPolicy?: SessionToolPolicy | undefined;
-  toolPolicyVersion?: number | undefined;
+  toolPolicy: SessionToolPolicy;
+  toolPolicyVersion: number;
   effectiveToolPolicy?: SessionEffectiveToolPolicy | undefined;
   metadata: Record<string, unknown>;
   /** Frozen creator fact; later turns carry their own independent initiator. */
@@ -517,6 +517,7 @@ export type Session = {
   rigId: string | null;
   rigVersionId: string | null;
   firstPartyMcpPermissions: string[] | null;
+  firstPartyMcpTools: FirstPartyMcpToolName[];
   mcpServers: SessionMcpServerMetadata[];
   parentSessionId: string | null;
   /** Immutable server-authored nested-agent lineage and policy snapshot. */
@@ -758,6 +759,9 @@ export const SESSION_EVENT_TYPES = [
   "goal.continuation",
   "system.update.pending",
   "system.update.delivered",
+  "system.update.superseded",
+  "system.update.cancelled",
+  "system.update.settled",
   "session.control.paused",
   "session.control.resumed",
   "session.control.steer_requested",
@@ -1594,6 +1598,7 @@ export type CreateSessionRequest = {
   expectedNewSessionDraftRevision?: number | undefined;
   maxNestedAgentDepth?: number | undefined;
   firstPartyMcpPermissions?: string[] | undefined;
+  firstPartyMcpTools?: FirstPartyMcpToolName[] | undefined;
   mcpServers?: SessionMcpServerInput[] | undefined;
   // Shared-sandbox placement (mirror of `@opengeni/contracts` CreateSessionRequest.sandbox,
   // addendum 05 §D.1). Three-way union; OMITTED ⇒ the context-dependent server default
@@ -1659,6 +1664,58 @@ export type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
  */
 export type Permission = KnownPermission | (string & {});
 
+export type FirstPartyMcpToolName =
+  | "set_session_title"
+  | "goal_set"
+  | "goal_update"
+  | "goal_complete"
+  | "goal_pause"
+  | "memory_search"
+  | "memory_save"
+  | "memory_correct"
+  | "sandboxes_list"
+  | "sandbox_attach"
+  | "sandbox_swap"
+  | "run_on"
+  | "sandbox_provision"
+  | "rig_list"
+  | "rig_get"
+  | "rig_propose_change"
+  | "rig_verify"
+  | "rig_promote"
+  | "sessions_list"
+  | "session_get"
+  | "session_events"
+  | "session_create"
+  | "session_send_message"
+  | "session_pause"
+  | "session_resume"
+  | "session_steer"
+  | "set_other_session_title"
+  | "variable_set_list"
+  | "environment_list"
+  | "variable_set_set_variable"
+  | "environment_set_variable"
+  | "github_connect_link"
+  | "github_token"
+  | "github_repositories_list"
+  | "social_connections_list"
+  | "social_posts_recent"
+  | "social_daily_analysis_context"
+  | "scheduled_tasks_list"
+  | "scheduled_tasks_get"
+  | "scheduled_tasks_create"
+  | "scheduled_tasks_update"
+  | "scheduled_tasks_pause"
+  | "scheduled_tasks_resume"
+  | "scheduled_tasks_trigger"
+  | "scheduled_tasks_delete"
+  | "scheduled_task_runs_list"
+  | "slack_bot_list_channels"
+  | "slack_bot_channel_history"
+  | "slack_bot_list_users"
+  | "slack_bot_post_message";
+
 export type ProductAccessMode = "local" | "configured" | "managed";
 
 export type ModelCapabilitySupportV1 = "supported" | "unsupported" | "unknown";
@@ -2332,9 +2389,6 @@ export type ComposerDraft = {
   revision: number;
   text: string;
   resources: ResourceRef[];
-  tools: ToolRef[];
-  /** False inherits the session policy; true preserves an explicit array. */
-  toolsProvided: boolean;
   model: string;
   reasoningEffort: ReasoningEffort;
   sourceTurnId: string | null;
@@ -2350,6 +2404,7 @@ export type NewSessionDraftOptions = {
   rigId?: string | undefined;
   goal?: GoalSpec | undefined;
   firstPartyMcpPermissions?: Permission[] | undefined;
+  firstPartyMcpTools?: FirstPartyMcpToolName[] | undefined;
 };
 
 export type NewSessionDraft = {
@@ -2371,8 +2426,20 @@ export type SessionQueueSnapshot = {
   /** The latest interrupted attempt has not yet durably proved physical quiescence. */
   stoppingPreviousAttempt: boolean;
   items: SessionTurn[];
+  /** Canonical pending machine inputs. Events only invalidate this snapshot. */
+  pendingInputs: SessionPendingInputPreview[];
+  /** Exact next bounded input batch that will join an already-waiting prompt. */
+  pendingInputAttachment: {
+    turnId: string;
+    inputIds: string[];
+  } | null;
 };
 
+export type SessionPendingInputPreview = Pick<
+  SessionSystemUpdate,
+  "id" | "sessionId" | "kind" | "classification" | "sourceId" | "summary" | "createdAt"
+>;
+
 export type SystemUpdateClassification = "success" | "failure" | "action_required" | "info";
 
 export type SessionSystemUpdateKind =
@@ -2384,7 +2451,6 @@ export type SessionSystemUpdateKind =
 
 export type SessionSystemUpdateState =
   | "pending"
-  | "deferred"
   | "delivered"
   | "cancelled"
   | "superseded"
@@ -2402,6 +2468,7 @@ export type SessionSystemUpdate = {
   lineage: Record<string, unknown>;
   state: SessionSystemUpdateState;
   deliveredTurnId: string | null;
+  deliveredHistoryItemId: string | null;
   deliveredAt: string | null;
   createdAt: string;
 };
@@ -3409,6 +3476,8 @@ export type GitHubRepositoryScope = "all" | "selected";
 
 export type GitHubBindingStatus = "disabled" | "unbound" | "bound";
 
+export type GitHubAppSetupMode = "platform" | "operator";
+
 export type GitHubInstallationLifecycle = "active" | "suspended" | "deleted" | "unverified";
 
 export type GitHubInstallationBinding = {
@@ -3419,6 +3488,8 @@ export type GitHubInstallationBinding = {
   lifecycle: GitHubInstallationLifecycle;
   repositoryScope: GitHubRepositoryScope;
   repositoryCount: number;
+  /** OpenGeni-owned entry point for changing the installation's repository allowlist. */
+  configureUrl: string | null;
   createdAt: string;
   updatedAt: string;
 };
@@ -3427,12 +3498,14 @@ export type GitHubAppInfo = {
   configured: boolean;
   /** Truthful workspace binding state; server App credentials alone are not a binding. */
   status: GitHubBindingStatus;
+  /** Platform deployments expose installation only; operator deployments may create an App. */
+  setupMode: GitHubAppSetupMode;
   appId: string | null;
   clientId: string | null;
   appSlug: string | null;
-  /** Fresh GitHub-controlled installation/configuration consent entry point. */
+  /** Fresh OAuth-first existing-installation discovery and install entry point. */
   installUrl: string | null;
-  /** Compatibility alias for installUrl; no repository-admin chooser is exposed. */
+  /** Compatibility alias for installUrl. */
   linkUrl: string | null;
   /** Installation bindings owned independently by this workspace. */
   installations: GitHubInstallationBinding[];
@@ -3547,7 +3620,6 @@ export type UserMessageEventInput = {
     text: string;
     turnInstructions?: string | undefined;
     resources?: ResourceRef[] | undefined;
-    tools?: ToolRef[] | undefined;
     model?: string | undefined;
     reasoningEffort?: ReasoningEffort | undefined;
     mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[] | undefined;