@opengeni/contracts 2.6.0-canary.0 → 2.7.0

package/src/index.ts

@@ -13,6 +13,12 @@ import { ClientResumableVoiceInputConfig } from "./transcription-recordings";
 import { MediaGenerationResult } from "./video-generation";
 import { KnowledgeProviderCitation } from "./knowledge";
 import { XaiProviderAccountAuthoritySnapshotV1 } from "./xai-provider-account-authority";
+import {
+  MAX_NESTED_AGENT_DEPTH,
+  NestedAgentDepthValue,
+  SessionGoalStatus,
+  SessionStatus,
+} from "./session-topology-primitives";
 
 export * from "./slack-bot-scopes";
 export * from "./slack-task-policy";
@@ -31,6 +37,9 @@ export * from "./interaction";
 export * from "./sandbox-file-artifacts";
 export * from "./permissions";
 export * from "./session-titles";
+export * from "./session-topology-primitives";
+export * from "./agent-topology";
+export * from "./work-claims";
 
 export {
   CreateWorkspaceArtifactRequest,
@@ -149,18 +158,6 @@ export {
   type ModalCheckpointProviderBinding,
 } from "./checkpoint-provider-bindings";
 
-export const SessionStatus = z.enum([
-  "queued",
-  "running",
-  "idle",
-  "requires_action",
-  "recovering",
-  "waiting_capacity",
-  "failed",
-  "cancelled",
-]);
-export type SessionStatus = z.infer<typeof SessionStatus>;
-
 // 12 backends; 3-way enum parity (contracts / sdk / deployment) is pinned by
 // `packages/sdk/test/contract-parity.test.ts`. Every member is ADDITIVE AT THE
 // END (the parity test pins positions): the original four, then the six cloud
@@ -680,10 +677,6 @@ export const ErrorEnvelope = z.object({
 });
 export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
 
-/** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
-export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
-export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
-export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;
 /** A denied child can be one greater than the persisted PostgreSQL int ceiling. */
 export const NestedAgentDepthAttemptValue = z
   .number()
@@ -779,6 +772,8 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "task_note_save",
   "task_note_archive",
   "task_note_replace",
+  "work_claim_upsert",
+  "work_claim_release",
   "knowledge_propose",
   "knowledge_correct",
   "task_note_promote_knowledge",
@@ -5563,9 +5558,6 @@ export type SessionControlState = z.infer<typeof SessionControlState>;
 export const WorkspaceInferenceState = z.enum(["active", "paused"]);
 export type WorkspaceInferenceState = z.infer<typeof WorkspaceInferenceState>;
 
-export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
-export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
-
 export const SessionGoalCreatedBy = z.enum(["api", "agent", "scheduled_task"]);
 export type SessionGoalCreatedBy = z.infer<typeof SessionGoalCreatedBy>;
 
@@ -11725,57 +11717,6 @@ export const SessionListResponse = z.object({
 });
 export type SessionListResponse = z.infer<typeof SessionListResponse>;
 
-/** Compact, bounded session projection for workspace agent-topology browsers. */
-export const AgentTopologySession = z.object({
-  id: z.string().uuid(),
-  title: z.string().nullable(),
-  titleTruncated: z.boolean(),
-  parentSessionId: z.string().uuid().nullable(),
-  rootSessionId: z.string().uuid(),
-  nestedAgentDepth: NestedAgentDepthValue,
-  ancestorPath: z.array(
-    z.object({
-      id: z.string().uuid(),
-      title: z.string().nullable(),
-      titleTruncated: z.boolean(),
-    }),
-  ),
-  status: SessionStatus,
-  pause: z.object({
-    state: z.enum(["active", "paused"]),
-    additionalBlockerCount: z.number().int().nonnegative(),
-    source: z
-      .object({
-        kind: z.enum(["session", "workspace"]),
-        sessionId: z.string().uuid().optional(),
-        displayName: z.string(),
-        displayNameTruncated: z.boolean(),
-      })
-      .nullable(),
-  }),
-  children: z.object({
-    directChildren: z.number().int().nonnegative(),
-    totalDescendants: z.number().int().nonnegative(),
-    runningDescendants: z.number().int().nonnegative(),
-    queuedDescendants: z.number().int().nonnegative(),
-    attentionDescendants: z.number().int().nonnegative(),
-    pausedDescendants: z.number().int().nonnegative(),
-    failedDescendants: z.number().int().nonnegative(),
-    truncated: z.boolean(),
-  }),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-export type AgentTopologySession = z.infer<typeof AgentTopologySession>;
-
-export const AgentTopologyPageResponse = z.object({
-  sessions: z.array(AgentTopologySession),
-  total: z.number().int().nonnegative(),
-  hasMore: z.boolean(),
-  nextCursor: z.string().nullable(),
-});
-export type AgentTopologyPageResponse = z.infer<typeof AgentTopologyPageResponse>;
-
 // Recursive: the TS type is declared first so the schema annotation can carry
 // the FULL recursive shape (a shallow annotation loses type information for
 // contracts consumers after one level of nesting).

package/src/session-topology-primitives.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const SessionStatus = z.enum([
+  "queued",
+  "running",
+  "idle",
+  "requires_action",
+  "recovering",
+  "waiting_capacity",
+  "failed",
+  "cancelled",
+]);
+export type SessionStatus = z.infer<typeof SessionStatus>;
+
+export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
+export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
+
+/** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
+export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
+export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
+export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;

package/src/work-claims.ts

@@ -0,0 +1,266 @@
+import { z } from "zod";
+import { normalizeAutomaticSessionTitle } from "./session-titles";
+
+export const WORK_CLAIM_NAMESPACE_MAX_BYTES = 64;
+export const WORK_CLAIM_CANONICAL_KEY_MAX_BYTES = 512;
+export const WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES = 256;
+export const WORK_CLAIM_VERSION_VALUE_MAX_BYTES = 256;
+export const WORK_CLAIM_ACTIVE_SESSION_CAP = 64;
+export const WORK_CLAIM_DISCOVERY_LIMIT = 8;
+export const WORK_CLAIM_DISCOVERY_DEFAULT_LIMIT = 4;
+export const WORK_DISCOVERY_QUERY_MAX_CHARS = 200;
+export const WORK_DISCOVERY_RECENT_HOURS_MAX = 24 * 365;
+
+const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u;
+const NAMESPACE_PATTERN = /^[a-z0-9](?:[a-z0-9._:-]{0,62}[a-z0-9])?$/u;
+
+function boundedCanonicalText(maxBytes: number, label: string) {
+  return z
+    .string()
+    .min(1)
+    .superRefine((value, context) => {
+      if (value !== value.trim()) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `${label} must not have leading or trailing whitespace`,
+        });
+      }
+      if (value !== value.normalize("NFKC")) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `${label} must use canonical Unicode normalization`,
+        });
+      }
+      if (CONTROL_CHARACTERS.test(value)) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `${label} must not contain control characters`,
+        });
+      }
+      if (utf8Bytes(value) > maxBytes) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
+        });
+      }
+    });
+}
+
+export function normalizeWorkClaimNamespace(value: string): string {
+  return value.normalize("NFKC").trim().toLowerCase();
+}
+
+export function normalizeWorkClaimCanonicalKey(value: string): string {
+  return value.normalize("NFKC").trim();
+}
+
+export function normalizeWorkClaimDisplayLabel(value: string): string | null {
+  const normalized = normalizeAutomaticSessionTitle(value);
+  if (!normalized || utf8Bytes(normalized) > WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES) return null;
+  return normalized;
+}
+
+export const WorkClaimNamespace = z
+  .string()
+  .min(1)
+  .max(WORK_CLAIM_NAMESPACE_MAX_BYTES)
+  .regex(NAMESPACE_PATTERN)
+  .refine((value) => value === normalizeWorkClaimNamespace(value), {
+    message: "work claim namespace must already be canonical lowercase text",
+  });
+export type WorkClaimNamespace = z.infer<typeof WorkClaimNamespace>;
+
+export const WorkClaimCanonicalKey = boundedCanonicalText(
+  WORK_CLAIM_CANONICAL_KEY_MAX_BYTES,
+  "work claim canonical key",
+);
+export type WorkClaimCanonicalKey = z.infer<typeof WorkClaimCanonicalKey>;
+
+export const WorkClaimDisplayLabel = z
+  .string()
+  .min(1)
+  .superRefine((value, context) => {
+    if (utf8Bytes(value) > WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `work claim display label must be at most ${WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES} UTF-8 bytes`,
+      });
+    }
+    if (normalizeWorkClaimDisplayLabel(value) !== value) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "work claim display label must be a safe concise semantic label",
+      });
+    }
+  });
+export type WorkClaimDisplayLabel = z.infer<typeof WorkClaimDisplayLabel>;
+
+export const WorkClaimSubjectType = z.enum([
+  "repository",
+  "branch",
+  "pull_request",
+  "issue",
+  "artifact",
+  "release",
+  "ci_run",
+  "other",
+]);
+export type WorkClaimSubjectType = z.infer<typeof WorkClaimSubjectType>;
+
+export const WorkClaimRole = z.enum(["working", "reviewing", "monitoring", "delivering"]);
+export type WorkClaimRole = z.infer<typeof WorkClaimRole>;
+
+export const WorkClaimState = z.enum(["active", "released", "superseded", "stale"]);
+export type WorkClaimState = z.infer<typeof WorkClaimState>;
+
+export const WorkClaimProvenance = z.enum([
+  "explicit_agent",
+  "user_api",
+  "trusted_integration",
+  "session_resource",
+  "system_lifecycle",
+]);
+export type WorkClaimProvenance = z.infer<typeof WorkClaimProvenance>;
+
+export const WorkClaimVersionKind = z.enum([
+  "git_commit",
+  "branch_head",
+  "pull_request_head",
+  "artifact_version",
+  "release_version",
+  "ci_run",
+  "other",
+]);
+export type WorkClaimVersionKind = z.infer<typeof WorkClaimVersionKind>;
+
+export const WorkClaimVersionValue = boundedCanonicalText(
+  WORK_CLAIM_VERSION_VALUE_MAX_BYTES,
+  "work claim version value",
+);
+export type WorkClaimVersionValue = z.infer<typeof WorkClaimVersionValue>;
+
+export const WorkClaimReleaseReason = z.enum([
+  "completed",
+  "cancelled",
+  "failed",
+  "superseded",
+  "no_longer_active",
+  "corrected",
+  "external_state_changed",
+  "other",
+]);
+export type WorkClaimReleaseReason = z.infer<typeof WorkClaimReleaseReason>;
+
+export const WorkClaimMutationKind = z.enum([
+  "created",
+  "updated",
+  "released",
+  "superseded",
+  "stale",
+]);
+export type WorkClaimMutationKind = z.infer<typeof WorkClaimMutationKind>;
+
+export const WorkClaim = z.object({
+  id: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  rootSessionId: z.string().uuid(),
+  subject: z.object({
+    namespace: WorkClaimNamespace,
+    type: WorkClaimSubjectType,
+    canonicalKey: WorkClaimCanonicalKey,
+    displayLabel: WorkClaimDisplayLabel.nullable(),
+  }),
+  role: WorkClaimRole,
+  state: WorkClaimState,
+  revision: z.number().int().positive(),
+  provenance: WorkClaimProvenance,
+  version: z
+    .object({
+      kind: WorkClaimVersionKind,
+      value: WorkClaimVersionValue,
+    })
+    .nullable(),
+  observedAt: z.string().datetime({ offset: true }),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+  settledAt: z.string().datetime({ offset: true }).nullable(),
+});
+export type WorkClaim = z.infer<typeof WorkClaim>;
+
+export const WorkClaimMutationResult = z.object({
+  claim: WorkClaim,
+  mutation: WorkClaimMutationKind,
+  replayed: z.boolean(),
+});
+export type WorkClaimMutationResult = z.infer<typeof WorkClaimMutationResult>;
+
+export const WorkClaimDiscoverySummary = WorkClaim.pick({
+  id: true,
+  sessionId: true,
+  subject: true,
+  role: true,
+  state: true,
+  revision: true,
+  provenance: true,
+  version: true,
+  observedAt: true,
+  updatedAt: true,
+  settledAt: true,
+});
+export type WorkClaimDiscoverySummary = z.infer<typeof WorkClaimDiscoverySummary>;
+
+export const WorkClaimSubjectFilter = z
+  .object({
+    namespace: WorkClaimNamespace,
+    type: WorkClaimSubjectType,
+    canonicalKey: WorkClaimCanonicalKey,
+  })
+  .strict();
+export type WorkClaimSubjectFilter = z.infer<typeof WorkClaimSubjectFilter>;
+
+export const WorkDiscoveryMatchClass = z.enum(["exact_subject", "title", "goal", "fuzzy"]);
+export type WorkDiscoveryMatchClass = z.infer<typeof WorkDiscoveryMatchClass>;
+
+export const WorkDiscoveryMatchedField = z.enum([
+  "subject",
+  "title",
+  "goal",
+  "claim_key",
+  "claim_label",
+]);
+export type WorkDiscoveryMatchedField = z.infer<typeof WorkDiscoveryMatchedField>;
+
+/**
+ * Deliberately stable bands rather than a raw ranking score. Raw full-text or
+ * trigram values are query-relative and become a misleading cross-query API.
+ */
+export const WorkDiscoveryScoreBand = z.enum(["exact", "strong", "related"]);
+export type WorkDiscoveryScoreBand = z.infer<typeof WorkDiscoveryScoreBand>;
+
+export const WorkDiscoveryMatch = z
+  .object({
+    class: WorkDiscoveryMatchClass,
+    field: WorkDiscoveryMatchedField,
+    scoreBand: WorkDiscoveryScoreBand,
+    claimId: z.string().uuid().nullable(),
+  })
+  .strict();
+export type WorkDiscoveryMatch = z.infer<typeof WorkDiscoveryMatch>;
+
+/**
+ * Provider-neutral related-work evidence. The two literal booleans are part of
+ * the wire contract so a consumer cannot accidentally present a claim as a
+ * lock, authorization grant, ownership transfer, or mandatory instruction.
+ */
+export const WorkDiscoveryProjection = z
+  .object({
+    claims: z.array(WorkClaimDiscoverySummary).max(WORK_CLAIM_DISCOVERY_LIMIT),
+    claimsTruncated: z.boolean(),
+    match: WorkDiscoveryMatch.nullable(),
+    possibleOverlap: z.boolean(),
+    advisoryOnly: z.literal(true),
+    noAdditionalAccess: z.literal(true),
+  })
+  .strict();
+export type WorkDiscoveryProjection = z.infer<typeof WorkDiscoveryProjection>;