@softure-ai/mcp-access 0.2.9 → 0.4.0

package/dist/index.d.ts

@@ -27,6 +27,23 @@ export declare const MCP_RATE_LIMIT_BUCKETS: {
         readonly key: "ip";
     };
 };
+/**
+ * The rate limit buckets of `requireApiToken`, to spread into `security({ buckets })` when the app sets
+ * `apiTokens`: `api` counts requests per client address before the token is looked up (guessing),
+ * `api-token` counts requests per verified token (one script or Shortcut cannot flood a route).
+ */
+export declare const API_TOKEN_RATE_LIMIT_BUCKETS: {
+    readonly api: {
+        readonly limit: 300;
+        readonly windowMinutes: 15;
+        readonly key: "ip";
+    };
+    readonly "api-token": {
+        readonly limit: 120;
+        readonly windowMinutes: 15;
+        readonly key: "subject";
+    };
+};
 /**
  * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
  * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
@@ -60,6 +77,28 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
         pending: string;
         limit: string;
     };
+    apiScopes: {
+        title: string;
+        lead: string;
+        read: string;
+        write: string;
+        writeUnavailable: string;
+    };
+    apiIssue: {
+        title: string;
+        name: string;
+        nameHint: string;
+        scopes: string;
+        submit: string;
+        pending: string;
+    };
+    apiIssued: {
+        title: string;
+        once: string;
+        scopes: string;
+        tokenTitle: string;
+        headerTitle: string;
+    };
     issued: {
         title: string;
         once: string;
@@ -82,6 +121,8 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
     };
     list: {
         title: string;
+        kindMcp: string;
+        kindApi: string;
         empty: string;
         readOnly: string;
         readWrite: string;
@@ -131,9 +172,36 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
         noFields: string;
         fieldRenamed: string;
     };
+    confirmation: {
+        ask: string;
+        fieldDescription: string;
+        invalid: string;
+        otherTool: string;
+        otherAccount: string;
+        expired: string;
+        argumentsChanged: string;
+        estimateChanged: string;
+        used: string;
+    };
     serverInfoTool: {
         description: string;
     };
+    operations: {
+        statusToolDescription: string;
+        cancelToolDescription: string;
+        started: string;
+        queued: string;
+        running: string;
+        cancelRequested: string;
+        succeeded: string;
+        failed: string;
+        cancelled: string;
+        notFound: string;
+        finished: string;
+        taskQueued: string;
+        taskRunning: string;
+        taskCancelRequested: string;
+    };
     errors: {
         "mcp-access": {
             name_required: string;
@@ -143,6 +211,9 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
             grant_not_found: string;
             issue_refused: string;
             write_refused: string;
+            api_disabled: string;
+            scope_required: string;
+            scope_unknown: string;
         };
         auth: {
             unauthenticated: string;
@@ -187,11 +258,26 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
             protectedResource: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodCustom<(origins: import("./origins.js").McpOrigins) => Readonly<Record<string, unknown>>, (origins: import("./origins.js").McpOrigins) => Readonly<Record<string, unknown>>>, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>]>>;
         }, import("zod/v4/core").$strict>>;
     }, import("zod/v4/core").$strict>>;
+    apiTokens: import("zod").ZodOptional<import("zod").ZodObject<{
+        prefix: import("zod").ZodDefault<import("zod").ZodString>;
+        scopes: import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            access: import("zod").ZodEnum<{
+                read: "read";
+                write: "write";
+            }>;
+            description: import("zod").ZodRecord<import("zod").ZodString & import("zod").ZodType<string, string, import("zod/v4/core").$ZodTypeInternals<string, string>>, import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>;
+        examples: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+            title: import("zod").ZodRecord<import("zod").ZodString & import("zod").ZodType<string, string, import("zod/v4/core").$ZodTypeInternals<string, string>>, import("zod").ZodString>;
+            text: import("zod").ZodRecord<import("zod").ZodString & import("zod").ZodType<string, string, import("zod/v4/core").$ZodTypeInternals<string, string>>, import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>>;
+    }, import("zod/v4/core").$strict>>;
 }, import("zod/v4/core").$strict>>;
 export { getAuthorizationHeader, getClaudeCodeCommand, getClaudeCodeLink, getDesktopConfig, getJsonConfig, getMcpClientSetup, type McpClientSetupInput, } from "./client-setup.js";
-export type { AccessTokenStatus, AccessTokenView, IssuedToken, IssueTokenFormState, McpAccessErrorCode, McpIssueRefusal, McpIssueRefusalCode, McpClientSetup, McpServerIdentity, OAuthGrantView, RevokeGrantFormState, RevokeTokenFormState, TokenFormErrorCode, } from "./contract.js";
+export type { AccessTokenKind, AccessTokenStatus, AccessTokenView, ApiTokenErrorCode, ApiTokenExample, ApiTokenIdentity, ApiTokenRefusal, IssuedApiTokenView, IssuedToken, IssueTokenFormState, McpAccessErrorCode, McpIssueRefusal, McpIssueRefusalCode, McpClientSetup, McpServerIdentity, OAuthGrantView, RevokeGrantFormState, RevokeTokenFormState, TokenFormErrorCode, } from "./contract.js";
 export { getTokenErrorMessage, mcpAccessMessages, type McpAccessMessages } from "./messages/index.js";
-export { MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, type McpAccessOptions, type McpAccessOptionsInput, type McpAppOriginResolver, type McpMetadataExtension, type McpOAuthOptions, type McpToolAccess, type McpToolDefinition, type McpToolDefinitionInput, } from "./options.js";
+export { API_SCOPE_PATTERN, API_TOKEN_PREFIX_PATTERN, MAX_API_TOKEN_SCOPES, MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, type ApiScopeDefinition, type ApiTokenOptions, type ApiTokenOptionsInput, type McpAccessOptions, type McpAccessOptionsInput, type McpAppOriginResolver, type McpMetadataExtension, type McpOAuthOptions, type McpToolAccess, type McpToolDefinition, type McpToolDefinitionInput, } from "./options.js";
 export { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 export { readRequestOrigin, type McpOriginRequest, type McpOrigins } from "./origins.js";
 export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants, type OAuthClientRow, type OAuthTokenEndpointAuthMethod } from "./schema.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;IAEjC;;;;OAIG;;;;;;CAE8D,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCA4BpB,CAAC;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,mCAAmC,EACnC,iCAAiC,EACjC,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,4BAA4B,EAAE,MAAM,aAAa,CAAC;AACvJ,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;IAEjC;;;;OAIG;;;;;;CAE8D,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;CAG0B,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAkCpB,CAAC;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,mCAAmC,EACnC,iCAAiC,EACjC,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,4BAA4B,EAAE,MAAM,aAAa,CAAC;AACvJ,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -29,6 +29,15 @@ export const MCP_RATE_LIMIT_BUCKETS = {
      */
     "mcp-oauth": { limit: 60, windowMinutes: 15, key: "ip" },
 };
+/**
+ * The rate limit buckets of `requireApiToken`, to spread into `security({ buckets })` when the app sets
+ * `apiTokens`: `api` counts requests per client address before the token is looked up (guessing),
+ * `api-token` counts requests per verified token (one script or Shortcut cannot flood a route).
+ */
+export const API_TOKEN_RATE_LIMIT_BUCKETS = {
+    api: { limit: 300, windowMinutes: 15, key: "ip" },
+    "api-token": { limit: 120, windowMinutes: 15, key: "subject" },
+};
 /**
  * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
  * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
@@ -36,11 +45,17 @@ export const MCP_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
     manifest: {
         id: MODULE_ID,
-        version: "0.2.9",
+        version: "0.4.0",
         dependsOn: { security: "^0.2.0", auth: "^0.2.0", jobs: "^0.1.1?", ops: "^0.2.0?" },
         dbSchema: "mcp",
-        tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window"],
-        env: [],
+        tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window", "used_confirmations", "operation_tasks"],
+        env: [
+            {
+                name: "MCP_CONFIRMATION_SECRET",
+                required: false,
+                description: "Signs and verifies the confirmation tokens of confirmed tool calls (withConfirmation), at least 32 characters; required only by an app that confirms tool calls. Changing it voids the tokens in flight.",
+            },
+        ],
         switches: [WRITES_ENABLED_SWITCH],
         routes: { ...DEFAULT_MCP_ACCESS_ROUTES },
         mount: [
@@ -64,7 +79,7 @@ export const mcpAccess = defineModule({
 });
 export { getAuthorizationHeader, getClaudeCodeCommand, getClaudeCodeLink, getDesktopConfig, getJsonConfig, getMcpClientSetup, } from "./client-setup.js";
 export { getTokenErrorMessage, mcpAccessMessages } from "./messages/index.js";
-export { MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, } from "./options.js";
+export { API_SCOPE_PATTERN, API_TOKEN_PREFIX_PATTERN, MAX_API_TOKEN_SCOPES, MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, } from "./options.js";
 export { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 export { readRequestOrigin } from "./origins.js";
 export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants } from "./schema.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/jobs/index.d.ts

@@ -9,4 +9,6 @@ export declare const mcpAccessJobSchedules: {
         every: string;
     };
 };
+export { cancelOperation, getOperation, getOperationErrorHints, getOperationStatus, getPollAfterSeconds, MAX_OPERATION_DEDUP_KEY_LENGTH, OPERATION_CANCEL_TOOL_NAME, OPERATION_ORIGIN, OPERATION_STATUS_TOOL_NAME, OPERATION_STATUSES, registerOperationCancelTool, registerOperationStatusTool, startOperation, type GetOperationOptions, type OperationAnswer, type OperationCancelToolOptions, type OperationErrorCode, type OperationJob, type OperationPollOptions, type OperationStatus, type OperationStatusToolOptions, type OperationToolContext, type ReadOperationResult, type StartOperationInput, } from "./operations.js";
+export { DEFAULT_TASK_TTL_SECONDS, getOperationTask, isTasksRequest, MAX_TASK_TTL_SECONDS, MIN_TASK_TTL_SECONDS, registerOperationTasks, TASKS_EXTENSION, type OperationTask, type OperationTaskRequest, type OperationTasksOptions, type OperationTaskStatus, } from "./operation-tasks.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/jobs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAOA,wEAAwE;AACxE,eAAO,MAAM,oBAAoB;IAC/B,+EAA+E;;CAQ1D,CAAC;AAExB,gFAAgF;AAChF,eAAO,MAAM,qBAAqB;;;;CAEL,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAQA,wEAAwE;AACxE,eAAO,MAAM,oBAAoB;IAC/B,+EAA+E;;CAQ1D,CAAC;AAExB,gFAAgF;AAChF,eAAO,MAAM,qBAAqB;;;;CAEL,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,8BAA8B,EAC9B,0BAA0B,EAC1B,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/jobs/index.js

@@ -1,5 +1,6 @@
-// The jobs adapter of @softure-ai/mcp-access: its daily cleanup as a `@softure-ai/jobs` handler and schedule (an
-// optional peer dependency; only apps that import this entry need it).
+// The jobs adapter of @softure-ai/mcp-access: its daily cleanup as a `@softure-ai/jobs` handler and schedule, and long
+// operations as MCP tools (`startOperation`, `get_operation`, `cancel_operation`) or as MCP Tasks
+// (`registerOperationTasks`). Jobs is an optional peer dependency; only apps that import this entry need it.
 import { ok } from "@softure-ai/core";
 import { defineJobHandler } from "@softure-ai/jobs";
 import { z } from "zod";
@@ -19,4 +20,6 @@ export const mcpAccessJobHandlers = {
 export const mcpAccessJobSchedules = {
     "mcp-access.prune": { every: "1d" },
 };
+export { cancelOperation, getOperation, getOperationErrorHints, getOperationStatus, getPollAfterSeconds, MAX_OPERATION_DEDUP_KEY_LENGTH, OPERATION_CANCEL_TOOL_NAME, OPERATION_ORIGIN, OPERATION_STATUS_TOOL_NAME, OPERATION_STATUSES, registerOperationCancelTool, registerOperationStatusTool, startOperation, } from "./operations.js";
+export { DEFAULT_TASK_TTL_SECONDS, getOperationTask, isTasksRequest, MAX_TASK_TTL_SECONDS, MIN_TASK_TTL_SECONDS, registerOperationTasks, TASKS_EXTENSION, } from "./operation-tasks.js";
 //# sourceMappingURL=index.js.map

package/dist/jobs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,uEAAuE;AACvE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAA4C,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+EAA+E;IAC/E,kBAAkB,EAAE,gBAAgB,CAAC;QACnC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;YAC3B,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;KACF,CAAC;CACmB,CAAC;AAExB,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;CACR,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,kGAAkG;AAClG,6GAA6G;AAC7G,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAA4C,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+EAA+E;IAC/E,kBAAkB,EAAE,gBAAgB,CAAC;QACnC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;YAC3B,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;KACF,CAAC;CACmB,CAAC;AAExB,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;CACR,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,8BAA8B,EAC9B,0BAA0B,EAC1B,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,cAAc,GAYf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAKhB,MAAM,sBAAsB,CAAC"}

package/dist/jobs/operation-state.d.ts

@@ -0,0 +1,58 @@
+import { type Job, type JobProgress } from "@softure-ai/jobs";
+import { type JobsContext } from "@softure-ai/jobs/server";
+import type { McpServerIdentity } from "../contract.js";
+/** The origin of every operation's job: the jobs admin page and run log show where it came from. */
+export declare const OPERATION_ORIGIN = "mcp";
+export declare const OPERATION_STATUS_TOOL_NAME = "get_operation";
+export declare const OPERATION_CANCEL_TOOL_NAME = "cancel_operation";
+/** The longest dedup key an app may pass: the column holds 200 characters and the owner's prefix takes 42. */
+export declare const MAX_OPERATION_DEDUP_KEY_LENGTH = 150;
+export declare const OPERATION_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled"];
+/** An operation's status as the assistant reads it: a retrying job is `running`, since the operation has not ended. */
+export type OperationStatus = (typeof OPERATION_STATUSES)[number];
+export type OperationErrorCode = "mcp-access.operation_not_found" | "mcp-access.operation_finished";
+/** How often the assistant is told to ask again: between `minSeconds` (default 2) and `maxSeconds` (default 30). */
+export interface OperationPollOptions {
+    readonly minSeconds?: number;
+    readonly maxSeconds?: number;
+}
+/** The job behind an operation, as `readResult` receives it. */
+export interface OperationJob {
+    readonly id: string;
+    readonly queue: string;
+    readonly payload: unknown;
+    readonly finishedAt: Date | null;
+}
+/** The app's result of a succeeded operation (a URL, an id, counts), read from its own tables; never a secret. */
+export type ReadOperationResult = (job: OperationJob) => unknown;
+/** What `get_operation` answers. `pollAfterSeconds` only while the operation runs, `result` and `errorCode` once ended. */
+export interface OperationAnswer {
+    readonly operationId: string;
+    readonly status: OperationStatus;
+    /** The running attempt's progress (`context.reportProgress`): codes and counts only. */
+    readonly progress: JobProgress | null;
+    readonly pollAfterSeconds?: number;
+    /** True once someone asked a running operation to stop and it has not ended yet. */
+    readonly cancelRequested?: boolean;
+    readonly result?: unknown;
+    /** The failure's code (`lastError`), `jobs.cancelled` for a cancelled operation. */
+    readonly errorCode?: string;
+    /** What the assistant should do next, in a sentence. */
+    readonly message: string;
+}
+export interface GetOperationOptions {
+    readonly readResult?: ReadOperationResult;
+    readonly poll?: OperationPollOptions;
+    readonly statusToolName?: string;
+}
+/** The operation's status: a pending job that has used an attempt is waiting for a retry, so it is `running`. */
+export declare function getOperationStatus(job: Pick<Job, "status" | "attempts">): OperationStatus;
+/** Seconds until the next status call: a quarter of the operation's age, clamped to the poll bounds. */
+export declare function getPollAfterSeconds(ageSeconds: number, poll?: OperationPollOptions): number;
+export declare function describeOperation(ctx: JobsContext, job: Job, options: GetOperationOptions): Promise<OperationAnswer>;
+/** The job behind the caller's operation, or null: not a job, not an operation, or another account's. */
+export declare function findOwnedJob(ctx: JobsContext, identity: McpServerIdentity, operationId: string): Promise<Job | null>;
+export declare function getOwnerPrefix(userId: string): string;
+export declare function getPollMin(poll?: OperationPollOptions): number;
+export declare function fillToolName(text: string, toolName: string): string;
+//# sourceMappingURL=operation-state.d.ts.map

package/dist/jobs/operation-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-state.d.ts","sourceRoot":"","sources":["../../src/jobs/operation-state.ts"],"names":[],"mappings":"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"}

package/dist/jobs/operation-state.js

@@ -0,0 +1,68 @@
+// The state of a long operation (#952) as both answers read it: the polling tools (`get_operation`) and MCP Tasks
+// (#977). An operation is a job of origin `mcp` whose dedup key starts with `mcp:<userId>:`.
+import { JOB_CANCELLED_CODE } from "@softure-ai/jobs";
+import { getJob } from "@softure-ai/jobs/server";
+import { getMcpAccessMessages } from "../server/options.js";
+/** The origin of every operation's job: the jobs admin page and run log show where it came from. */
+export const OPERATION_ORIGIN = "mcp";
+export const OPERATION_STATUS_TOOL_NAME = "get_operation";
+export const OPERATION_CANCEL_TOOL_NAME = "cancel_operation";
+/** The longest dedup key an app may pass: the column holds 200 characters and the owner's prefix takes 42. */
+export const MAX_OPERATION_DEDUP_KEY_LENGTH = 150;
+const DEFAULT_MIN_POLL_SECONDS = 2;
+const DEFAULT_MAX_POLL_SECONDS = 30;
+/** The wait grows with the operation's age: a quarter of the seconds since it started. */
+const POLL_AGE_FACTOR = 0.25;
+export const OPERATION_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled"];
+/** The operation's status: a pending job that has used an attempt is waiting for a retry, so it is `running`. */
+export function getOperationStatus(job) {
+    if (job.status === "pending")
+        return job.attempts === 0 ? "queued" : "running";
+    return job.status;
+}
+/** Seconds until the next status call: a quarter of the operation's age, clamped to the poll bounds. */
+export function getPollAfterSeconds(ageSeconds, poll = {}) {
+    const min = getPollMin(poll);
+    const max = Math.max(min, poll.maxSeconds ?? DEFAULT_MAX_POLL_SECONDS);
+    return Math.min(max, Math.max(min, Math.round(Math.max(0, ageSeconds) * POLL_AGE_FACTOR)));
+}
+export async function describeOperation(ctx, job, options) {
+    const messages = getMcpAccessMessages(ctx.config).operations;
+    const status = getOperationStatus(job);
+    const statusToolName = options.statusToolName ?? OPERATION_STATUS_TOOL_NAME;
+    const base = { operationId: job.id, status, progress: status === "running" ? job.progress : null };
+    if (status === "queued" || status === "running") {
+        const ageSeconds = (ctx.clock.now().getTime() - job.createdAt.getTime()) / 1000;
+        const cancelRequested = job.cancelRequestedAt !== null;
+        return {
+            ...base,
+            pollAfterSeconds: getPollAfterSeconds(ageSeconds, options.poll),
+            ...(cancelRequested ? { cancelRequested } : {}),
+            message: fillToolName(cancelRequested ? messages.cancelRequested : messages[status], statusToolName),
+        };
+    }
+    if (status === "succeeded") {
+        const result = options.readResult === undefined ? undefined : await options.readResult({ id: job.id, queue: job.queue, payload: job.payload, finishedAt: job.finishedAt });
+        return { ...base, ...(result === undefined ? {} : { result }), message: messages.succeeded };
+    }
+    if (status === "cancelled")
+        return { ...base, errorCode: JOB_CANCELLED_CODE, message: messages.cancelled };
+    return { ...base, ...(job.lastError === null ? {} : { errorCode: job.lastError }), message: messages.failed };
+}
+/** The job behind the caller's operation, or null: not a job, not an operation, or another account's. */
+export async function findOwnedJob(ctx, identity, operationId) {
+    const job = await getJob(ctx, operationId);
+    if (job === null || job.origin !== OPERATION_ORIGIN || job.dedupKey?.startsWith(getOwnerPrefix(identity.userId)) !== true)
+        return null;
+    return job;
+}
+export function getOwnerPrefix(userId) {
+    return `${OPERATION_ORIGIN}:${userId}:`;
+}
+export function getPollMin(poll = {}) {
+    return poll.minSeconds ?? DEFAULT_MIN_POLL_SECONDS;
+}
+export function fillToolName(text, toolName) {
+    return text.replaceAll("{tool}", toolName);
+}
+//# sourceMappingURL=operation-state.js.map

package/dist/jobs/operation-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-state.js","sourceRoot":"","sources":["../../src/jobs/operation-state.ts"],"names":[],"mappings":"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"}

package/dist/jobs/operation-tasks.d.ts

@@ -0,0 +1,68 @@
+import { type CallToolResult, type McpServer } from "@modelcontextprotocol/server";
+import { type JobsContext } from "@softure-ai/jobs/server";
+import type { McpServerIdentity } from "../contract.js";
+import { type OperationPollOptions, type ReadOperationResult } from "./operation-state.js";
+/** The extension's identifier, in the client's per-request capabilities and the server's `capabilities.extensions`. */
+export declare const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+export declare const DEFAULT_TASK_TTL_SECONDS = 86400;
+export declare const MIN_TASK_TTL_SECONDS = 60;
+/** Thirty days: a task outlives its operation only so long. */
+export declare const MAX_TASK_TTL_SECONDS = 2592000;
+/** The tool handler's request context (its second argument): only its per-request `_meta` envelope is read. */
+export interface OperationTaskRequest {
+    readonly mcpReq: {
+        readonly envelope?: object;
+    };
+}
+/** A task's status as the extension defines it; operations never ask for input, nor fail at the protocol level. */
+export type OperationTaskStatus = "working" | "completed" | "cancelled";
+/** A task as `tasks/get` answers it. `result` once completed: the `get_operation` answer, `isError` when it failed. */
+export interface OperationTask {
+    readonly taskId: string;
+    readonly status: OperationTaskStatus;
+    readonly statusMessage?: string;
+    /** ISO 8601. */
+    readonly createdAt: string;
+    /** ISO 8601: the job's last change. */
+    readonly lastUpdatedAt: string;
+    readonly ttlMs: number;
+    /** Only while working: the operation's wait (`pollAfterSeconds`) in milliseconds. */
+    readonly pollIntervalMs?: number;
+    readonly result?: CallToolResult;
+}
+/** `ctx`, or `getContext` resolved inside each task request (see `OperationToolContext`). */
+export type OperationTasksOptions = OperationTaskContext & {
+    /** The request's identity: a task is found only for its owner, and only a writer may cancel it. */
+    readonly identity: McpServerIdentity;
+    readonly readResult?: ReadOperationResult;
+    readonly poll?: OperationPollOptions;
+};
+type OperationTaskContext = {
+    readonly ctx: JobsContext;
+    readonly getContext?: never;
+} | {
+    readonly ctx?: never;
+    readonly getContext: () => Promise<JobsContext>;
+};
+export interface AnswerOperationTaskInput {
+    readonly jobId: string;
+    readonly ttlSeconds?: number;
+    readonly poll?: OperationPollOptions;
+}
+/** True when the request's client declared the Tasks extension in its per-request capabilities (revision 2026-07-28). */
+export declare function isTasksRequest(request: OperationTaskRequest): boolean;
+export declare function isTaskTtlValid(seconds: number): boolean;
+/**
+ * The tool's answer as a task (`resultType: "task"`) for the operation's job: stores the task before answering, as the
+ * spec requires, and gives the same account the same task id for the same job.
+ */
+export declare function answerOperationTask(ctx: JobsContext, identity: McpServerIdentity, input: AnswerOperationTaskInput): Promise<CallToolResult>;
+/** The caller's task with its operation's state now; `null` when unknown, another account's, or its job is gone. */
+export declare function getOperationTask(ctx: JobsContext, identity: McpServerIdentity, taskId: string, options?: Pick<OperationTasksOptions, "readResult" | "poll">): Promise<OperationTask | "expired" | null>;
+/**
+ * Serves the Tasks extension on the app's server: declares the capability and answers `tasks/get`, `tasks/update` and
+ * `tasks/cancel` for the request's account. Register it on every server whose tools pass `taskRequest`.
+ */
+export declare function registerOperationTasks(server: McpServer, options: OperationTasksOptions): void;
+export {};
+//# sourceMappingURL=operation-tasks.d.ts.map

package/dist/jobs/operation-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-tasks.d.ts","sourceRoot":"","sources":["../../src/jobs/operation-tasks.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIxD,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,uHAAuH;AACvH,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAC/D,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAQ9C,+GAA+G;AAC/G,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED,mHAAmH;AACnH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;AAExE,uHAAuH;AACvH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB;IAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,6FAA6F;AAC7F,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG;IACzD,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;CACtC,CAAC;AAEF,KAAK,oBAAoB,GACrB;IAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAQD,yHAAyH;AACzH,wBAAgB,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAIrE;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQjJ;AAED,oHAAoH;AACpH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,YAAY,GAAG,MAAM,CAAM,GAC/D,OAAO,CAAC,aAAa,GAAG,SAAS,GAAG,IAAI,CAAC,CAI3C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CA6B9F"}

package/dist/jobs/operation-tasks.js

@@ -0,0 +1,163 @@
+// Long operations as MCP Tasks (#977): the Tasks extension `io.modelcontextprotocol/tasks` of protocol revision
+// 2026-07-28. A client that declares the extension on a tool call gets a task instead of an operation id and follows it
+// through `tasks/get`; every other client keeps the polling tools (`get_operation`, `cancel_operation`) of #952.
+//
+//   registerOperationTasks(server, { ctx, identity, readResult: (job) => findRenderUrl(job.id) });
+//   server.registerTool("render_video", { inputSchema }, (args, request) =>
+//     startOperation(ctx, identity, { queue: "video.render", payload: args, taskRequest: request }));
+//
+// A task id is random (the spec requires ids nobody can guess) and lives in `mcp.operation_tasks` with its owner, the
+// operation's job and an expiry. Every task request checks the owner too, and reads the job's state as it is now.
+import { randomBytes } from "node:crypto";
+import { CLIENT_CAPABILITIES_META_KEY, MissingRequiredClientCapabilityError, ProtocolError, ProtocolErrorCode, } from "@modelcontextprotocol/server";
+import { requestJobCancel } from "@softure-ai/jobs/server";
+import { and, eq, sql } from "drizzle-orm";
+import { z } from "zod";
+import { operationTasks } from "../schema.js";
+import { getMcpAccessMessages } from "../server/options.js";
+import { toolResult } from "../server/tools.js";
+import { describeOperation, findOwnedJob, getOperationStatus, getPollAfterSeconds, } from "./operation-state.js";
+/** The extension's identifier, in the client's per-request capabilities and the server's `capabilities.extensions`. */
+export const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+export const DEFAULT_TASK_TTL_SECONDS = 86_400;
+export const MIN_TASK_TTL_SECONDS = 60;
+/** Thirty days: a task outlives its operation only so long. */
+export const MAX_TASK_TTL_SECONDS = 2_592_000;
+const TASK_ID_BYTES = 32;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TASK_NOT_FOUND = "Failed to retrieve task: Task not found";
+const TASK_EXPIRED = "Failed to retrieve task: Task has expired";
+const CANCEL_NEEDS_WRITE = "Cancelling a task needs a token with write access";
+const taskIdParams = z.looseObject({ taskId: z.string() });
+const taskResult = z.looseObject({});
+const clientCapabilities = z.looseObject({ extensions: z.record(z.string(), z.unknown()).optional() });
+/** True when the request's client declared the Tasks extension in its per-request capabilities (revision 2026-07-28). */
+export function isTasksRequest(request) {
+    const envelope = { ...request.mcpReq.envelope };
+    const capabilities = clientCapabilities.safeParse(envelope[CLIENT_CAPABILITIES_META_KEY]);
+    return capabilities.success && capabilities.data.extensions?.[TASKS_EXTENSION] !== undefined;
+}
+export function isTaskTtlValid(seconds) {
+    return Number.isInteger(seconds) && seconds >= MIN_TASK_TTL_SECONDS && seconds <= MAX_TASK_TTL_SECONDS;
+}
+/**
+ * The tool's answer as a task (`resultType: "task"`) for the operation's job: stores the task before answering, as the
+ * spec requires, and gives the same account the same task id for the same job.
+ */
+export async function answerOperationTask(ctx, identity, input) {
+    const row = await storeTask(ctx, identity, input);
+    const job = await findOwnedJob(ctx, identity, input.jobId);
+    if (job === null)
+        throw new Error(`answerOperationTask: job ${input.jobId} is not an operation of this account`);
+    const task = await describeTask(ctx, row, job, input.poll === undefined ? {} : { poll: input.poll });
+    // On revision 2026-07-28 the SDK passes a tool's own `resultType` through; its `CallToolResult` type does not know
+    // the extension's task shape, and the `content` it would add anyway is ignored by clients.
+    return { content: [], ...task, resultType: "task" };
+}
+/** The caller's task with its operation's state now; `null` when unknown, another account's, or its job is gone. */
+export async function getOperationTask(ctx, identity, taskId, options = {}) {
+    const found = await findTask(ctx, identity, taskId);
+    if (found === null || found === "expired")
+        return found;
+    return describeTask(ctx, found.row, found.job, options);
+}
+/**
+ * Serves the Tasks extension on the app's server: declares the capability and answers `tasks/get`, `tasks/update` and
+ * `tasks/cancel` for the request's account. Register it on every server whose tools pass `taskRequest`.
+ */
+export function registerOperationTasks(server, options) {
+    const { identity } = options;
+    const resolveContext = () => (options.getContext === undefined ? Promise.resolve(options.ctx) : options.getContext());
+    const describeOptions = { ...(options.readResult === undefined ? {} : { readResult: options.readResult }), ...(options.poll === undefined ? {} : { poll: options.poll }) };
+    server.server.registerCapabilities({ extensions: { [TASKS_EXTENSION]: {} } });
+    server.server.setRequestHandler("tasks/get", { params: taskIdParams, result: taskResult }, async ({ taskId }, request) => {
+        requireTasksCapability(request);
+        return { ...(await requireTask(await resolveContext(), identity, taskId, describeOptions)) };
+    });
+    // Operations never ask for input, so there is nothing to update; an owned task is acknowledged, as the spec asks.
+    server.server.setRequestHandler("tasks/update", { params: taskIdParams, result: taskResult }, async ({ taskId }, request) => {
+        requireTasksCapability(request);
+        await requireTask(await resolveContext(), identity, taskId, describeOptions);
+        return {};
+    });
+    server.server.setRequestHandler("tasks/cancel", { params: taskIdParams, result: taskResult }, async ({ taskId }, request) => {
+        requireTasksCapability(request);
+        const ctx = await resolveContext();
+        const found = await findTask(ctx, identity, taskId);
+        if (found === null)
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_NOT_FOUND);
+        if (found === "expired")
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_EXPIRED);
+        if (!identity.canWrite)
+            throw new ProtocolError(ProtocolErrorCode.InvalidRequest, CANCEL_NEEDS_WRITE);
+        // Cancelling is cooperative: an operation that has already ended is acknowledged all the same.
+        await requestJobCancel(ctx, found.job.id);
+        return {};
+    });
+}
+async function storeTask(ctx, identity, input) {
+    const now = ctx.clock.now();
+    const expiresAt = new Date(now.getTime() + (input.ttlSeconds ?? DEFAULT_TASK_TTL_SECONDS) * 1000);
+    // One task per account and job: joining a running operation answers its task again, kept alive at least as long.
+    const [row] = await ctx.db
+        .insert(operationTasks)
+        .values({ taskId: randomBytes(TASK_ID_BYTES).toString("base64url"), userId: identity.userId, jobId: BigInt(input.jobId), createdAt: now, expiresAt })
+        .onConflictDoUpdate({
+        target: [operationTasks.userId, operationTasks.jobId],
+        set: { expiresAt: sql `greatest(${operationTasks.expiresAt}, excluded.expires_at)` },
+    })
+        .returning();
+    if (row === undefined)
+        throw new Error(`answerOperationTask: no task row for job ${input.jobId}`);
+    return row;
+}
+async function findTask(ctx, identity, taskId) {
+    if (!UUID.test(identity.userId))
+        return null;
+    const [row] = await ctx.db
+        .select()
+        .from(operationTasks)
+        .where(and(eq(operationTasks.taskId, taskId), eq(operationTasks.userId, identity.userId)))
+        .limit(1);
+    if (row === undefined)
+        return null;
+    if (row.expiresAt.getTime() <= ctx.clock.now().getTime())
+        return "expired";
+    const job = await findOwnedJob(ctx, identity, row.jobId.toString());
+    return job === null ? null : { row, job };
+}
+async function requireTask(ctx, identity, taskId, options) {
+    const task = await getOperationTask(ctx, identity, taskId, options);
+    if (task === null)
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_NOT_FOUND);
+    if (task === "expired")
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_EXPIRED);
+    return task;
+}
+/** The spec's rule for `tasks/*`: a client that did not declare the extension on this request gets `-32021`. */
+function requireTasksCapability(request) {
+    if (!isTasksRequest(request))
+        throw new MissingRequiredClientCapabilityError({ requiredCapabilities: { extensions: { [TASKS_EXTENSION]: {} } } });
+}
+async function describeTask(ctx, row, job, options) {
+    const messages = getMcpAccessMessages(ctx.config).operations;
+    const status = getOperationStatus(job);
+    const base = {
+        taskId: row.taskId,
+        createdAt: row.createdAt.toISOString(),
+        lastUpdatedAt: job.updatedAt.toISOString(),
+        ttlMs: row.expiresAt.getTime() - row.createdAt.getTime(),
+    };
+    if (status === "queued" || status === "running") {
+        const ageSeconds = (ctx.clock.now().getTime() - job.createdAt.getTime()) / 1000;
+        const statusMessage = job.cancelRequestedAt !== null ? messages.taskCancelRequested : status === "queued" ? messages.taskQueued : messages.taskRunning;
+        return { ...base, status: "working", statusMessage, pollIntervalMs: getPollAfterSeconds(ageSeconds, options.poll) * 1000 };
+    }
+    if (status === "cancelled")
+        return { ...base, status: "cancelled", statusMessage: messages.cancelled };
+    // A failed job is a tool-level failure, not a JSON-RPC error: the spec makes it `completed` with `isError`.
+    const answer = await describeOperation(ctx, job, options);
+    const result = status === "failed" ? { ...toolResult(answer), isError: true } : toolResult(answer);
+    return { ...base, status: "completed", statusMessage: answer.message, result };
+}
+//# sourceMappingURL=operation-tasks.js.map