@opengeni/contracts 0.4.0 → 0.6.0

package/package.json

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

package/src/index.ts

@@ -486,6 +486,10 @@ export const Permission = z.enum([
   "api_keys:manage",
   "environments:manage",
   "environments:use",
+  // Attach or rotate per-session third-party MCP server credentials. Deliberately
+  // not part of the worker's default first-party MCP permission set: a sandboxed
+  // agent must not be able to hand itself new bearer credentials.
+  "mcp_servers:attach",
   "goals:manage",
   // Bring-your-own-compute (M5). enrollments:read lists a workspace's machines;
   // enrollments:manage approves a device-flow enrollment (the LOUD whole-machine
@@ -1351,19 +1355,53 @@ export type DocumentSearchRequest = z.infer<typeof DocumentSearchRequest>;
 export const ToolRef = z.object({
   kind: z.literal("mcp"),
   id: z.string().min(1),
-  // Non-fatal-on-connect marker for an AUTO-ATTACHED (workspace-default)
-  // capability MCP server: when true, a connect / tools-list failure (e.g. an
-  // expired capability credential returning 401) must SKIP that server with a
-  // logged warning and let the turn proceed, rather than failing the whole
-  // turn before the model runs. Absent/false ⇒ STRICT: an unavailable server
-  // fails the turn (the contract for EXPLICITLY-requested tools). This flag is
-  // set server-side only, at the default-capability auto-attach seam; it is
-  // stripped from client-supplied tool refs so an explicit request always
-  // stays strict.
+  // Non-fatal-on-connect marker for MCP server refs that can degrade
+  // gracefully. Absent/false is STRICT: the id must be configured and an
+  // unavailable server fails the turn. `optional:true` is preserved for known
+  // servers and makes runtime connect/list failures skip that server; if the
+  // deployment does not configure the id, validation drops the ref. The server
+  // also sets this for auto-attached workspace-default capability MCPs.
   optional: z.boolean().optional(),
 });
 export type ToolRef = z.infer<typeof ToolRef>;
 
+const registryId = /^[A-Za-z0-9_-]+$/;
+const httpsUrl = z.string().url().refine((value) => {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}, { message: "URL must use https" });
+
+export const SessionMcpServerInput = z.object({
+  id: z.string().min(1).regex(registryId),
+  name: z.string().min(1).optional(),
+  url: httpsUrl,
+  allowedTools: z.array(z.string().min(1)).optional(),
+  timeoutMs: z.number().int().positive().optional(),
+  cacheToolsList: z.boolean().optional(),
+  // Write-only credential headers. Values are encrypted at rest and never
+  // returned in session responses or events; response metadata exposes names.
+  headers: z.record(z.string(), z.string()).optional(),
+});
+export type SessionMcpServerInput = z.infer<typeof SessionMcpServerInput>;
+
+export const SessionMcpCredentialUpdateInput = z.object({
+  id: z.string().min(1).regex(registryId),
+  headers: z.record(z.string(), z.string()),
+});
+export type SessionMcpCredentialUpdateInput = z.infer<typeof SessionMcpCredentialUpdateInput>;
+
+export const SessionMcpServerMetadata = z.object({
+  id: z.string().min(1).regex(registryId),
+  name: z.string().min(1).nullable(),
+  url: httpsUrl,
+  headerNames: z.array(z.string()).default([]),
+  credentialVersion: z.number().int().positive(),
+}).strict();
+export type SessionMcpServerMetadata = z.infer<typeof SessionMcpServerMetadata>;
+
 export class ResourceRefConflictError extends Error {
   constructor(message: string) {
     super(message);
@@ -1382,10 +1420,10 @@ export function mergeToolRefs(existing: ToolRef[], additions: ToolRef[]): ToolRe
       order.push(key);
       continue;
     }
-    // Strict wins: if the same server appears both auto-attached (optional) and
-    // explicitly requested (non-optional), the explicit occurrence upgrades the
-    // merged ref to strict — a later explicit request of an already-defaulted
-    // capability MCP must still fail the turn when the server is unavailable.
+    // Strict wins: if the same server appears both optional and strict, the
+    // strict occurrence upgrades the merged ref so an unavailable server fails
+    // the turn. This preserves the fail-loud default when defaults, packs, and
+    // per-turn tool selections are combined.
     if (prior.optional === true && tool.optional !== true) {
       const { optional: _dropped, ...strict } = prior;
       byKey.set(key, strict);
@@ -2145,6 +2183,10 @@ export const Session = z.object({
   initialMessage: z.string(),
   title: z.string().nullable(),
   titleSource: z.enum(["user", "agent"]).nullable(),
+  // Per-session agent persona/system instructions supplied at create. Org-visible
+  // metadata (exposed like title/goal), never a secret and never a timeline event.
+  // null when the session carried none.
+  instructions: z.string().nullable(),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
   metadata: z.record(z.string(), z.unknown()),
@@ -2167,6 +2209,9 @@ export const Session = z.object({
   // Non-default first-party MCP token permissions (manager-style sessions);
   // null means the fixed worker default set.
   firstPartyMcpPermissions: z.array(Permission).nullable(),
+  // Per-session third-party MCP servers, metadata only. Credential values are
+  // write-only and never appear here.
+  mcpServers: z.array(SessionMcpServerMetadata).default([]),
   // The manager session that spawned this one via session_create (set only
   // when the creating grant carried a worker-signed sessionId claim); null for
   // direct API creates and scheduled-task runs. When set, this session's
@@ -2738,6 +2783,15 @@ export type SessionEvent = z.infer<typeof SessionEvent>;
 
 export const CreateSessionRequest = z.object({
   initialMessage: z.string().min(1),
+  // Per-session agent persona/system instructions (org-visible metadata, NOT a
+  // secret). Rides the SAME system-level instructions channel the per-workspace
+  // agentInstructions rides, composed AFTER the workspace persona so it refines
+  // it for this one session — how a host delivers per-agent-type prompts without
+  // leaking them into the user-visible timeline (it is NEVER emitted as an
+  // event, unlike goal/initialMessage). Trimmed, non-empty. The 32768-char cap
+  // matches the codebase's largest free-form string convention (workspace
+  // environment variable values). Absent ⇒ byte-identical to today.
+  instructions: z.string().trim().min(1).max(32768).optional(),
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
   metadata: z.record(z.string(), z.unknown()).default({}),
@@ -2772,6 +2826,9 @@ export const CreateSessionRequest = z.object({
   // the orchestration/environment/github tools. Capped at creation: every
   // requested permission must be held by the creating grant (no escalation).
   firstPartyMcpPermissions: z.array(Permission).optional(),
+  // Third-party MCP servers attached only to this session. Credential headers are
+  // write-only: create responses and events expose only SessionMcpServerMetadata.
+  mcpServers: z.array(SessionMcpServerInput).default([]),
   // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
   // today's behavior (a context-dependent default resolved server-side: from
   // inside a session → "shared" with the creator's box, top-level → "new").
@@ -2807,6 +2864,9 @@ export const ClientSessionEvent = z.discriminatedUnion("type", [
       tools: z.array(ToolRef).default([]),
       model: z.string().min(1).optional(),
       reasoningEffort: ReasoningEffort.optional(),
+      // Header-value rotation only. URL/name/tool settings are immutable after
+      // session create; persisted events expose metadata, never header values.
+      mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
     }),
   }),
   z.object({