@opengeni/contracts 1.0.2 → 1.1.0

package/dist/connect.js

@@ -1,7 +1,7 @@
 import {
   IntegrationInstanceKey,
   IntegrationSource
-} from "./chunk-X7ETVO4P.js";
+} from "./chunk-VSM752ZW.js";
 import "./chunk-5IXYF6XN.js";
 import "./chunk-NRMCVHAU.js";
 import "./chunk-WYBDERIY.js";

package/dist/connection-authority.js

@@ -6,8 +6,8 @@ import {
   ConnectionUseAuthorizationResult,
   ConnectionUseDenialReason,
   ConnectionUseSelectionSource
-} from "./chunk-46KLD2UH.js";
-import "./chunk-X7ETVO4P.js";
+} from "./chunk-6GXQBK6J.js";
+import "./chunk-VSM752ZW.js";
 import "./chunk-5IXYF6XN.js";
 import "./chunk-NRMCVHAU.js";
 import "./chunk-WYBDERIY.js";

package/dist/google-drive.js

@@ -1,6 +1,6 @@
 import {
   ConnectionMetadata
-} from "./chunk-X7ETVO4P.js";
+} from "./chunk-VSM752ZW.js";
 import "./chunk-5IXYF6XN.js";
 import "./chunk-NRMCVHAU.js";
 import {

package/dist/host-mcp-bindings.js

@@ -3,14 +3,14 @@ import {
 } from "./chunk-KR2V42UZ.js";
 import {
   ConnectionUseAuthoritySnapshot
-} from "./chunk-46KLD2UH.js";
+} from "./chunk-6GXQBK6J.js";
 import {
   HostMcpCreateSelections,
   ManagedUserResourceGrantMode,
   McpServerConnectionRef,
   SessionTenancyVisibility,
   stableJson
-} from "./chunk-X7ETVO4P.js";
+} from "./chunk-VSM752ZW.js";
 import "./chunk-5IXYF6XN.js";
 import "./chunk-NRMCVHAU.js";
 import "./chunk-WYBDERIY.js";

package/dist/index.d.ts

@@ -8537,6 +8537,8 @@ export declare const SessionGoalContinuation: z.ZodObject<{
     holdReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 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 declare const SessionGoal: z.ZodObject<{
     id: z.ZodString;
     accountId: z.ZodString;
@@ -18814,7 +18816,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.
  */

package/dist/index.js

@@ -22,6 +22,7 @@ import {
   AGENT_PROMPT_MODULE_IDS,
   AGENT_PROMPT_MODULE_TITLES,
   AGENT_RUNTIME_MECHANIC_TOOL_NAMES,
+  AGENT_SANDBOX_MECHANIC_TOOL_NAMES,
   AGENT_SKILL_MANAGE_TOOL_NAMES,
   AGENT_SKILL_READ_TOOL_NAMES,
   ANALYTICS_MODEL_PROVIDERS,
@@ -112,6 +113,7 @@ import {
   ArtifactCatalogKind,
   ArtifactCatalogListQuery,
   ArtifactCatalogListResponse,
+  ArtifactPinResponse,
   AssignableWorkspaceMemberRole,
   AtlassianBrowseItem,
   AtlassianBrowseResponse,
@@ -1685,6 +1687,7 @@ import {
   UninstallPluginResult,
   UninstallSkillRequest,
   UninstallSkillResult,
+  UpdateArtifactPinRequest,
   UpdateAutomationSourceRequest,
   UpdateAutomationTriggerRequest,
   UpdateBrowserIdentityRequest,
@@ -1997,6 +2000,7 @@ import {
   boundSessionMcpText,
   boundWorkspaceControlEvent,
   boundedTaskNoteText,
+  bundledSkillSelectionForAgentConfig,
   bundledSkillSelectionFromMetadata,
   canonicalCodexFleetReplayJsonV1,
   canonicalModalCheckpointProviderBinding,
@@ -2041,6 +2045,7 @@ import {
   isAgentConfigError,
   isChildLifecycleSystemUpdateKind,
   isClearedRunStateBlob,
+  isDerivedAgentToolOwner,
   isDirectModelId,
   isModelUnavailableError,
   isOpenSuffixRunStateBlob,
@@ -2167,7 +2172,7 @@ import {
   workspaceLearningPolicyRouterContext,
   workspaceLearningSourceKey,
   workspaceSlackReactionChannelAllowed
-} from "./chunk-X7ETVO4P.js";
+} from "./chunk-VSM752ZW.js";
 import {
   COMPUTER_SCREENSHOT_MAX_BYTES,
   COMPUTER_SCREENSHOT_MAX_DIMENSION,
@@ -2602,6 +2607,7 @@ export {
   AGENT_PROMPT_MODULE_IDS,
   AGENT_PROMPT_MODULE_TITLES,
   AGENT_RUNTIME_MECHANIC_TOOL_NAMES,
+  AGENT_SANDBOX_MECHANIC_TOOL_NAMES,
   AGENT_SKILL_MANAGE_TOOL_NAMES,
   AGENT_SKILL_READ_TOOL_NAMES,
   ANALYTICS_MODEL_PROVIDERS,
@@ -2697,6 +2703,7 @@ export {
   ArtifactCatalogKind,
   ArtifactCatalogListQuery,
   ArtifactCatalogListResponse,
+  ArtifactPinResponse,
   AssignableWorkspaceMemberRole,
   AtlassianBrowseItem,
   AtlassianBrowseResponse,
@@ -4494,6 +4501,7 @@ export {
   UninstallPluginResult,
   UninstallSkillRequest,
   UninstallSkillResult,
+  UpdateArtifactPinRequest,
   UpdateAutomationSourceRequest,
   UpdateAutomationTriggerRequest,
   UpdateBrowserIdentityRequest,
@@ -4856,6 +4864,7 @@ export {
   boundedTaskNoteText,
   browserSessionStorageMode,
   buildOpenGeniSlackBotManifest,
+  bundledSkillSelectionForAgentConfig,
   bundledSkillSelectionFromMetadata,
   canonicalCodexFleetReplayJsonV1,
   canonicalModalCheckpointProviderBinding,
@@ -4945,6 +4954,7 @@ export {
   isAgentConfigError,
   isChildLifecycleSystemUpdateKind,
   isClearedRunStateBlob,
+  isDerivedAgentToolOwner,
   isDirectModelId,
   isModelUnavailableError,
   isOpenSuffixRunStateBlob,

package/dist/personal-github.js

@@ -1,6 +1,6 @@
 import {
   ConnectionMetadata
-} from "./chunk-X7ETVO4P.js";
+} from "./chunk-VSM752ZW.js";
 import "./chunk-5IXYF6XN.js";
 import "./chunk-NRMCVHAU.js";
 import "./chunk-WYBDERIY.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {

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

@@ -6709,6 +6709,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 +10440,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.
  */