@shipfox/api-agent-access-dto 20.2.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @shipfox/api-agent-access-dto
+
+## 20.2.0
+
+### Minor Changes
+
+- ba481d6: Add the dormant agent-access MCP gateway foundation and shared tool response contracts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipfox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AGENT_ACCESS_ERROR_CODE_MAX_LENGTH, AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH, type AgentAccessEnvelopeDto, type AgentAccessErrorDto, type AgentAccessJsonSchema, type AgentAccessObjectSchema, agentAccessEnvelopeJsonSchema, agentAccessEnvelopeSchema, agentAccessErrorSchema, agentAccessOutputSchema, } from './schemas/envelope.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,qCAAqC,EACrC,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { AGENT_ACCESS_ERROR_CODE_MAX_LENGTH, AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH, agentAccessEnvelopeJsonSchema, agentAccessEnvelopeSchema, agentAccessErrorSchema, agentAccessOutputSchema } from './schemas/envelope.js';
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export {\n  AGENT_ACCESS_ERROR_CODE_MAX_LENGTH,\n  AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH,\n  type AgentAccessEnvelopeDto,\n  type AgentAccessErrorDto,\n  type AgentAccessJsonSchema,\n  type AgentAccessObjectSchema,\n  agentAccessEnvelopeJsonSchema,\n  agentAccessEnvelopeSchema,\n  agentAccessErrorSchema,\n  agentAccessOutputSchema,\n} from './schemas/envelope.js';\n"],"names":["AGENT_ACCESS_ERROR_CODE_MAX_LENGTH","AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH","agentAccessEnvelopeJsonSchema","agentAccessEnvelopeSchema","agentAccessErrorSchema","agentAccessOutputSchema"],"mappings":"AAAA,SACEA,kCAAkC,EAClCC,qCAAqC,EAKrCC,6BAA6B,EAC7BC,yBAAyB,EACzBC,sBAAsB,EACtBC,uBAAuB,QAClB,wBAAwB"}

package/dist/schemas/envelope.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+export declare const AGENT_ACCESS_ERROR_CODE_MAX_LENGTH = 128;
+export declare const AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH = 2048;
+/** A bounded error payload shared by every agent-access tool. */
+export declare const agentAccessErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    retry_after_seconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentAccessErrorDto = z.infer<typeof agentAccessErrorSchema>;
+/**
+ * The wire envelope for both successful and failed tool calls. The relation
+ * between `ok` and the optional payload is checked at runtime below rather
+ * than represented as a top-level JSON-schema union.
+ */
+export declare const agentAccessEnvelopeSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+        retry_after_seconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    response_truncated: z.ZodOptional<z.ZodBoolean>;
+    response_total_bytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentAccessEnvelopeDto = z.infer<typeof agentAccessEnvelopeSchema>;
+export interface AgentAccessJsonSchema {
+    readonly type?: string;
+    readonly [key: string]: unknown;
+}
+export interface AgentAccessObjectSchema extends AgentAccessJsonSchema {
+    readonly type: 'object';
+}
+/** JSON Schema form used in MCP tool descriptors. It intentionally has no top-level oneOf. */
+export declare const agentAccessEnvelopeJsonSchema: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly ok: {
+            readonly type: 'boolean';
+        };
+        readonly result: {};
+        readonly error: {
+            readonly type: 'object';
+            readonly properties: {
+                readonly code: {
+                    readonly type: 'string';
+                    readonly minLength: 1;
+                    readonly maxLength: 128;
+                };
+                readonly message: {
+                    readonly type: 'string';
+                    readonly maxLength: 2048;
+                };
+                readonly retry_after_seconds: {
+                    readonly type: 'integer';
+                    readonly minimum: 1;
+                };
+            };
+            readonly required: readonly ['code'];
+            readonly additionalProperties: false;
+        };
+        readonly response_truncated: {
+            readonly type: 'boolean';
+        };
+        readonly response_total_bytes: {
+            readonly type: 'integer';
+            readonly minimum: 0;
+        };
+    };
+    readonly required: readonly ["ok"];
+    readonly additionalProperties: false;
+};
+/** Adds a tool-specific result schema while preserving the common envelope. */
+export declare function agentAccessOutputSchema(resultSchema?: AgentAccessJsonSchema): AgentAccessObjectSchema;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/schemas/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/schemas/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,kCAAkC,MAAM,CAAC;AACtD,eAAO,MAAM,qCAAqC,OAAO,CAAC;AAI1D,iEAAiE;AACjE,eAAO,MAAM,sBAAsB;;;;kBAMxB,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;kBAsClC,CAAC;AAEL,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE/E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAmBD,8FAA8F;AAC9F,eAAO,MAAM,6BAA6B;mBAClC,QAAQ;;;qBAlBT,IAAI,EAAE,SAAS;;;;qBAGlB,IAAI,EAAE,QAAQ;qBACd,UAAU;yBACR,IAAI;6BAAG,IAAI,EAAE,QAAQ;6BAAE,SAAS,EAAE,CAAC;6BAAE,SAAS;;yBAC9C,OAAO;6BAAG,IAAI,EAAE,QAAQ;6BAAE,SAAS;;yBACnC,mBAAmB;6BAAG,IAAI,EAAE,SAAS;6BAAE,OAAO,EAAE,CAAC;;;qBAEnD,QAAQ,YAAG,MAAM;qBACjB,oBAAoB;;;qBAED,IAAI,EAAE,SAAS;;;qBACb,IAAI,EAAE,SAAS;qBAAE,OAAO,EAAE,CAAC;;;;;CASR,CAAC;AAE7C,+EAA+E;AAC/E,wBAAgB,uBAAuB,CACrC,YAAY,GAAE,qBAA0B,GACvC,uBAAuB,CAKzB"}

package/dist/schemas/envelope.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+export const AGENT_ACCESS_ERROR_CODE_MAX_LENGTH = 128;
+export const AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH = 2048;
+const agentAccessErrorCodeSchema = z.string().min(1).max(AGENT_ACCESS_ERROR_CODE_MAX_LENGTH);
+/** A bounded error payload shared by every agent-access tool. */ export const agentAccessErrorSchema = z.object({
+    code: agentAccessErrorCodeSchema,
+    message: z.string().max(AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH).optional(),
+    retry_after_seconds: z.number().int().min(1).optional()
+}).strict();
+/**
+ * The wire envelope for both successful and failed tool calls. The relation
+ * between `ok` and the optional payload is checked at runtime below rather
+ * than represented as a top-level JSON-schema union.
+ */ export const agentAccessEnvelopeSchema = z.object({
+    ok: z.boolean(),
+    result: z.unknown().optional(),
+    error: agentAccessErrorSchema.optional(),
+    response_truncated: z.boolean().optional(),
+    response_total_bytes: z.number().int().min(0).optional()
+}).strict().superRefine((value, context)=>{
+    if (value.ok && value.result === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: [
+                'result'
+            ],
+            message: 'Successful responses must include result'
+        });
+    }
+    if (value.ok && value.error !== undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: [
+                'error'
+            ],
+            message: 'Successful responses must not include error'
+        });
+    }
+    if (!value.ok && value.error === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: [
+                'error'
+            ],
+            message: 'Failed responses must include error'
+        });
+    }
+    if (!value.ok && value.result !== undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: [
+                'result'
+            ],
+            message: 'Failed responses must not include result'
+        });
+    }
+});
+const agentAccessEnvelopeProperties = {
+    ok: {
+        type: 'boolean'
+    },
+    result: {},
+    error: {
+        type: 'object',
+        properties: {
+            code: {
+                type: 'string',
+                minLength: 1,
+                maxLength: AGENT_ACCESS_ERROR_CODE_MAX_LENGTH
+            },
+            message: {
+                type: 'string',
+                maxLength: AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH
+            },
+            retry_after_seconds: {
+                type: 'integer',
+                minimum: 1
+            }
+        },
+        required: [
+            'code'
+        ],
+        additionalProperties: false
+    },
+    response_truncated: {
+        type: 'boolean'
+    },
+    response_total_bytes: {
+        type: 'integer',
+        minimum: 0
+    }
+};
+/** JSON Schema form used in MCP tool descriptors. It intentionally has no top-level oneOf. */ export const agentAccessEnvelopeJsonSchema = {
+    type: 'object',
+    properties: agentAccessEnvelopeProperties,
+    required: [
+        'ok'
+    ],
+    additionalProperties: false
+};
+/** Adds a tool-specific result schema while preserving the common envelope. */ export function agentAccessOutputSchema(resultSchema = {}) {
+    return {
+        ...agentAccessEnvelopeJsonSchema,
+        properties: {
+            ...agentAccessEnvelopeProperties,
+            result: resultSchema
+        }
+    };
+}
+
+//# sourceMappingURL=envelope.js.map

package/dist/schemas/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/schemas/envelope.ts"],"sourcesContent":["import {z} from 'zod';\n\nexport const AGENT_ACCESS_ERROR_CODE_MAX_LENGTH = 128;\nexport const AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH = 2048;\n\nconst agentAccessErrorCodeSchema = z.string().min(1).max(AGENT_ACCESS_ERROR_CODE_MAX_LENGTH);\n\n/** A bounded error payload shared by every agent-access tool. */\nexport const agentAccessErrorSchema = z\n  .object({\n    code: agentAccessErrorCodeSchema,\n    message: z.string().max(AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH).optional(),\n    retry_after_seconds: z.number().int().min(1).optional(),\n  })\n  .strict();\n\nexport type AgentAccessErrorDto = z.infer<typeof agentAccessErrorSchema>;\n\n/**\n * The wire envelope for both successful and failed tool calls. The relation\n * between `ok` and the optional payload is checked at runtime below rather\n * than represented as a top-level JSON-schema union.\n */\nexport const agentAccessEnvelopeSchema = z\n  .object({\n    ok: z.boolean(),\n    result: z.unknown().optional(),\n    error: agentAccessErrorSchema.optional(),\n    response_truncated: z.boolean().optional(),\n    response_total_bytes: z.number().int().min(0).optional(),\n  })\n  .strict()\n  .superRefine((value, context) => {\n    if (value.ok && value.result === undefined) {\n      context.addIssue({\n        code: 'custom',\n        path: ['result'],\n        message: 'Successful responses must include result',\n      });\n    }\n    if (value.ok && value.error !== undefined) {\n      context.addIssue({\n        code: 'custom',\n        path: ['error'],\n        message: 'Successful responses must not include error',\n      });\n    }\n    if (!value.ok && value.error === undefined) {\n      context.addIssue({\n        code: 'custom',\n        path: ['error'],\n        message: 'Failed responses must include error',\n      });\n    }\n    if (!value.ok && value.result !== undefined) {\n      context.addIssue({\n        code: 'custom',\n        path: ['result'],\n        message: 'Failed responses must not include result',\n      });\n    }\n  });\n\nexport type AgentAccessEnvelopeDto = z.infer<typeof agentAccessEnvelopeSchema>;\n\nexport interface AgentAccessJsonSchema {\n  readonly type?: string;\n  readonly [key: string]: unknown;\n}\n\nexport interface AgentAccessObjectSchema extends AgentAccessJsonSchema {\n  readonly type: 'object';\n}\n\nconst agentAccessEnvelopeProperties = {\n  ok: {type: 'boolean'},\n  result: {},\n  error: {\n    type: 'object',\n    properties: {\n      code: {type: 'string', minLength: 1, maxLength: AGENT_ACCESS_ERROR_CODE_MAX_LENGTH},\n      message: {type: 'string', maxLength: AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH},\n      retry_after_seconds: {type: 'integer', minimum: 1},\n    },\n    required: ['code'],\n    additionalProperties: false,\n  },\n  response_truncated: {type: 'boolean'},\n  response_total_bytes: {type: 'integer', minimum: 0},\n} as const;\n\n/** JSON Schema form used in MCP tool descriptors. It intentionally has no top-level oneOf. */\nexport const agentAccessEnvelopeJsonSchema = {\n  type: 'object',\n  properties: agentAccessEnvelopeProperties,\n  required: ['ok'],\n  additionalProperties: false,\n} as const satisfies AgentAccessObjectSchema;\n\n/** Adds a tool-specific result schema while preserving the common envelope. */\nexport function agentAccessOutputSchema(\n  resultSchema: AgentAccessJsonSchema = {},\n): AgentAccessObjectSchema {\n  return {\n    ...agentAccessEnvelopeJsonSchema,\n    properties: {...agentAccessEnvelopeProperties, result: resultSchema},\n  };\n}\n"],"names":["z","AGENT_ACCESS_ERROR_CODE_MAX_LENGTH","AGENT_ACCESS_ERROR_MESSAGE_MAX_LENGTH","agentAccessErrorCodeSchema","string","min","max","agentAccessErrorSchema","object","code","message","optional","retry_after_seconds","number","int","strict","agentAccessEnvelopeSchema","ok","boolean","result","unknown","error","response_truncated","response_total_bytes","superRefine","value","context","undefined","addIssue","path","agentAccessEnvelopeProperties","type","properties","minLength","maxLength","minimum","required","additionalProperties","agentAccessEnvelopeJsonSchema","agentAccessOutputSchema","resultSchema"],"mappings":"AAAA,SAAQA,CAAC,QAAO,MAAM;AAEtB,OAAO,MAAMC,qCAAqC,IAAI;AACtD,OAAO,MAAMC,wCAAwC,KAAK;AAE1D,MAAMC,6BAA6BH,EAAEI,MAAM,GAAGC,GAAG,CAAC,GAAGC,GAAG,CAACL;AAEzD,+DAA+D,GAC/D,OAAO,MAAMM,yBAAyBP,EACnCQ,MAAM,CAAC;IACNC,MAAMN;IACNO,SAASV,EAAEI,MAAM,GAAGE,GAAG,CAACJ,uCAAuCS,QAAQ;IACvEC,qBAAqBZ,EAAEa,MAAM,GAAGC,GAAG,GAAGT,GAAG,CAAC,GAAGM,QAAQ;AACvD,GACCI,MAAM,GAAG;AAIZ;;;;CAIC,GACD,OAAO,MAAMC,4BAA4BhB,EACtCQ,MAAM,CAAC;IACNS,IAAIjB,EAAEkB,OAAO;IACbC,QAAQnB,EAAEoB,OAAO,GAAGT,QAAQ;IAC5BU,OAAOd,uBAAuBI,QAAQ;IACtCW,oBAAoBtB,EAAEkB,OAAO,GAAGP,QAAQ;IACxCY,sBAAsBvB,EAAEa,MAAM,GAAGC,GAAG,GAAGT,GAAG,CAAC,GAAGM,QAAQ;AACxD,GACCI,MAAM,GACNS,WAAW,CAAC,CAACC,OAAOC;IACnB,IAAID,MAAMR,EAAE,IAAIQ,MAAMN,MAAM,KAAKQ,WAAW;QAC1CD,QAAQE,QAAQ,CAAC;YACfnB,MAAM;YACNoB,MAAM;gBAAC;aAAS;YAChBnB,SAAS;QACX;IACF;IACA,IAAIe,MAAMR,EAAE,IAAIQ,MAAMJ,KAAK,KAAKM,WAAW;QACzCD,QAAQE,QAAQ,CAAC;YACfnB,MAAM;YACNoB,MAAM;gBAAC;aAAQ;YACfnB,SAAS;QACX;IACF;IACA,IAAI,CAACe,MAAMR,EAAE,IAAIQ,MAAMJ,KAAK,KAAKM,WAAW;QAC1CD,QAAQE,QAAQ,CAAC;YACfnB,MAAM;YACNoB,MAAM;gBAAC;aAAQ;YACfnB,SAAS;QACX;IACF;IACA,IAAI,CAACe,MAAMR,EAAE,IAAIQ,MAAMN,MAAM,KAAKQ,WAAW;QAC3CD,QAAQE,QAAQ,CAAC;YACfnB,MAAM;YACNoB,MAAM;gBAAC;aAAS;YAChBnB,SAAS;QACX;IACF;AACF,GAAG;AAaL,MAAMoB,gCAAgC;IACpCb,IAAI;QAACc,MAAM;IAAS;IACpBZ,QAAQ,CAAC;IACTE,OAAO;QACLU,MAAM;QACNC,YAAY;YACVvB,MAAM;gBAACsB,MAAM;gBAAUE,WAAW;gBAAGC,WAAWjC;YAAkC;YAClFS,SAAS;gBAACqB,MAAM;gBAAUG,WAAWhC;YAAqC;YAC1EU,qBAAqB;gBAACmB,MAAM;gBAAWI,SAAS;YAAC;QACnD;QACAC,UAAU;YAAC;SAAO;QAClBC,sBAAsB;IACxB;IACAf,oBAAoB;QAACS,MAAM;IAAS;IACpCR,sBAAsB;QAACQ,MAAM;QAAWI,SAAS;IAAC;AACpD;AAEA,4FAA4F,GAC5F,OAAO,MAAMG,gCAAgC;IAC3CP,MAAM;IACNC,YAAYF;IACZM,UAAU;QAAC;KAAK;IAChBC,sBAAsB;AACxB,EAA6C;AAE7C,6EAA6E,GAC7E,OAAO,SAASE,wBACdC,eAAsC,CAAC,CAAC;IAExC,OAAO;QACL,GAAGF,6BAA6B;QAChCN,YAAY;YAAC,GAAGF,6BAA6B;YAAEX,QAAQqB;QAAY;IACrE;AACF"}