@opengeni/api-router 3.0.1-canary.0 → 3.0.1-canary.2

package/dist/integrations/marketplace-plugin.d.ts

@@ -52,8 +52,8 @@ export declare function marketplacePlugin(url: string): {
         category: string;
         keywords: never[];
         author: {
-            name: string;
             url?: never;
+            name: string;
             email?: never;
         };
         version: string;
@@ -78,9 +78,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
+                url?: never;
                 source: string;
                 path: string;
-                url?: never;
             };
             policy: {
                 installation: string;
@@ -124,9 +124,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
+                url?: never;
                 source: string;
                 path: string;
-                url?: never;
             };
             policy: {
                 installation: string;
@@ -170,9 +170,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
+                url?: never;
                 source: string;
                 path: string;
-                url?: never;
             };
             policy: {
                 installation: string;
@@ -216,9 +216,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
+                url?: never;
                 source: string;
                 path: string;
-                url?: never;
             };
             policy: {
                 installation: string;
@@ -262,9 +262,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
+                url?: never;
                 source: string;
                 path: string;
-                url?: never;
             };
             policy: {
                 installation: string;
@@ -308,9 +308,9 @@ export declare function marketplacePlugin(url: string): {
         installation: string;
         upstream: {
             source: {
+                url?: never;
                 source: string;
                 path: string;
-                url?: never;
             };
             policy: {
                 installation: string;

package/dist/mcp/scheduled-task-view.d.ts

@@ -82,8 +82,8 @@ export declare function scheduledTaskMcpSummary(task: ScheduledTask): {
     runMode: "existing_session" | "new_session_per_run" | "reusable_session";
     overlapPolicy: "allow_concurrent" | "buffer_one" | "skip";
     action: {
-        readonly sourceId?: never;
         kind: "agent_turn";
+        sourceId?: never;
         sourceGeneration?: never;
         sourceLifecycleGeneration?: never;
         destination?: never;
@@ -205,8 +205,8 @@ export declare function boundScheduledTaskDetailMcp(task: ScheduledTask): {
     runMode: "existing_session" | "new_session_per_run" | "reusable_session";
     overlapPolicy: "allow_concurrent" | "buffer_one" | "skip";
     action: {
-        readonly sourceId?: never;
         kind: "agent_turn";
+        sourceId?: never;
         sourceGeneration?: never;
         sourceLifecycleGeneration?: never;
         destination?: never;
@@ -389,8 +389,8 @@ export declare function boundScheduledTaskMcpPage(input: {
         runMode: "existing_session" | "new_session_per_run" | "reusable_session";
         overlapPolicy: "allow_concurrent" | "buffer_one" | "skip";
         action: {
-            readonly sourceId?: never;
             kind: "agent_turn";
+            sourceId?: never;
             sourceGeneration?: never;
             sourceLifecycleGeneration?: never;
             destination?: never;

package/dist/routes/sessions.d.ts

@@ -1,5 +1,5 @@
-import { ClientSessionEvent, SteerSessionMessageRequest, type SessionStatus, type WorkClaimSubjectFilter, type SessionGoalRevision, type SessionAuthorizationOperation } from "@opengeni/contracts";
-import { type SessionDiscoveryCursor } from "@opengeni/db";
+import { ClientSessionEvent, SessionScopeSubjectId, SteerSessionMessageRequest, type SessionStatus, type WorkClaimSubjectFilter, type SessionGoalRevision, type SessionAuthorizationOperation } from "@opengeni/contracts";
+import { decodeSessionListCursor, type SessionDiscoveryCursor } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { type ViewerServices } from "../sandbox/viewer.js";
@@ -13,6 +13,28 @@ export declare function goalProposalMatchesExpectedRevision(revision: Pick<Sessi
  */
 export declare function sessionAuthorizationOperationForHttp(method: string, pathname: string, sessionId: string): SessionAuthorizationOperation | null;
 export declare function sessionTenancyHttpError(error: unknown): Error;
+export declare function sessionListQuery(query: Record<string, string>, allowCursor?: boolean): {
+    originSiteId: string | undefined;
+    limit: string | undefined;
+    parentSessionId: string | null | undefined;
+    cursor: ReturnType<typeof decodeSessionListCursor> | undefined;
+    search: string | undefined;
+    pinsOnly: boolean;
+    archivedOnly: boolean;
+    sortBy: "updatedAt" | "createdAt" | "name" | undefined;
+    archiveStatus: "active" | "archived" | "all" | undefined;
+    channelId: string | null | undefined;
+    createdBy: {
+        kind: "subject" | "service";
+        subjectId: string;
+    } | undefined;
+    updatedFrom: Date | undefined;
+    updatedBefore: Date | undefined;
+    createdFrom: Date | undefined;
+    createdBefore: Date | undefined;
+    scopeSubjectId: SessionScopeSubjectId | undefined;
+    hasPageFilters: boolean;
+};
 export type AgentTopologyCursorEnvelope = {
     cursor: SessionDiscoveryCursor;
     parentSessionId: string | null | "all";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "3.0.1-canary.0",
+  "version": "3.0.1-canary.2",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,24 +43,24 @@
     "@hono/zod-validator": "^0.7.6",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.6.0-canary.5",
-    "@opengeni/artifact-tool": "^0.3.29-canary.0",
-    "@opengeni/capabilities": "^0.3.4-canary.0",
-    "@opengeni/codemode": "^0.5.9-canary.0",
-    "@opengeni/codex": "^0.2.23-canary.2",
-    "@opengeni/config": "^1.2.2-canary.0",
-    "@opengeni/contracts": "^4.1.0-canary.0",
-    "@opengeni/core": "^3.0.1-canary.0",
-    "@opengeni/db": "^5.0.1-canary.0",
-    "@opengeni/documents": "^0.8.30-canary.0",
-    "@opengeni/events": "^0.4.28-canary.0",
-    "@opengeni/github": "^0.7.13-canary.0",
-    "@opengeni/network": "^0.3.1-canary.17",
-    "@opengeni/observability": "^0.8.29-canary.0",
-    "@opengeni/runtime": "^3.0.1-canary.0",
-    "@opengeni/storage": "^0.2.130-canary.0",
-    "@opengeni/tool-gateway": "^0.1.10-canary.0",
-    "@opengeni/xai-subscription": "^0.1.4-canary.17",
+    "@opengeni/agent-proto": "^0.6.0-canary.7",
+    "@opengeni/artifact-tool": "^0.3.29-canary.2",
+    "@opengeni/capabilities": "^0.3.4-canary.2",
+    "@opengeni/codemode": "^0.5.9-canary.2",
+    "@opengeni/codex": "^0.2.23-canary.4",
+    "@opengeni/config": "^1.2.2-canary.2",
+    "@opengeni/contracts": "^4.1.0-canary.2",
+    "@opengeni/core": "^3.0.1-canary.2",
+    "@opengeni/db": "^5.0.1-canary.2",
+    "@opengeni/documents": "^0.8.30-canary.2",
+    "@opengeni/events": "^0.4.28-canary.2",
+    "@opengeni/github": "^0.7.13-canary.2",
+    "@opengeni/network": "^0.3.1-canary.19",
+    "@opengeni/observability": "^0.8.29-canary.2",
+    "@opengeni/runtime": "^3.0.1-canary.2",
+    "@opengeni/storage": "^0.2.130-canary.2",
+    "@opengeni/tool-gateway": "^0.1.10-canary.2",
+    "@opengeni/xai-subscription": "^0.1.4-canary.19",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/editable-artifact-production.ts

@@ -47,6 +47,7 @@ import {
   PostgresEditableArtifactStore,
   listEditableArtifactIdsForSession,
   touchEditableArtifactSessionLink,
+  recordNativeDocumentInspection,
   dbSql,
   withRlsContext,
   type Database,
@@ -167,6 +168,11 @@ export async function createStandaloneEditableArtifactApplication(input: {
         await touchEditableArtifactSessionLink(input.db, scope, sessionId, artifactId),
     } satisfies EditableArtifactAgentAssociationPort),
     inspector: kernel,
+    recordInspection: async (inspection) => {
+      if (inspection.actor.kind !== "agent")
+        throw new Error("Inspection proof requires an agent attempt");
+      return recordNativeDocumentInspection(input.db, { ...inspection, actor: inspection.actor });
+    },
     officeImports,
     workspaceFiles: new EditableArtifactWorkspaceFileAdapter({
       db: input.db,

package/src/mcp/editable-artifacts.ts

@@ -38,6 +38,7 @@ const ArtifactCommand = z
 const ArtifactMetadata = z
   .object({
     id: ArtifactId,
+    artifactReference: z.string(),
     modality: Modality,
     title: z.string(),
     lifecycle: z.enum(["active", "archived"]),
@@ -203,13 +204,17 @@ export function registerEditableArtifactAgentTools(
     {
       title: "Inspect editable artifact",
       description:
-        "Query the artifact's current canonical head through the same native kernel used by the browser. Use bounded modality queries; results are current, not a sandbox-file snapshot.",
+        "Query the artifact's current canonical head through the same native kernel used by the browser. Use bounded modality queries; results are current, not a sandbox-file snapshot. Native document queries return a server-issued inspectionReceiptId; use a post-edit body inspection receipt for declared report completion. If the document changes during inspection, retry against its current head.",
       inputSchema: {
         artifactId: ArtifactId,
         modality: Modality,
         request: EditableArtifactQueryRequestSchema,
       },
-      outputSchema: { artifact: ArtifactMetadata, projection: z.unknown() },
+      outputSchema: {
+        artifact: ArtifactMetadata,
+        projection: z.unknown(),
+        inspectionReceiptId: z.string().uuid().optional(),
+      },
       annotations: readOnlyAnnotations("Inspect editable artifact"),
     },
     async ({ artifactId, modality, request }, extra) =>

package/src/mcp/server.ts

@@ -18,6 +18,8 @@ import {
   CreateScheduledTaskRequest,
   CreateSessionRequest,
   GoalSpec,
+  SessionGoalReportRequirements,
+  SessionGoalReportDeliveries,
   boundSessionMcpText as capSessionDiscoveryText,
   compactSessionMcpListRow,
   sessionMcpIncludesRelatedWork,
@@ -160,6 +162,7 @@ import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/ser
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { HTTPException } from "hono/http-exception";
 import * as z4 from "zod/v4";
+import { editableArtifactActorForGrant } from "../routes/editable-artifacts";
 import { registerKnowledgeEntryTools } from "./knowledge-entries";
 import {
   FIRST_PARTY_TOOL_AUTHORIZATION,
@@ -2420,7 +2423,7 @@ function registerGoalTools(
     "goal_set",
     {
       description:
-        "Create a goal when this session has none, or replace a completed goal with a new one. While active, idle moments synthesize continuation turns until goal_complete or goal_pause. To change an active or paused goal, use goal_update with its objective revision, a change kind, and rationale.",
+        "Create a goal when this session has none, or replace a completed goal with a new one. Declare user-facing native document reports with reportRequirements before producing them. While active, idle moments synthesize continuation turns until goal_complete or goal_pause. To change an active or paused goal, use goal_update with its objective revision, a change kind, and rationale.",
       // `maxAutoContinuations` is deliberately not agent-facing: the ceiling is
       // API/scheduled-task pacing configuration, and an agent that set its own
       // cap used to silence its orchestration for hours. Continuation pacing is
@@ -2428,9 +2431,10 @@ function registerGoalTools(
       inputSchema: {
         text: goalText,
         successCriteria: successCriteriaSchema.optional(),
+        reportRequirements: SessionGoalReportRequirements.optional(),
       },
     },
-    async ({ text, successCriteria }) => {
+    async ({ text, successCriteria, reportRequirements }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
@@ -2444,15 +2448,24 @@ function registerGoalTools(
           ? (grant.metadata["turnId"] as string)
           : null;
       await assertGoalReactivationAllowed(deps, grant.workspaceId, sessionId, callerTurnId);
+      const context = exactAgentCommandContext(grant, sessionId);
       const { goal, replaced, events } = await upsertSessionGoalWithEvent(deps.db, {
         accountId: grant.accountId,
         workspaceId: grant.workspaceId,
         sessionId,
         text,
         successCriteria: successCriteria ?? null,
+        ...(reportRequirements !== undefined ? { reportRequirements } : {}),
         maxAutoContinuations: null,
         createdBy: "agent",
         actor: "agent",
+        commandActor: {
+          type: "agent_attempt",
+          sessionId: context.callerSessionId,
+          turnId: context.callerTurnId,
+          attemptId: context.callerAttemptId,
+          executionGeneration: context.callerExecutionGeneration,
+        },
       });
       if (events.length > 0) {
         await deps.bus.publish(grant.workspaceId, sessionId, events);
@@ -2540,13 +2553,14 @@ function registerGoalTools(
     "goal_progress",
     {
       description:
-        "Record concrete progress toward the unchanged active goal. This does not change goal text, success criteria, mutation policy, or objective revision. Do not use it merely to keep the continuation loop alive.",
+        "Record concrete progress toward the unchanged active goal. Optionally append reportRequirements for secondary user-facing reports discovered during other work; existing requirement IDs and titles cannot be changed or removed. This does not change goal text, success criteria, mutation policy, or objective revision. Do not use it merely to keep the continuation loop alive.",
       inputSchema: {
         progressNote: progressNoteSchema,
         idempotencyKey: z4.string().uuid(),
+        reportRequirements: SessionGoalReportRequirements.optional(),
       },
     },
-    async ({ progressNote, idempotencyKey }) => {
+    async ({ progressNote, idempotencyKey, reportRequirements }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       const context = exactAgentCommandContext(grant, sessionId);
       const { goal, events, operationId, replay } = await recordSessionGoalProgressWithEvent(
@@ -2555,6 +2569,7 @@ function registerGoalTools(
         sessionId,
         {
           progressNote,
+          ...(reportRequirements !== undefined ? { reportRequirements } : {}),
           command: {
             accountId: grant.accountId,
             actor: {
@@ -2635,16 +2650,23 @@ function registerGoalTools(
     "goal_complete",
     {
       description:
-        "Mark the session goal as completed. Requires concrete evidence (what was done and how it satisfies the success criteria). Completion prevents further continuation turns.",
-      inputSchema: { evidence: z4.string().min(1) },
+        "Mark the session goal as completed with concrete evidence. Every persisted report requirement must have a matching reportDeliveries entry containing a native document artifactId and its server-issued inspectionReceiptId from a post-edit body inspection. Missing, stale, inaccessible or summary-only proof fails; inspect again after an edit. Omit reportDeliveries only when no reports were declared. Successful completion returns report artifact references and prevents further continuation turns.",
+      inputSchema: {
+        evidence: z4.string().min(1),
+        reportDeliveries: SessionGoalReportDeliveries.optional(),
+      },
     },
-    async ({ evidence }) => {
+    async ({ evidence, reportDeliveries }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
       if (!existing) {
         throw new Error("this session has no goal; use goal_set first");
       }
+      const context = exactAgentCommandContext(grant, sessionId);
+      const reportArtifactActor = editableArtifactActorForGrant(grant, "0000000000000001");
+      if (reportArtifactActor.kind !== "agent")
+        throw new Error("Goal completion requires exact agent authority");
       const { goal, events } = await setSessionGoalStatusWithEvent(
         deps.db,
         grant.workspaceId,
@@ -2652,6 +2674,15 @@ function registerGoalTools(
         {
           status: "completed",
           evidence,
+          ...(reportDeliveries !== undefined ? { reportDeliveries } : {}),
+          reportArtifactActor,
+          commandActor: {
+            type: "agent_attempt",
+            sessionId: context.callerSessionId,
+            turnId: context.callerTurnId,
+            attemptId: context.callerAttemptId,
+            executionGeneration: context.callerExecutionGeneration,
+          },
           event: { type: "goal.completed", evidence },
         },
       );
@@ -2659,8 +2690,8 @@ function registerGoalTools(
       if (events.length > 0) {
         await deps.bus.publish(grant.workspaceId, sessionId, events);
       }
-      return json(
-        mcpMutationReceipt({
+      return json({
+        ...mcpMutationReceipt({
           operation: "goal_complete",
           committed: true,
           outcome: changed ? "updated" : "unchanged",
@@ -2675,7 +2706,13 @@ function registerGoalTools(
           idempotency: { status: "not_supported" },
           nextAction: { tool: "session_get", arguments: { sessionId } },
         }),
-      );
+        reportDeliveries: SessionGoalReportDeliveries.parse(
+          goal.metadata.reportDeliveriesV1 ?? [],
+        ).map((delivery) => ({
+          ...delivery,
+          artifactReference: `[Open report](/workspaces/${grant.workspaceId}/artifacts/editable/${delivery.artifactId})`,
+        })),
+      });
     },
   );
 

package/src/routes/sessions.ts

@@ -708,6 +708,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         ...(query.search ? { search: query.search } : {}),
         ...(query.pinsOnly ? { pinsOnly: true } : {}),
         ...(query.archivedOnly ? { archivedOnly: true } : {}),
+        ...(query.sortBy ? { sortBy: query.sortBy } : {}),
+        ...(query.archiveStatus ? { archiveStatus: query.archiveStatus } : {}),
         ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
         ...(query.channelId !== undefined ? { channelId: query.channelId } : {}),
         ...(query.originSiteId ? { originSiteId: query.originSiteId } : {}),
@@ -2569,10 +2571,17 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   app.delete("/v1/workspaces/:workspaceId/sessions/:sessionId/goal", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const { event } = await clearSessionGoal(db, workspaceId, sessionId);
+    const { event } = await clearSessionGoal(db, workspaceId, sessionId, {
+      actor: grant.principalKind === "agent_attempt" ? "agent" : "api",
+    }).catch((error: unknown) => {
+      if (error instanceof SessionControlConflictError) {
+        throw new HTTPException(409, { message: error.message, cause: error });
+      }
+      throw error;
+    });
     if (event) {
       try {
         await bus.publish(workspaceId, sessionId, [event]);
@@ -4795,7 +4804,7 @@ function eventEnumList<T extends string>(
   });
 }
 
-function sessionListQuery(
+export function sessionListQuery(
   query: Record<string, string>,
   allowCursor = true,
 ): {
@@ -4806,6 +4815,8 @@ function sessionListQuery(
   search: string | undefined;
   pinsOnly: boolean;
   archivedOnly: boolean;
+  sortBy: "updatedAt" | "createdAt" | "name" | undefined;
+  archiveStatus: "active" | "archived" | "all" | undefined;
   channelId: string | null | undefined;
   createdBy: { kind: "subject" | "service"; subjectId: string } | undefined;
   updatedFrom: Date | undefined;
@@ -4852,6 +4863,20 @@ function sessionListQuery(
     throw new HTTPException(400, { message: 'archivedOnly must be the literal "true"' });
   }
   const archivedOnly = query.archivedOnly === "true";
+  const sortBy = z.enum(["updatedAt", "createdAt", "name"]).optional().safeParse(query.sortBy);
+  const archiveStatus = z
+    .enum(["active", "archived", "all"])
+    .optional()
+    .safeParse(query.archiveStatus);
+  if (!sortBy.success || !archiveStatus.success) {
+    throw new HTTPException(400, { message: "Invalid session sortBy or archiveStatus" });
+  }
+  if (archivedOnly && archiveStatus.data !== undefined && archiveStatus.data !== "archived") {
+    throw new HTTPException(400, { message: "archivedOnly conflicts with archiveStatus" });
+  }
+  if (pinsOnly && archiveStatus.data === "archived") {
+    throw new HTTPException(400, { message: "pinsOnly cannot be combined with archived status" });
+  }
   const channelId = query.channelId;
   if (
     channelId !== undefined &&
@@ -4956,6 +4981,8 @@ function sessionListQuery(
     search: search || undefined,
     pinsOnly,
     archivedOnly,
+    sortBy: sortBy.data,
+    archiveStatus: archiveStatus.data,
     channelId: channelId === undefined ? undefined : channelId === "null" ? null : channelId,
     createdBy:
       createdByKind && createdBySubjectId