@opengeni/contracts 1.0.2 → 1.2.0

package/src/agent-config.ts

@@ -200,9 +200,22 @@ export type ClientAgentConfig = z.infer<typeof ClientAgentConfig>;
 // Capability registry
 // ---------------------------------------------------------------------------
 
-/** A first-party tool's owner: a capability, or pure runtime mechanics. */
+/** A built-in MCP server's owner: a capability, or pure runtime mechanics. */
 export type AgentToolCapability = AgentCapabilityId | "runtime";
 
+/**
+ * A first-party tool's owner: a capability, pure runtime mechanics, or the
+ * attached compute (a managed sandbox or Connected Machine).
+ */
+export type AgentFirstPartyToolOwner = AgentToolCapability | "sandbox";
+
+/** Owners no capability toggles: the runtime or the attached compute derives them. */
+export function isDerivedAgentToolOwner(
+  owner: AgentFirstPartyToolOwner,
+): owner is "runtime" | "sandbox" {
+  return owner === "runtime" || owner === "sandbox";
+}
+
 /**
  * Exhaustive map from every `FIRST_PARTY_MCP_TOOL_NAMES` entry to exactly one
  * owner. The `Record` type makes an unmapped new name a compile error, and
@@ -210,15 +223,18 @@ export type AgentToolCapability = AgentCapabilityId | "runtime";
  *
  * `runtime` tools are mechanics every agent needs regardless of what it may do:
  * - `wait_for_input`: ends the turn and waits for the next input.
- * - `command_read` / `command_wait`: read/await the session's own background
- *   sandbox commands (the shell already exists whenever a sandbox is attached).
  * - `set_session_title`: session titling.
+ *
+ * `sandbox` tools are derived from attached compute and never toggled:
+ * - `command_read` / `command_wait`: read/await the session's own background
+ *   commands. A command can only exist on a managed sandbox or Connected
+ *   Machine, so a turn with neither attached never receives them.
  */
 export const FIRST_PARTY_MCP_TOOL_CAPABILITIES = {
   set_session_title: "runtime",
   wait_for_input: "runtime",
-  command_wait: "runtime",
-  command_read: "runtime",
+  command_wait: "sandbox",
+  command_read: "sandbox",
 
   goal_set: "goals",
   goal_update: "goals",
@@ -400,7 +416,7 @@ export const FIRST_PARTY_MCP_TOOL_CAPABILITIES = {
   editable_artifact_apply: "artifacts",
   editable_artifact_export: "artifacts",
   editable_artifact_export_status: "artifacts",
-} as const satisfies Record<FirstPartyMcpToolName, AgentToolCapability>;
+} as const satisfies Record<FirstPartyMcpToolName, AgentFirstPartyToolOwner>;
 
 /** Owner of a non-MCP tool: a capability, runtime mechanics, or the sandbox. */
 export type AgentFunctionToolClass = AgentCapabilityId | "runtime" | "sandbox";
@@ -493,7 +509,7 @@ export const AGENT_BUILTIN_MCP_SERVER_CAPABILITIES = {
   "google-drive-publishing": "workspaceConnectors",
 } as const satisfies Record<string, AgentToolCapability>;
 
-export function firstPartyMcpToolCapability(tool: FirstPartyMcpToolName): AgentToolCapability {
+export function firstPartyMcpToolCapability(tool: FirstPartyMcpToolName): AgentFirstPartyToolOwner {
   return FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
 }
 
@@ -508,10 +524,21 @@ export type AgentToolEnvironment = {
   media?: boolean | undefined;
   hasDeferredTools?: boolean;
   routerInHistory?: boolean;
+  /**
+   * Whether the turn has a managed sandbox or Connected Machine attached.
+   * `false` withholds the `sandbox`-owned first-party tools, which could never
+   * find a command; undefined means not yet known and keeps them.
+   */
+  sandboxAttached?: boolean;
 };
 
+/** Runtime mechanics every configured agent receives. */
 export const AGENT_RUNTIME_MECHANIC_TOOL_NAMES = [
   "wait_for_input",
+] as const satisfies readonly FirstPartyMcpToolName[];
+
+/** First-party tools a configured agent receives whenever compute is attached. */
+export const AGENT_SANDBOX_MECHANIC_TOOL_NAMES = [
   "command_read",
   "command_wait",
 ] as const satisfies readonly FirstPartyMcpToolName[];
@@ -519,7 +546,9 @@ export const AGENT_RUNTIME_MECHANIC_TOOL_NAMES = [
 /**
  * The one turn-time capability gate. Null means the historical attachment
  * rules, including unconditional Skill tools and router. Resource-derived
- * sandbox tools, product MCPs and runtime mechanics are never toggled.
+ * sandbox tools, product MCPs and runtime mechanics are never toggled; the
+ * `sandbox`-owned first-party tools follow `environment.sandboxAttached` for
+ * every session, configured or not.
  */
 export function resolveAgentToolFamilies(
   config: ResolvedAgentConfig | null | undefined,
@@ -534,8 +563,10 @@ export function resolveAgentToolFamilies(
   const humanInput = enabled("humanInput") && environment.humanInput !== false;
   const media = enabled("media") && environment.media !== false;
   const skills = !config ? "manage" : enabled("skills") ? config.capabilities.skills : false;
+  const sandboxTools = environment.sandboxAttached !== false;
   const allowsFirstPartyTool = (name: FirstPartyMcpToolName): boolean => {
-    const owner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[name];
+    const owner: AgentFirstPartyToolOwner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[name];
+    if (owner === "sandbox") return sandboxTools;
     return owner === "runtime" || enabled(owner);
   };
   return {
@@ -549,11 +580,14 @@ export function resolveAgentToolFamilies(
     allowsFirstPartyTool,
     firstPartyTools(names: readonly FirstPartyMcpToolName[]): FirstPartyMcpToolName[] {
       return !config
-        ? [...names]
+        ? names.filter(
+            (name) => sandboxTools || FIRST_PARTY_MCP_TOOL_CAPABILITIES[name] !== "sandbox",
+          )
         : [
             ...new Set([
               ...names.filter(allowsFirstPartyTool),
               ...AGENT_RUNTIME_MECHANIC_TOOL_NAMES,
+              ...(sandboxTools ? AGENT_SANDBOX_MECHANIC_TOOL_NAMES : []),
             ]),
           ];
     },
@@ -1203,8 +1237,8 @@ export function agentConfigFirstPartyMcpTools(
   explicit?: readonly FirstPartyMcpToolName[],
 ): FirstPartyMcpToolName[] {
   for (const tool of explicit ?? []) {
-    const owner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
-    if (owner !== "runtime" && capabilityFilteredOut(config, owner)) {
+    const owner: AgentFirstPartyToolOwner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
+    if (!isDerivedAgentToolOwner(owner) && capabilityFilteredOut(config, owner)) {
       throw new AgentConfigError(
         "agent_config_conflict",
         `firstPartyMcpTools lists ${tool}, but agent capability ${owner} is off`,
@@ -1213,8 +1247,8 @@ export function agentConfigFirstPartyMcpTools(
     }
   }
   return baseline.filter((tool) => {
-    const owner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
-    return owner === "runtime" || !capabilityFilteredOut(config, owner);
+    const owner: AgentFirstPartyToolOwner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
+    return isDerivedAgentToolOwner(owner) || !capabilityFilteredOut(config, owner);
   });
 }
 
@@ -1229,9 +1263,9 @@ export function agentConfigAddedFirstPartyMcpTools(
   defaults: readonly FirstPartyMcpToolName[],
 ): FirstPartyMcpToolName[] {
   return defaults.filter((tool) => {
-    const owner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
+    const owner: AgentFirstPartyToolOwner = FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool];
     return (
-      owner !== "runtime" &&
+      !isDerivedAgentToolOwner(owner) &&
       !agentCapabilityEnabled(previous, owner) &&
       agentCapabilityEnabled(next.capabilities, owner)
     );
@@ -1325,7 +1359,7 @@ export function legacyEffectiveAgentCapabilities(input: {
    */
   defaultServerIds?: Iterable<string> | undefined;
 }): ResolvedAgentCapabilities {
-  const selected = new Set<AgentToolCapability>(
+  const selected = new Set<AgentFirstPartyToolOwner>(
     input.firstPartyMcpTools.map((tool) => FIRST_PARTY_MCP_TOOL_CAPABILITIES[tool]),
   );
   const ids = new Set(input.tools.map((tool) => tool.id));

package/src/artifact-catalog.ts

@@ -20,6 +20,8 @@ export const ArtifactCatalogItem = z
     createdAt: z.string().datetime({ offset: true }),
     updatedAt: z.string().datetime({ offset: true }),
     status: z.enum(["active", "archived"]),
+    /** Shared workspace metadata, not content-access authority. */
+    pinned: z.boolean().optional(),
     sourceSessionId: z.string().uuid().optional(),
     versionId: z.string().min(1).max(128).optional(),
     file: RetainedArtifactReferenceSchema.optional(),
@@ -58,3 +60,15 @@ export const ArtifactCatalogListResponse = z
   })
   .strict();
 export type ArtifactCatalogListResponse = z.infer<typeof ArtifactCatalogListResponse>;
+
+export const UpdateArtifactPinRequest = z.object({ pinned: z.boolean() }).strict();
+export type UpdateArtifactPinRequest = z.infer<typeof UpdateArtifactPinRequest>;
+
+export const ArtifactPinResponse = z
+  .object({
+    kind: ArtifactCatalogKind,
+    artifactId: z.string().min(1).max(128),
+    pinned: z.boolean(),
+  })
+  .strict();
+export type ArtifactPinResponse = z.infer<typeof ArtifactPinResponse>;

package/src/bundled-skills.ts

@@ -32,6 +32,19 @@ export function resolveBundledSkillSelection(
   return selected === undefined ? undefined : BundledSkillSelection.parse(selected);
 }
 
+/**
+ * Freeze the defaults a session's agent configuration implies. An agent that
+ * starts from `capabilities: "none"` carries no bundled Opengeni guides unless
+ * the request lists them; an explicit list (including `[]`) is kept exactly,
+ * and `"all"` or legacy (null) configurations keep the bundled defaults.
+ */
+export function bundledSkillSelectionForAgentConfig(
+  selection: BundledSkillId[] | undefined,
+  agentConfig: { from: "all" | "none" } | null | undefined,
+): BundledSkillId[] | undefined {
+  return selection === undefined && agentConfig?.from === "none" ? [] : selection;
+}
+
 // Immutable session configuration, following the existing create-identity
 // metadata convention. Callers cannot set this through arbitrary metadata.
 const BUNDLED_SKILL_SELECTION_KEY = "_opengeni_bundled_skill_ids_v1";

package/src/index.ts

@@ -1,3 +1,4 @@
+import { modelLogoUrl } from "./model-display";
 import {
   ClaudeProviderAccountAuthoritySnapshotV1,
   WORKSPACE_CLAUDE_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1,
@@ -5003,11 +5004,26 @@ export type GitHubAppApiPort = {
   }) => Promise<GitHubAppRepositoryBranchPage>;
 };
 
+export const PromotionalCreditScope = z.object({
+  label: z.string().trim().min(1).max(120),
+  eligibleModelIds: z.array(z.string().trim().min(1).max(200)).min(1).max(40),
+});
+export type PromotionalCreditScope = z.infer<typeof PromotionalCreditScope>;
+
+export const PromotionalCreditBalance = PromotionalCreditScope.extend({
+  grantId: z.string().uuid(),
+  remainingMicros: z.number().int().nonnegative(),
+});
+export type PromotionalCreditBalance = z.infer<typeof PromotionalCreditBalance>;
+
 export const BillingBalance = z.object({
   accountId: z.string().uuid(),
   balanceMicros: z.number().int(),
   currency: z.literal("usd"),
   updatedAt: z.string(),
+  /** General credits, including unrestricted legacy grants. May be negative after use. */
+  generalBalanceMicros: z.number().int().optional(),
+  promotionalCredits: z.array(PromotionalCreditBalance).optional(),
 });
 export type BillingBalance = z.infer<typeof BillingBalance>;
 
@@ -5038,6 +5054,7 @@ export const CreateCheckoutResponse = z.object({
   url: z.string().url(),
   /** The credits this checkout grants once it completes. */
   amountUsd: z.number().optional(),
+  promotionalScope: PromotionalCreditScope.optional(),
 });
 export type CreateCheckoutResponse = z.infer<typeof CreateCheckoutResponse>;
 
@@ -5055,6 +5072,7 @@ export const BillingCheckoutStatus = z.object({
     currency: z.literal("usd"),
     /** True when a coupon covered the whole checkout, so nothing was charged. */
     free: z.boolean(),
+    promotionalScope: PromotionalCreditScope.optional(),
   }),
   balance: BillingBalance.nullable(),
 });
@@ -6709,6 +6727,16 @@ export const SessionGoalContinuation = z.object({
 });
 export type SessionGoalContinuation = z.infer<typeof SessionGoalContinuation>;
 
+/** New admission pauses are specific; the wire field remains open for older peers. */
+export type GoalAdmissionPausedReason =
+  | "model_unavailable"
+  | "model_policy"
+  | "credits"
+  | "budget"
+  | "usage_limit"
+  | "usage_policy"
+  | "allowance";
+
 export const SessionGoal = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -10430,7 +10458,8 @@ export type KnowledgeSourceSyncRunSummary = z.infer<typeof KnowledgeSourceSyncRu
  * means every occurrence is refused until the task or a resource it names
  * changes. Known reasons: `scheduled_authority_unavailable`,
  * `machine_target_unavailable`, `machine_enrollment_inactive`,
- * `variable_set_unavailable`, `rig_version_unavailable` (terminal) and
+ * `variable_set_unavailable`, `rig_version_unavailable`, `scheduled_model_unavailable`
+ * (terminal) and
  * `insufficient_credits`, `allowance_exhausted`, `monthly_model_cost_limit`, `monthly_agent_run_limit`
  * (transient). Readers must tolerate new reasons.
  */
@@ -18098,6 +18127,10 @@ export const ClientModel = /* @__PURE__ */ defineModelContractSchema(() =>
     label: z.string(),
     /** Optional curated compact label for dense UI (e.g. mobile composer). */
     shortLabel: z.string().min(1).max(64).optional(),
+    logoUrl: z
+      .string()
+      .refine((value) => modelLogoUrl({ id: "", logoUrl: value }) !== null)
+      .optional(),
     provider: z.string(), // provider id
     providerLabel: z.string(),
     api: z.enum(["responses", "chat", "anthropic-messages"]),
@@ -18218,6 +18251,8 @@ export const WorkspaceModelCatalogModel =
   /* @__PURE__ */ defineModelContractSchema(() =>
     ClientModel.extend({
       credentialReadiness: ModelCredentialReadinessV1,
+      /** Current funding status, without exposing the organization's balance. */
+      creditFunding: z.enum(["promotional", "general", "unavailable"]).optional(),
       /** Exact workspace-policy verdict without exposing provider identity. */
       policyAllowed: z.boolean().optional(),
       availability: ModelAvailabilityV1,

package/src/model-display.ts

@@ -28,10 +28,23 @@ export type ModelDisplayInput =
   | {
       id: string;
       label?: string | null | undefined;
+      logoUrl?: string | null | undefined;
       upstreamModelId?: string | null | undefined;
       deployment?: { upstreamModelId?: string | null | undefined } | null | undefined;
     };
 
+/** Catalog maker logo; remote images must use HTTPS without embedded credentials. */
+export function modelLogoUrl(input: ModelDisplayInput): string | null {
+  const value = typeof input === "string" ? undefined : input.logoUrl;
+  if (!value || value.length > 2048 || value !== value.trim()) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 const WORDS: Readonly<Record<string, string>> = {
   gpt: "GPT",
   chatgpt: "ChatGPT",