@opengeni/contracts 2.6.0-canary.0 → 2.9.2-canary.0

package/dist/work-claims.d.ts

@@ -0,0 +1,411 @@
+import { z } from "zod";
+export declare const WORK_CLAIM_NAMESPACE_MAX_BYTES = 64;
+export declare const WORK_CLAIM_CANONICAL_KEY_MAX_BYTES = 512;
+export declare const WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES = 256;
+export declare const WORK_CLAIM_VERSION_VALUE_MAX_BYTES = 256;
+export declare const WORK_CLAIM_ACTIVE_SESSION_CAP = 64;
+export declare const WORK_CLAIM_DISCOVERY_LIMIT = 8;
+export declare const WORK_CLAIM_DISCOVERY_DEFAULT_LIMIT = 4;
+export declare const WORK_DISCOVERY_QUERY_MAX_CHARS = 200;
+export declare const WORK_DISCOVERY_RECENT_HOURS_MAX: number;
+export declare function normalizeWorkClaimNamespace(value: string): string;
+export declare function normalizeWorkClaimCanonicalKey(value: string): string;
+export declare function normalizeWorkClaimDisplayLabel(value: string): string | null;
+export declare const WorkClaimNamespace: z.ZodString;
+export type WorkClaimNamespace = z.infer<typeof WorkClaimNamespace>;
+export declare const WorkClaimCanonicalKey: z.ZodString;
+export type WorkClaimCanonicalKey = z.infer<typeof WorkClaimCanonicalKey>;
+export declare const WorkClaimDisplayLabel: z.ZodString;
+export type WorkClaimDisplayLabel = z.infer<typeof WorkClaimDisplayLabel>;
+export declare const WorkClaimSubjectType: z.ZodEnum<{
+    artifact: "artifact";
+    branch: "branch";
+    ci_run: "ci_run";
+    issue: "issue";
+    other: "other";
+    pull_request: "pull_request";
+    release: "release";
+    repository: "repository";
+}>;
+export type WorkClaimSubjectType = z.infer<typeof WorkClaimSubjectType>;
+export declare const WorkClaimRole: z.ZodEnum<{
+    delivering: "delivering";
+    monitoring: "monitoring";
+    reviewing: "reviewing";
+    working: "working";
+}>;
+export type WorkClaimRole = z.infer<typeof WorkClaimRole>;
+export declare const WorkClaimState: z.ZodEnum<{
+    active: "active";
+    released: "released";
+    stale: "stale";
+    superseded: "superseded";
+}>;
+export type WorkClaimState = z.infer<typeof WorkClaimState>;
+export declare const WorkClaimProvenance: z.ZodEnum<{
+    explicit_agent: "explicit_agent";
+    session_resource: "session_resource";
+    system_lifecycle: "system_lifecycle";
+    trusted_integration: "trusted_integration";
+    user_api: "user_api";
+}>;
+export type WorkClaimProvenance = z.infer<typeof WorkClaimProvenance>;
+export declare const WorkClaimVersionKind: z.ZodEnum<{
+    artifact_version: "artifact_version";
+    branch_head: "branch_head";
+    ci_run: "ci_run";
+    git_commit: "git_commit";
+    other: "other";
+    pull_request_head: "pull_request_head";
+    release_version: "release_version";
+}>;
+export type WorkClaimVersionKind = z.infer<typeof WorkClaimVersionKind>;
+export declare const WorkClaimVersionValue: z.ZodString;
+export type WorkClaimVersionValue = z.infer<typeof WorkClaimVersionValue>;
+export declare const WorkClaimReleaseReason: z.ZodEnum<{
+    cancelled: "cancelled";
+    completed: "completed";
+    corrected: "corrected";
+    external_state_changed: "external_state_changed";
+    failed: "failed";
+    no_longer_active: "no_longer_active";
+    other: "other";
+    superseded: "superseded";
+}>;
+export type WorkClaimReleaseReason = z.infer<typeof WorkClaimReleaseReason>;
+export declare const WorkClaimMutationKind: z.ZodEnum<{
+    created: "created";
+    released: "released";
+    stale: "stale";
+    superseded: "superseded";
+    updated: "updated";
+}>;
+export type WorkClaimMutationKind = z.infer<typeof WorkClaimMutationKind>;
+export declare const WorkClaim: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    rootSessionId: z.ZodString;
+    subject: z.ZodObject<{
+        namespace: z.ZodString;
+        type: z.ZodEnum<{
+            artifact: "artifact";
+            branch: "branch";
+            ci_run: "ci_run";
+            issue: "issue";
+            other: "other";
+            pull_request: "pull_request";
+            release: "release";
+            repository: "repository";
+        }>;
+        canonicalKey: z.ZodString;
+        displayLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    role: z.ZodEnum<{
+        delivering: "delivering";
+        monitoring: "monitoring";
+        reviewing: "reviewing";
+        working: "working";
+    }>;
+    state: z.ZodEnum<{
+        active: "active";
+        released: "released";
+        stale: "stale";
+        superseded: "superseded";
+    }>;
+    revision: z.ZodNumber;
+    provenance: z.ZodEnum<{
+        explicit_agent: "explicit_agent";
+        session_resource: "session_resource";
+        system_lifecycle: "system_lifecycle";
+        trusted_integration: "trusted_integration";
+        user_api: "user_api";
+    }>;
+    version: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            artifact_version: "artifact_version";
+            branch_head: "branch_head";
+            ci_run: "ci_run";
+            git_commit: "git_commit";
+            other: "other";
+            pull_request_head: "pull_request_head";
+            release_version: "release_version";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    observedAt: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    settledAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WorkClaim = z.infer<typeof WorkClaim>;
+export declare const WorkClaimMutationResult: z.ZodObject<{
+    claim: z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        rootSessionId: z.ZodString;
+        subject: z.ZodObject<{
+            namespace: z.ZodString;
+            type: z.ZodEnum<{
+                artifact: "artifact";
+                branch: "branch";
+                ci_run: "ci_run";
+                issue: "issue";
+                other: "other";
+                pull_request: "pull_request";
+                release: "release";
+                repository: "repository";
+            }>;
+            canonicalKey: z.ZodString;
+            displayLabel: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        role: z.ZodEnum<{
+            delivering: "delivering";
+            monitoring: "monitoring";
+            reviewing: "reviewing";
+            working: "working";
+        }>;
+        state: z.ZodEnum<{
+            active: "active";
+            released: "released";
+            stale: "stale";
+            superseded: "superseded";
+        }>;
+        revision: z.ZodNumber;
+        provenance: z.ZodEnum<{
+            explicit_agent: "explicit_agent";
+            session_resource: "session_resource";
+            system_lifecycle: "system_lifecycle";
+            trusted_integration: "trusted_integration";
+            user_api: "user_api";
+        }>;
+        version: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<{
+                artifact_version: "artifact_version";
+                branch_head: "branch_head";
+                ci_run: "ci_run";
+                git_commit: "git_commit";
+                other: "other";
+                pull_request_head: "pull_request_head";
+                release_version: "release_version";
+            }>;
+            value: z.ZodString;
+        }, z.core.$strip>>;
+        observedAt: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        settledAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    mutation: z.ZodEnum<{
+        created: "created";
+        released: "released";
+        stale: "stale";
+        superseded: "superseded";
+        updated: "updated";
+    }>;
+    replayed: z.ZodBoolean;
+}, z.core.$strip>;
+export type WorkClaimMutationResult = z.infer<typeof WorkClaimMutationResult>;
+export declare const WorkClaimDiscoverySummary: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    subject: z.ZodObject<{
+        namespace: z.ZodString;
+        type: z.ZodEnum<{
+            artifact: "artifact";
+            branch: "branch";
+            ci_run: "ci_run";
+            issue: "issue";
+            other: "other";
+            pull_request: "pull_request";
+            release: "release";
+            repository: "repository";
+        }>;
+        canonicalKey: z.ZodString;
+        displayLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    role: z.ZodEnum<{
+        delivering: "delivering";
+        monitoring: "monitoring";
+        reviewing: "reviewing";
+        working: "working";
+    }>;
+    state: z.ZodEnum<{
+        active: "active";
+        released: "released";
+        stale: "stale";
+        superseded: "superseded";
+    }>;
+    revision: z.ZodNumber;
+    provenance: z.ZodEnum<{
+        explicit_agent: "explicit_agent";
+        session_resource: "session_resource";
+        system_lifecycle: "system_lifecycle";
+        trusted_integration: "trusted_integration";
+        user_api: "user_api";
+    }>;
+    version: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            artifact_version: "artifact_version";
+            branch_head: "branch_head";
+            ci_run: "ci_run";
+            git_commit: "git_commit";
+            other: "other";
+            pull_request_head: "pull_request_head";
+            release_version: "release_version";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    observedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    settledAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WorkClaimDiscoverySummary = z.infer<typeof WorkClaimDiscoverySummary>;
+export declare const WorkClaimSubjectFilter: z.ZodObject<{
+    namespace: z.ZodString;
+    type: z.ZodEnum<{
+        artifact: "artifact";
+        branch: "branch";
+        ci_run: "ci_run";
+        issue: "issue";
+        other: "other";
+        pull_request: "pull_request";
+        release: "release";
+        repository: "repository";
+    }>;
+    canonicalKey: z.ZodString;
+}, z.core.$strict>;
+export type WorkClaimSubjectFilter = z.infer<typeof WorkClaimSubjectFilter>;
+export declare const WorkDiscoveryMatchClass: z.ZodEnum<{
+    exact_subject: "exact_subject";
+    fuzzy: "fuzzy";
+    goal: "goal";
+    title: "title";
+}>;
+export type WorkDiscoveryMatchClass = z.infer<typeof WorkDiscoveryMatchClass>;
+export declare const WorkDiscoveryMatchedField: z.ZodEnum<{
+    claim_key: "claim_key";
+    claim_label: "claim_label";
+    goal: "goal";
+    subject: "subject";
+    title: "title";
+}>;
+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 declare const WorkDiscoveryScoreBand: z.ZodEnum<{
+    exact: "exact";
+    related: "related";
+    strong: "strong";
+}>;
+export type WorkDiscoveryScoreBand = z.infer<typeof WorkDiscoveryScoreBand>;
+export declare const WorkDiscoveryMatch: z.ZodObject<{
+    class: z.ZodEnum<{
+        exact_subject: "exact_subject";
+        fuzzy: "fuzzy";
+        goal: "goal";
+        title: "title";
+    }>;
+    field: z.ZodEnum<{
+        claim_key: "claim_key";
+        claim_label: "claim_label";
+        goal: "goal";
+        subject: "subject";
+        title: "title";
+    }>;
+    scoreBand: z.ZodEnum<{
+        exact: "exact";
+        related: "related";
+        strong: "strong";
+    }>;
+    claimId: z.ZodNullable<z.ZodString>;
+}, z.core.$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 declare const WorkDiscoveryProjection: z.ZodObject<{
+    claims: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodString;
+        subject: z.ZodObject<{
+            namespace: z.ZodString;
+            type: z.ZodEnum<{
+                artifact: "artifact";
+                branch: "branch";
+                ci_run: "ci_run";
+                issue: "issue";
+                other: "other";
+                pull_request: "pull_request";
+                release: "release";
+                repository: "repository";
+            }>;
+            canonicalKey: z.ZodString;
+            displayLabel: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        role: z.ZodEnum<{
+            delivering: "delivering";
+            monitoring: "monitoring";
+            reviewing: "reviewing";
+            working: "working";
+        }>;
+        state: z.ZodEnum<{
+            active: "active";
+            released: "released";
+            stale: "stale";
+            superseded: "superseded";
+        }>;
+        revision: z.ZodNumber;
+        provenance: z.ZodEnum<{
+            explicit_agent: "explicit_agent";
+            session_resource: "session_resource";
+            system_lifecycle: "system_lifecycle";
+            trusted_integration: "trusted_integration";
+            user_api: "user_api";
+        }>;
+        version: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<{
+                artifact_version: "artifact_version";
+                branch_head: "branch_head";
+                ci_run: "ci_run";
+                git_commit: "git_commit";
+                other: "other";
+                pull_request_head: "pull_request_head";
+                release_version: "release_version";
+            }>;
+            value: z.ZodString;
+        }, z.core.$strip>>;
+        observedAt: z.ZodString;
+        updatedAt: z.ZodString;
+        settledAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    claimsTruncated: z.ZodBoolean;
+    match: z.ZodNullable<z.ZodObject<{
+        class: z.ZodEnum<{
+            exact_subject: "exact_subject";
+            fuzzy: "fuzzy";
+            goal: "goal";
+            title: "title";
+        }>;
+        field: z.ZodEnum<{
+            claim_key: "claim_key";
+            claim_label: "claim_label";
+            goal: "goal";
+            subject: "subject";
+            title: "title";
+        }>;
+        scoreBand: z.ZodEnum<{
+            exact: "exact";
+            related: "related";
+            strong: "strong";
+        }>;
+        claimId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    possibleOverlap: z.ZodBoolean;
+    advisoryOnly: z.ZodLiteral<true>;
+    noAdditionalAccess: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type WorkDiscoveryProjection = z.infer<typeof WorkDiscoveryProjection>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "2.6.0-canary.0",
+  "version": "2.9.2-canary.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {
@@ -58,6 +58,10 @@
       "types": "./dist/canonical-human-identities.d.ts",
       "import": "./dist/canonical-human-identities.js"
     },
+    "./session-titles": {
+      "types": "./dist/session-titles.d.ts",
+      "import": "./dist/session-titles.js"
+    },
     "./managed-auth-session-sets": {
       "types": "./dist/managed-auth-session-sets.d.ts",
       "import": "./dist/managed-auth-session-sets.js"

package/src/agent-authored-durable-text.ts

@@ -57,8 +57,8 @@ export const AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE =
   "A Skill is durable Agent Knowledge that agents retrieve on demand, so its length is " +
   "retrieval cost rather than standing prompt cost: only its short title and description are composed into " +
   `every session prompt. Keep it under ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters: state the ` +
-  "preference plainly, no numbered procedure and no examples. Put procedure in a Document or Skill and " +
-  "reference it instead.";
+  "trigger and outcome plainly, include only the necessary procedure, checks, and exceptions, and remove " +
+  "background, repeated guidance, and decorative examples.";
 
 export const AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE =
   "Organization identity and mission are mandatory prompt context in every root session across the " +
@@ -84,10 +84,17 @@ export const AGENT_AUTHORED_REMEMBER_CONTENT_TOO_LONG_MESSAGE =
  * preference*. Deliberately not reused for the company profile, which is a
  * descriptive profile rather than an instruction and needs its own wording.
  */
-export const AGENT_AUTHORED_DURABLE_TEXT_STYLE =
-  "Durable text is prompt cost, not a place to be thorough: write one imperative statement in 1-3 sentences, " +
-  "with no numbered steps, no examples, no rationale and no restating of defaults. Prefer several small entries " +
-  "over one long one, and keep procedure in a Document or Skill that the rule references instead of inlining it.";
+export const AGENT_AUTHORED_INSTRUCTION_POLICY_STYLE =
+  "Write the shortest complete imperative rule in 1-3 sentences, with no numbered procedure, examples, " +
+  "rationale, or restated defaults. Split unrelated rules, and move conditional procedure into a Skill.";
+
+export const AGENT_AUTHORED_SKILL_STYLE =
+  "Write one focused Skill with a clear trigger and outcome. Include only the prerequisites, necessary steps, " +
+  "verification, and important failure handling an agent needs to execute it; omit background, repetition, " +
+  "generic advice, and decorative examples. Split unrelated workflows into separate Skills.";
+
+/** @deprecated Use the destination-specific instruction or Skill style. */
+export const AGENT_AUTHORED_DURABLE_TEXT_STYLE = AGENT_AUTHORED_INSTRUCTION_POLICY_STYLE;
 
 /**
  * Actionable over-budget message including the text the caller actually sent,

package/src/agent-topology.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+import {
+  NestedAgentDepthValue,
+  SessionGoalStatus,
+  SessionStatus,
+} from "./session-topology-primitives";
+import { WorkDiscoveryProjection } from "./work-claims";
+
+/** 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,
+  goal: z
+    .object({
+      status: SessionGoalStatus,
+      summary: z.string(),
+      summaryTruncated: z.boolean(),
+    })
+    .nullable(),
+  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(),
+  }),
+  relatedWork: WorkDiscoveryProjection,
+  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(),
+  /** Operator rollout decision for human advisory presentation. */
+  humanAdvisoriesEnabled: z.boolean().optional(),
+  nextCursor: z.string().nullable(),
+});
+export type AgentTopologyPageResponse = z.infer<typeof AgentTopologyPageResponse>;

package/src/company-profile.ts

@@ -296,6 +296,29 @@ export type CompanyProfileMutationResponse = z.infer<typeof CompanyProfileMutati
 export const COMPANY_PROFILE_AGENT_APPROVE_OPTION = "activate" as const;
 export const COMPANY_PROFILE_AGENT_REJECT_OPTION = "skip" as const;
 
+export const CompanyProfileAgentPolicyMode = z.enum(["off", "suggest", "automatic"]);
+export type CompanyProfileAgentPolicyMode = z.infer<typeof CompanyProfileAgentPolicyMode>;
+
+export const CompanyProfileAgentPolicy = z.object({
+  organizationId: z.string().uuid(),
+  mode: CompanyProfileAgentPolicyMode,
+  version: z.number().int().nonnegative(),
+  updatedAt: z.string().datetime({ offset: true }),
+  changed: z.boolean().optional(),
+});
+export type CompanyProfileAgentPolicy = z.infer<typeof CompanyProfileAgentPolicy>;
+
+export const UpdateCompanyProfileAgentPolicyRequest = z
+  .object({
+    mode: CompanyProfileAgentPolicyMode,
+    expectedVersion: z.number().int().nonnegative(),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateCompanyProfileAgentPolicyRequest = z.infer<
+  typeof UpdateCompanyProfileAgentPolicyRequest
+>;
+
 export const CompanyProfileAgentAttempt = z
   .object({
     accountId: z.string().uuid(),
@@ -328,15 +351,37 @@ export type CompanyProfileAgentHumanInputPrompt = z.infer<
   typeof CompanyProfileAgentHumanInputPrompt
 >;
 
-export const CompanyProfileAgentProposalReceipt = z.object({
+export const CompanyProfileAgentReviewRequiredReceipt = z.object({
   status: z.literal("confirmation_required"),
   operationId: z.string().uuid(),
   proposalReceiptId: z.string().uuid(),
   revision: CompanyProfileRevision,
+  policyMode: z.literal("suggest"),
   humanInput: CompanyProfileAgentHumanInputPrompt,
   confirmWith: z.literal("company_profile_confirm"),
   replayed: z.boolean(),
 });
+export type CompanyProfileAgentReviewRequiredReceipt = z.infer<
+  typeof CompanyProfileAgentReviewRequiredReceipt
+>;
+
+export const CompanyProfileAgentAutomaticActivationReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  automaticActivationReceiptId: z.string().uuid(),
+  policyMode: z.literal("automatic"),
+  mutation: CompanyProfileMutationResponse,
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentAutomaticActivationReceipt = z.infer<
+  typeof CompanyProfileAgentAutomaticActivationReceipt
+>;
+
+export const CompanyProfileAgentProposalReceipt = z.discriminatedUnion("status", [
+  CompanyProfileAgentReviewRequiredReceipt,
+  CompanyProfileAgentAutomaticActivationReceipt,
+]);
 export type CompanyProfileAgentProposalReceipt = z.infer<typeof CompanyProfileAgentProposalReceipt>;
 
 export const CompanyProfileAgentConfirmRequest = z