@opengeni/react 3.3.2 → 3.4.1-canary.38960406141001

package/src/secrets-ui.tsx

@@ -0,0 +1,59 @@
+import type { GeneratePasswordSpec } from "@opengeni/sdk";
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * Secret-reference token shapes (structural mirror of `@opengeni/contracts`
+ * `SecretTextToken`). @opengeni/react may not depend on the contracts
+ * runtime, so hosts inject the one tokenizer and generator through
+ * `SecretsUiProvider`.
+ */
+export type SecretReferenceTargetLike =
+  | { form: "id"; itemId: string; field: string | null }
+  | { form: "path"; segments: readonly string[] };
+
+export type SecretReferenceLike = {
+  kind: "secret" | "secretfile";
+  raw: string;
+  start: number;
+  end: number;
+  target: SecretReferenceTargetLike;
+  otp: boolean;
+  previous: boolean;
+};
+
+export type SecretTextTokenLike =
+  | { type: "text"; value: string }
+  | { type: "reference"; reference: SecretReferenceLike }
+  | { type: "invalid"; raw: string; start: number; end: number; reason: string };
+
+export type PasswordStrengthLike = {
+  bits: number;
+  label: "weak" | "fair" | "strong" | "very_strong";
+};
+
+export type SecretsUi = {
+  /** Split text into plain text, references and invalid reference-looking text. */
+  tokenize: (text: string) => SecretTextTokenLike[];
+  /** Client-side password generator (same implementation as the server). */
+  generatePassword: (spec?: GeneratePasswordSpec) => string;
+  passwordStrength?: ((password: string) => PasswordStrengthLike) | undefined;
+  /** Optional link target for a reference chip (for example the item page). */
+  hrefForReference?: ((reference: SecretReferenceLike) => string | null) | undefined;
+};
+
+const SecretsUiContext = createContext<SecretsUi | null>(null);
+
+export function SecretsUiProvider({
+  value,
+  children,
+}: {
+  value: SecretsUi | null;
+  children?: ReactNode;
+}) {
+  return <SecretsUiContext.Provider value={value}>{children}</SecretsUiContext.Provider>;
+}
+
+/** Null without a provider: chips render as plain text, Generate is server-side. */
+export function useSecretsUi(): SecretsUi | null {
+  return useContext(SecretsUiContext);
+}

package/src/session-agents-model.ts

@@ -0,0 +1,33 @@
+import type { LineageNode, SessionGoal } from "@opengeni/sdk";
+
+/* Renderer-neutral session chrome signals shared by the web dock and native
+   apps: the sub-agents chip and the goal chip. */
+
+export type SessionAgentsSignal = {
+  count: number;
+  detail: string;
+  tone: "running" | "waiting" | "neutral";
+};
+
+/** The agents chip for a session's spawned workers, or undefined without any. */
+export function sessionAgentsSignal(
+  agents: readonly Pick<LineageNode, "session">[],
+): SessionAgentsSignal | undefined {
+  if (agents.length === 0) return undefined;
+  const running = agents.filter(
+    (node) => node.session.status === "running" && node.session.effectiveControl.state === "active",
+  ).length;
+  const paused = agents.filter((node) => node.session.effectiveControl.state === "paused").length;
+  return {
+    count: agents.length,
+    detail: running > 0 ? `${running} running` : paused > 0 ? `${paused} paused` : "Idle",
+    tone: running > 0 ? "running" : paused > 0 ? "waiting" : "neutral",
+  };
+}
+
+/** One human word for a goal's state, as the web goal pill reads. */
+export function sessionGoalStateLabel(goal: Pick<SessionGoal, "status">): string {
+  if (goal.status === "completed") return "Completed";
+  if (goal.status === "paused") return "Paused";
+  return "Active";
+}

package/src/session-attention-model.ts

@@ -0,0 +1,62 @@
+import type { SessionEvent } from "@opengeni/sdk";
+
+// Keep this client scheduling predicate aligned with the meaningful-attention
+// predicate in packages/db/src/session-meaningful-events.ts. The server remains
+// authoritative; this only avoids personal-state writes for streaming activity.
+export const SESSION_ATTENTION_EVENT_TYPES: ReadonlySet<string> = new Set([
+  "agent.message.completed",
+  "turn.completed",
+  "turn.failed",
+  "session.requiresAction",
+  "session.humanInput.requested",
+  "tool.auth_needed",
+  "credential.auth_needed",
+  "goal.completed",
+  "goal.paused",
+  "goal.progress",
+  "goal.rewrite.proposed",
+  "rig.setup.failed",
+  "sandbox.operation.failed",
+  "sandbox.box.lost",
+  "workspace.revision.degraded",
+  "machine.op.failed",
+  "machine.link.lost",
+  "session.event.envelope_omitted",
+]);
+
+/**
+ * The latest delivered attention boundary, independent of raw token activity.
+ * A foreground reader acknowledges through this sequence, so streaming flushes
+ * never cause a personal-state write and later activity stays unread.
+ */
+export function sessionAttentionReadThroughSequence(events: readonly SessionEvent[]): number {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]!;
+    if (
+      !SESSION_ATTENTION_EVENT_TYPES.has(event.type) ||
+      event.duplicateOfEventId ||
+      (event.turnAssociation != null && event.turnAssociation !== "current")
+    )
+      continue;
+    const payload =
+      event.payload && typeof event.payload === "object"
+        ? (event.payload as Record<string, unknown>)
+        : {};
+    if (
+      event.type === "agent.message.completed" &&
+      (payload.phase === "commentary" || payload.text == null || payload.text === "")
+    )
+      continue;
+    if (event.type === "turn.completed") {
+      // A task usage-limit stop is an actionable boundary (only a person can
+      // raise or clear the limit), matching the server's attention predicate.
+      if (payload.segmentLimit === "session_usage_limit") return event.sequence;
+      if (Object.hasOwn(payload, "maintenance") || Object.hasOwn(payload, "segmentLimit")) continue;
+      const output = payload.output ?? payload.result;
+      if ((output == null || output === "") && (payload.reply == null || payload.reply === ""))
+        continue;
+    }
+    return event.sequence;
+  }
+  return 0;
+}

package/src/session-auth-recommendation.ts

@@ -0,0 +1,48 @@
+import type { AuthNeededItem } from "./timeline/types";
+import type { CapabilityCatalogItem } from "@opengeni/sdk";
+
+/** Recovery events identify runtime servers/connections, while recommendation
+ * events already carry a catalog id. Never guess among same-domain accounts. */
+export function sessionAuthRecommendation(
+  item: AuthNeededItem,
+  catalog: CapabilityCatalogItem[],
+): AuthNeededItem | undefined {
+  if (
+    item.authoritySource === "host" ||
+    item.reason === "unsupported_auth" ||
+    item.reason === "resource_scope_unavailable"
+  )
+    return undefined;
+  if (item.capability) return item;
+  const recoveryServerId = item.canonicalServerId ?? item.serverId;
+  const matches = catalog.filter(
+    (candidate) =>
+      (recoveryServerId !== null &&
+        candidate.runtime.mcpServerId === recoveryServerId &&
+        recoveryServerId !== "opengeni") ||
+      (item.connectionId !== null && candidate.connectionRef?.connectionId === item.connectionId),
+  );
+  if (matches.length !== 1) return undefined;
+  const entry = matches[0]!;
+  const personalAccess = item.reason === "personal_authority_unavailable";
+  if (
+    personalAccess &&
+    ((item.connectionSubjectScope ?? entry.connectionRef?.subjectScope) !== "subject" ||
+      entry.connectionRef?.authoritySource === "host")
+  )
+    return undefined;
+  return {
+    ...item,
+    capability: {
+      id: entry.id,
+      name: entry.name,
+      kind: entry.kind,
+      source: entry.source,
+      action: "connect",
+      rationale: personalAccess
+        ? "Review permission to use your personal account in this conversation."
+        : "Reconnect this integration to use its tools in this conversation.",
+      requiredVariables: [],
+    },
+  };
+}

package/src/session-capability-policy.ts

@@ -0,0 +1,196 @@
+import type {
+  FirstPartyMcpToolName,
+  CapabilityCatalogItem,
+  Session,
+  UpdateSessionToolPolicyRequest,
+} from "@opengeni/sdk";
+import type { OpenGeniBrowserClient as OpenGeniClient } from "@opengeni/sdk/browser";
+
+/** Catalog tool discovery may be lazy; selecting the installed server does not
+ * require its individual tool inventory to have been fetched. */
+export function sessionCapabilityTools(item: CapabilityCatalogItem) {
+  const serverId = item.kind === "mcp" ? item.runtime?.mcpServerId : undefined;
+  return serverId && !item.tools.some((tool) => tool.kind === "mcp" && tool.id === serverId)
+    ? [...item.tools, { kind: "mcp" as const, id: serverId }]
+    : item.tools;
+}
+
+/** A connection never resets the human's existing tool selection. Default-mode
+ * sessions discover newly enabled servers at admission; explicit/inherited
+ * policies add only this reviewed capability, with the existing CAS fence. */
+export async function attachSessionCapability(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  item: CapabilityCatalogItem,
+  stillCurrent: () => boolean = () => true,
+): Promise<void> {
+  const tools = sessionCapabilityTools(item);
+  if (item.kind === "skill" || tools.length === 0) return;
+  if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+  const session = await client.getSession(workspaceId, sessionId);
+  if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+  const request = capabilityToolPolicyUpdate(session, item);
+  if (request) await client.updateSessionToolPolicy(workspaceId, sessionId, request);
+}
+
+function capabilityToolPolicyUpdate(
+  session: Session,
+  item: CapabilityCatalogItem,
+): UpdateSessionToolPolicyRequest | null {
+  const tools = sessionCapabilityTools(item);
+  if (item.kind === "skill" || tools.length === 0) return null;
+  // Session.tools includes mandatory runtime servers, which must never be
+  // echoed into the human's explicit selection.
+  let existing = session.tools.filter(
+    (tool) => !session.effectiveToolPolicy?.mandatoryIds?.includes(tool.id),
+  );
+  if (session.toolPolicy.mode === "workspace_default") {
+    const policy = session.effectiveToolPolicy;
+    if (!policy || policy.idsTruncated)
+      throw new Error(
+        "Connected, but the full session tool selection could not be read. Review the Tools picker before continuing.",
+      );
+    // A workspace may choose a restricted default instead of all enabled servers.
+    // Preserve that exact selection if this connection needs an explicit addition.
+    // selectedIds contains only explicit additions, and is normally empty for
+    // automatic selection. Compare against the resolved defaults instead.
+    existing = policy.effectiveIds
+      .filter((id) => !policy.mandatoryIds.includes(id))
+      .map(
+        (id) =>
+          session.tools.find((tool) => tool.kind === "mcp" && tool.id === id) ?? {
+            kind: "mcp" as const,
+            id,
+            optional: true,
+          },
+      );
+  }
+  const additions = tools.filter(
+    (tool) =>
+      !session.effectiveToolPolicy?.mandatoryIds.includes(tool.id) &&
+      !existing.some((current) => current.kind === tool.kind && current.id === tool.id),
+  );
+  const recommended = Array.isArray(item.metadata?.firstPartyMcpTools)
+    ? (item.metadata.firstPartyMcpTools.filter(
+        (name): name is string => typeof name === "string",
+      ) as FirstPartyMcpToolName[])
+    : [];
+  const firstParty = [...new Set([...session.firstPartyMcpTools, ...recommended])];
+  if (additions.length === 0 && firstParty.length === session.firstPartyMcpTools.length)
+    return null;
+  return {
+    mode: "explicit",
+    tools: [...existing, ...additions],
+    firstPartyMcpTools: firstParty,
+    expectedVersion: session.toolPolicyVersion,
+  };
+}
+
+/** Read-only review. Hosts must show ancestor changes and obtain a separate
+ * explicit click before applying. This plan is never authorization. */
+export type SessionCapabilityAccessPlan = {
+  workspaceId: string;
+  sessionId: string;
+  capabilityId: string;
+  sessions: Array<{
+    id: string;
+    title: string | null;
+    parentSessionId: string | null;
+    toolPolicyVersion: number;
+    request: UpdateSessionToolPolicyRequest | null;
+  }>;
+};
+
+export async function prepareSessionCapabilityAccess(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  item: CapabilityCatalogItem,
+  stillCurrent: () => boolean = () => true,
+): Promise<SessionCapabilityAccessPlan> {
+  const sessions: SessionCapabilityAccessPlan["sessions"] = [];
+  if (item.kind === "skill" || sessionCapabilityTools(item).length === 0)
+    return { workspaceId, sessionId, capabilityId: item.id, sessions };
+  const visited = new Set<string>();
+  let id: string | null = sessionId;
+  while (id) {
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    if (visited.has(id)) throw new Error("The parent chat chain could not be verified.");
+    visited.add(id);
+    const session = await client.getSession(workspaceId, id);
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    const request = capabilityToolPolicyUpdate(session, item);
+    sessions.push({
+      id,
+      title: session.title ?? null,
+      parentSessionId: session.parentSessionId ?? null,
+      toolPolicyVersion: session.toolPolicyVersion,
+      request,
+    });
+    // An unchanged immediate parent already supplies this capability's ceiling.
+    // Do not read or broaden ancestors irrelevant to this addition.
+    if (!request) break;
+    id = session.parentSessionId ?? null;
+  }
+  return { workspaceId, sessionId, capabilityId: item.id, sessions: sessions.reverse() };
+}
+
+/** Preflight the entire review, then apply ordinary CAS-fenced API writes root
+ * first. A partial failure may leave approved ancestor changes committed; never
+ * claim success or roll back another person's edits. Prepare a new review. */
+export async function applySessionCapabilityAccess(
+  client: OpenGeniClient,
+  plan: SessionCapabilityAccessPlan,
+  stillCurrent: () => boolean = () => true,
+): Promise<void> {
+  for (const reviewed of plan.sessions) {
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    const current = await client.getSession(plan.workspaceId, reviewed.id);
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    if (
+      current.toolPolicyVersion !== reviewed.toolPolicyVersion ||
+      (current.parentSessionId ?? null) !== reviewed.parentSessionId
+    )
+      throw new Error("Chat access changed. Click Add tools to review the current choices again.");
+  }
+  for (const reviewed of plan.sessions) {
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    if (reviewed.request) {
+      const updated = await client.updateSessionToolPolicy(
+        plan.workspaceId,
+        reviewed.id,
+        reviewed.request,
+      );
+      if (
+        reviewed.request.mode === "explicit" &&
+        reviewed.request.firstPartyMcpTools.some(
+          (tool) => !updated.firstPartyMcpTools.includes(tool),
+        )
+      )
+        throw new Error(
+          "This chat's capabilities do not allow these tools. Review its capability settings before adding tools again.",
+        );
+    }
+  }
+}
+
+/** Native OAuth callbacks have already saved the provider connection. Finish
+ * the separate, version-fenced session tool selection before reporting success. */
+export async function completeSessionCapabilityOAuth(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  capabilityId: string | null,
+): Promise<void> {
+  if (!capabilityId)
+    throw new Error(
+      "The authorized integration could not be identified. Review its connection card to finish setup.",
+    );
+  const connected = (await client.listCapabilities(workspaceId)).items.find(
+    (item) => item.id === capabilityId,
+  );
+  if (!connected?.enabled)
+    throw new Error("The connection was authorized, but enabling its tools could not be verified.");
+  await attachSessionCapability(client, workspaceId, sessionId, connected);
+}

package/src/session-context.ts

@@ -129,7 +129,7 @@ function useEmbeddedClientRefinement<TClient extends object>(
   const workspaceId = override.workspaceId ?? context?.workspaceId;
   if (!candidate || !workspaceId) {
     throw new Error(
-      "@opengeni/react: no OpenGeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
+      "@opengeni/react: no Opengeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
     );
   }
   const methods = candidate as Record<string, unknown>;
@@ -164,7 +164,7 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
   const workspaceId = override.workspaceId ?? context?.workspaceId;
   if (!client || !workspaceId) {
     throw new Error(
-      "@opengeni/react: no OpenGeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
+      "@opengeni/react: no Opengeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
     );
   }
   return {
@@ -193,7 +193,6 @@ const BROWSER_INTERACTION_METHODS = [
   "getAuthRun",
   "startBrowserAuthRun",
   "reportBrowserAuthRun",
-  "protectedBrowserAuthFill",
   "verifyBrowserAuthRun",
   "listInteractionInterventions",
   "getInteractionIntervention",
@@ -423,7 +422,7 @@ export function useOpenGeniClient(
   const client = override.client ?? context?.client;
   if (!client) {
     throw new Error(
-      "@opengeni/react: no OpenGeni client available. Wrap the tree in <OpenGeniProvider> or pass { client } to the hook.",
+      "@opengeni/react: no Opengeni client available. Wrap the tree in <OpenGeniProvider> or pass { client } to the hook.",
     );
   }
   return client;

package/src/session-feedback-model.ts

@@ -0,0 +1,95 @@
+// Reply and session feedback shared by web and native: the one feedback read
+// per session (with recovery), saved turn ratings, the submission payload with
+// a retained idempotency key, and the dialog copy. No DOM, no React.
+import type {
+  CreateFeedbackRequest,
+  Feedback,
+  FeedbackSentiment,
+  OpenGeniClient,
+} from "@opengeni/sdk";
+
+export type FeedbackClient = Pick<OpenGeniClient, "createFeedback" | "listOwnFeedback">;
+
+/** One shared read per session, with recovery after a transient network failure. */
+export function loadSessionFeedback(
+  client: Pick<OpenGeniClient, "listOwnFeedback">,
+  workspaceId: string,
+  sessionId: string,
+  onLoaded: (result: Awaited<ReturnType<OpenGeniClient["listOwnFeedback"]>>) => void,
+): () => void {
+  let current = true;
+  let delay = 1_000;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const load = () => {
+    void client.listOwnFeedback(workspaceId, { sessionId, includeTurns: true }).then(
+      (result) => {
+        if (current) onLoaded(result);
+      },
+      () => {
+        if (!current) return;
+        timer = setTimeout(load, delay);
+        delay = Math.min(delay * 2, 30_000);
+      },
+    );
+  };
+  load();
+  return () => {
+    current = false;
+    clearTimeout(timer);
+  };
+}
+
+/** The first saved rating per turn (the list is newest-first). */
+export function turnRatingsFromFeedback(
+  feedback: readonly Feedback[],
+): Record<string, FeedbackSentiment> {
+  const ratings: Record<string, FeedbackSentiment> = {};
+  for (const entry of feedback) {
+    if (entry.turnId && entry.sentiment && !ratings[entry.turnId])
+      ratings[entry.turnId] = entry.sentiment;
+  }
+  return ratings;
+}
+
+export type FeedbackPayload = Omit<CreateFeedbackRequest, "idempotencyKey">;
+
+/**
+ * The request to send, reusing the previous idempotency key when the user
+ * retries the identical submission (a lost response must not duplicate it).
+ */
+export function feedbackSubmission(
+  payload: FeedbackPayload,
+  previous: CreateFeedbackRequest | null,
+  newKey: () => string,
+): CreateFeedbackRequest {
+  if (
+    previous &&
+    previous.sessionId === payload.sessionId &&
+    previous.turnId === payload.turnId &&
+    previous.sentiment === payload.sentiment &&
+    previous.comment === payload.comment
+  ) {
+    return previous;
+  }
+  return { ...payload, idempotencyKey: newKey() };
+}
+
+export function feedbackDialogCopy(target: {
+  sessionId?: string | undefined;
+  turnId?: string | undefined;
+}) {
+  return {
+    title: target.turnId
+      ? "Rate this reply"
+      : target.sessionId
+        ? "Rate this session"
+        : "Send feedback",
+    description: target.sessionId
+      ? "Share what worked or what could be better."
+      : "Tell us what could make Opengeni better.",
+  };
+}
+
+export function feedbackSentimentLabel(sentiment: FeedbackSentiment): string {
+  return sentiment === "positive" ? "Thumbs up" : "Thumbs down";
+}