@opengeni/contracts 0.44.1 → 1.0.0

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>;

package/src/workspace-instruction-policies.ts

@@ -15,6 +15,7 @@ export type WorkspaceInstructionPolicyScope = z.infer<typeof WorkspaceInstructio
 
 export const WorkspaceInstructionPolicyProvenanceSource = z.enum([
   "human",
+  "agent_learning",
   "onboarding",
   "knowledge_proposal",
   "legacy_import",
@@ -154,6 +155,16 @@ export const WorkspaceInstructionPolicyHead = z.object({
 });
 export type WorkspaceInstructionPolicyHead = z.infer<typeof WorkspaceInstructionPolicyHead>;
 
+export const WorkspaceInstructionPolicyInactiveHead = z.object({
+  workspaceId: z.string().uuid(),
+  ...targetShape,
+  activationVersion: z.number().int().positive(),
+  deactivatedAt: z.string().datetime(),
+});
+export type WorkspaceInstructionPolicyInactiveHead = z.infer<
+  typeof WorkspaceInstructionPolicyInactiveHead
+>;
+
 export const WorkspaceInstructionPolicySnapshotProvenance = z.object({
   source: WorkspaceInstructionPolicyProvenanceSource,
   sourceIdHash: z
@@ -230,6 +241,23 @@ export type WorkspaceInstructionPolicyActivationEvent = z.infer<
   typeof WorkspaceInstructionPolicyActivationEvent
 >;
 
+export const WorkspaceInstructionPolicyDeactivationEvent = z.object({
+  id: z.string().uuid(),
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  ...targetShape,
+  type: z.literal("automatic_deactivate"),
+  activationVersion: z.number().int().positive(),
+  oldRevision: WorkspaceInstructionPolicyRevisionIdentity,
+  actorSubjectId: z.string().min(1),
+  reason: z.string().min(1).max(WORKSPACE_INSTRUCTION_POLICY_REASON_MAX_CHARS),
+  createdAt: z.string().datetime(),
+});
+export type WorkspaceInstructionPolicyDeactivationEvent = z.infer<
+  typeof WorkspaceInstructionPolicyDeactivationEvent
+>;
+
 export const CreateWorkspaceInstructionPolicyDraftRequest = z
   .object({
     operationId: z.string().uuid().optional(),
@@ -279,7 +307,10 @@ export type WorkspaceInstructionPolicyListQuery = z.infer<
 export const WorkspaceInstructionPolicyListResponse = z.object({
   revisions: z.array(WorkspaceInstructionPolicyRevision),
   activeHeads: z.array(WorkspaceInstructionPolicyHead),
+  inactiveHeads: z.array(WorkspaceInstructionPolicyInactiveHead).default([]),
+  inactiveHeadsTruncated: z.boolean().default(false),
   activationEvents: z.array(WorkspaceInstructionPolicyActivationEvent),
+  deactivationEvents: z.array(WorkspaceInstructionPolicyDeactivationEvent).default([]),
   nextAfterRevision: z.number().int().positive().nullable(),
 });
 export type WorkspaceInstructionPolicyListResponse = z.infer<

package/src/workspace-integration-wire.ts

@@ -0,0 +1,99 @@
+/**
+ * Dependency-free wire constants and the OpenGeni-Signature scheme shared by
+ * workspace webhooks and credential providers. Kept free of zod so browser and
+ * React Native bundles can verify signatures without the schema runtime.
+ */
+
+export const WORKSPACE_WEBHOOK_EVENT_TYPES = [
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "session.status.changed",
+  "session.requiresAction",
+  "session.humanInput.requested",
+  "usage.threshold_reached",
+  "usage.exhausted",
+  "usage.period_reset",
+] as const;
+
+/**
+ * Sent only when an administrator presses "Send test event". It is never a
+ * subscribable type: every endpoint can receive it, and a receiver that does
+ * not care acknowledges it with any 2xx.
+ */
+export const OPENGENI_WEBHOOK_TEST_EVENT_TYPE = "webhook.test";
+
+/**
+ * The session, turn and attempt ids of a credential-provider test request
+ * (`purpose: "test"`). A test is not a run, so no real ids exist.
+ */
+export const OPENGENI_TEST_REQUEST_NIL_ID = "00000000-0000-0000-0000-000000000000";
+
+export const OPENGENI_SIGNATURE_HEADER = "OpenGeni-Signature";
+export const OPENGENI_EVENT_ID_HEADER = "OpenGeni-Event-Id";
+export const OPENGENI_DELIVERY_ID_HEADER = "OpenGeni-Delivery-Id";
+export const OPENGENI_SIGNATURE_TOLERANCE_SECONDS = 300;
+
+const encoder = new TextEncoder();
+
+async function hmacSha256Hex(secret: string, message: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+  return Array.from(signature, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function constantTimeEqualHex(left: string, right: string): boolean {
+  if (left.length !== right.length) return false;
+  let difference = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+  }
+  return difference === 0;
+}
+
+/**
+ * `OpenGeni-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>`.
+ * The timestamp is signed so a captured request cannot be replayed later.
+ */
+export async function signOpenGeniPayload(
+  secret: string,
+  body: string,
+  timestampSeconds = Math.floor(Date.now() / 1000),
+): Promise<string> {
+  return `t=${timestampSeconds},v1=${await hmacSha256Hex(secret, `${timestampSeconds}.${body}`)}`;
+}
+
+export type VerifyOpenGeniSignatureInput = {
+  secret: string;
+  /** The exact raw request body, before JSON parsing. */
+  body: string;
+  /** The `OpenGeni-Signature` header value. */
+  signature: string | null | undefined;
+  toleranceSeconds?: number;
+  nowSeconds?: number;
+};
+
+export async function verifyOpenGeniSignature(
+  input: VerifyOpenGeniSignatureInput,
+): Promise<boolean> {
+  if (!input.signature) return false;
+  let timestamp: number | null = null;
+  const candidates: string[] = [];
+  for (const part of input.signature.split(",")) {
+    const [key, value] = part.trim().split("=", 2);
+    if (key === "t" && value && /^\d{1,12}$/.test(value)) timestamp = Number(value);
+    if (key === "v1" && value && /^[0-9a-f]{64}$/.test(value)) candidates.push(value);
+  }
+  if (timestamp === null || candidates.length === 0) return false;
+  const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const tolerance = input.toleranceSeconds ?? OPENGENI_SIGNATURE_TOLERANCE_SECONDS;
+  if (Math.abs(now - timestamp) > tolerance) return false;
+  const expected = await hmacSha256Hex(input.secret, `${timestamp}.${input.body}`);
+  return candidates.some((candidate) => constantTimeEqualHex(candidate, expected));
+}