@agentage/extension 0.0.0-stage → 0.1.1

package/dist/tool/main.js

@@ -0,0 +1,54 @@
+import { parseArgs } from 'node:util';
+import { build } from './build.js';
+import { buildLines } from './format.js';
+export const USAGE = `usage: agentage-extension build [--push] [--dir <path>] [--registry <host/owner>]
+
+  build      one image per server part from the kit recipe
+  --push     push the images and write dist/agentage-extension.json with their digests
+  --dir      the extension package folder (default: the current folder)
+  --registry image registry and owner (default: ghcr.io/agentage)`;
+const defaultDeps = {
+    build: (options) => build(options),
+    out: (line) => void process.stdout.write(`${line}\n`),
+    err: (line) => void process.stderr.write(`${line}\n`),
+};
+const parse = (argv) => parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+        push: { type: 'boolean' },
+        dir: { type: 'string' },
+        registry: { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+    },
+});
+// Exit codes: 0 ok, 1 the build failed, 2 usage.
+export const main = async (argv, deps = defaultDeps) => {
+    let parsed;
+    try {
+        parsed = parse(argv);
+    }
+    catch (err) {
+        deps.err(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    const { positionals, values } = parsed;
+    if (values.help)
+        return (deps.out(USAGE), 0);
+    if (positionals[0] !== 'build' || positionals.length !== 1)
+        return (deps.err(USAGE), 2);
+    try {
+        const result = await deps.build({
+            push: values.push,
+            dir: values.dir,
+            registry: values.registry,
+        });
+        for (const line of buildLines(result))
+            deps.out(line);
+        return 0;
+    }
+    catch (err) {
+        deps.err(`build failed: ${err.message}`);
+        return 1;
+    }
+};

package/dist/tool/recipe.d.ts

@@ -0,0 +1,3 @@
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
+export declare const PART_PORT = 3000;
+export declare const serverPartRecipe: (part: ImagePartKind) => string;

package/dist/tool/recipe.js

@@ -0,0 +1,32 @@
+import {} from '../manifest/primitives.schema.js';
+export const PART_PORT = 3000;
+const HEALTH_PROBE = `fetch('http://127.0.0.1:${PART_PORT}/health')` +
+    '.then((r) => process.exit(r.status === 200 || r.status === 503 ? 0 : 1), () => process.exit(1))';
+// The one recipe for a Node server part; the staged context holds deps/ (npm ci) and app/ (code).
+export const serverPartRecipe = (part) => [
+    '# syntax=docker/dockerfile:1',
+    '# Generated by @agentage/extension build. Extension authors never write a Dockerfile.',
+    'FROM node:26-alpine AS deps',
+    'WORKDIR /app',
+    'COPY deps/ ./',
+    'RUN npm ci --omit=dev --no-audit --no-fund',
+    '',
+    'FROM node:26-alpine AS runner',
+    'ARG COMMIT_SHA',
+    'ARG BUILD_TIME',
+    'ARG IMAGE',
+    'ENV NODE_ENV=production \\',
+    '    NODE_OPTIONS=--enable-source-maps \\',
+    `    PORT=${PART_PORT} \\`,
+    '    COMMIT_SHA=$COMMIT_SHA \\',
+    '    BUILD_TIME=$BUILD_TIME \\',
+    '    AGENTAGE_IMAGE=$IMAGE',
+    'WORKDIR /app',
+    'COPY --from=deps /app/node_modules ./node_modules',
+    'COPY app/ ./',
+    'USER node',
+    `EXPOSE ${PART_PORT}`,
+    `HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 CMD ["node", "-e", "${HEALTH_PROBE}"]`,
+    `CMD ["node", "node_modules/@agentage/extension/dist/runtime/main.js", "${part}"]`,
+    '',
+].join('\n');

package/dist/tool/stage.d.ts

@@ -0,0 +1,5 @@
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
+export declare const RECORD_FILE = "agentage-extension.json";
+export declare const localTarballs: (pkg: ExtensionPackage) => string[];
+export declare const stageContext: (dir: string, pkg: ExtensionPackage, part: ImagePartKind, tmpRoot?: string) => Promise<string>;

package/dist/tool/stage.js

@@ -0,0 +1,52 @@
+import { access, cp, mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, normalize } from 'node:path';
+import {} from '../manifest/manifest.schema.js';
+import {} from '../manifest/primitives.schema.js';
+import { serverPartRecipe } from './recipe.js';
+export const RECORD_FILE = 'agentage-extension.json';
+const dependencySpecs = (pkg) => {
+    const deps = pkg.dependencies;
+    if (typeof deps !== 'object' || deps === null)
+        return [];
+    return Object.values(deps).filter((spec) => typeof spec === 'string');
+};
+// `file:` tarball dependencies travel into the deps stage at the same relative path.
+export const localTarballs = (pkg) => dependencySpecs(pkg)
+    .filter((spec) => spec.startsWith('file:') && spec.endsWith('.tgz'))
+    .map((spec) => normalize(spec.slice('file:'.length)))
+    .map((path) => {
+    if (isAbsolute(path) || path.startsWith('..')) {
+        throw new Error(`local dependency ${path} must live inside the package folder`);
+    }
+    return path;
+});
+const copyInto = async (from, to) => {
+    await mkdir(dirname(to), { recursive: true });
+    await cp(from, to, { recursive: true });
+};
+const copyDeps = async (dir, root, pkg) => {
+    await access(join(dir, 'package-lock.json')).catch(() => {
+        throw new Error('package-lock.json is missing: the image installs with npm ci');
+    });
+    await copyInto(join(dir, 'package.json'), join(root, 'deps', 'package.json'));
+    await copyInto(join(dir, 'package-lock.json'), join(root, 'deps', 'package-lock.json'));
+    for (const path of localTarballs(pkg))
+        await copyInto(join(dir, path), join(root, 'deps', path));
+};
+const copyApp = async (dir, root) => {
+    await copyInto(join(dir, 'package.json'), join(root, 'app', 'package.json'));
+    await mkdir(join(root, 'app'), { recursive: true });
+    await cp(join(dir, 'dist'), join(root, 'app', 'dist'), {
+        recursive: true,
+        filter: (source) => basename(source) !== RECORD_FILE,
+    });
+};
+// A clean build context per part: only the manifest, the lockfile, local tarballs and dist/.
+export const stageContext = async (dir, pkg, part, tmpRoot = tmpdir()) => {
+    const root = await mkdtemp(join(tmpRoot, `agentage-${pkg.agentage.id}-${part}-`));
+    await copyDeps(dir, root, pkg);
+    await copyApp(dir, root);
+    await writeFile(join(root, 'Dockerfile'), serverPartRecipe(part));
+    return root;
+};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@agentage/extension",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The agentage extension kit: create(ctx) per part, the server, /health, discovery, the envelope, and the build tool",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentage/platform.git",
+    "directory": "packages/extension"
+  },
+  "homepage": "https://agentage.io",
+  "bugs": {
+    "url": "https://github.com/agentage/platform/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tool": {
+      "types": "./dist/tool/index.d.ts",
+      "default": "./dist/tool/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "!dist/**/*.test.*",
+    "!dist/test-support"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "schemas": "node dist/schemas/write-schemas.js schemas",
+    "verify": "npm run verify --prefix ../..",
+    "prepublishOnly": "npm run verify"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "helmet": "^8.1.0",
+    "zod": "^4.2.0"
+  },
+  "peerDependencies": {
+    "express": "^5.1.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "agentage",
+    "extension"
+  ]
+}

package/schemas/error-envelope.schema.json

@@ -0,0 +1,70 @@
+{
+  "$id": "https://agentage.io/schemas/error-envelope.schema.json",
+  "title": "REST error envelope",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "success": {
+      "type": "boolean",
+      "const": false
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "enum": [
+            "VALIDATION_ERROR",
+            "UNAUTHORIZED",
+            "FORBIDDEN",
+            "NOT_FOUND",
+            "CONFLICT",
+            "PRECONDITION_FAILED",
+            "PAYLOAD_TOO_LARGE",
+            "RATE_LIMITED",
+            "INTERNAL",
+            "UNAVAILABLE"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "agcid": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._:-]{8,128}$"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "field": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "field",
+              "message"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "code",
+        "message",
+        "agcid"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "success",
+    "error"
+  ],
+  "additionalProperties": false
+}

package/schemas/extension-discovery.schema.json

@@ -0,0 +1,182 @@
+{
+  "$id": "https://agentage.io/schemas/extension-discovery.schema.json",
+  "title": "GET /.well-known/agentage-extension.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "maxLength": 32,
+      "pattern": "^(?!(?:auth|www|api|sync|mail|mcp|ui|git|setup|status|update|extension|add|remove|help|con|prn|aux|nul|com[0-9]|lpt[0-9])$)[a-z][a-z0-9-]*$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
+    },
+    "commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "buildTime": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
+    },
+    "parts": {
+      "type": "object",
+      "properties": {
+        "pages": {
+          "type": "object",
+          "properties": {
+            "image": {
+              "type": "string",
+              "maxLength": 256,
+              "pattern": "^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\\/[a-z0-9][a-z0-9-]*\\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$"
+            }
+          },
+          "required": [
+            "image"
+          ],
+          "additionalProperties": false
+        },
+        "ui": {
+          "type": "object",
+          "properties": {
+            "image": {
+              "type": "string",
+              "maxLength": 256,
+              "pattern": "^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\\/[a-z0-9][a-z0-9-]*\\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$"
+            }
+          },
+          "required": [
+            "image"
+          ],
+          "additionalProperties": false
+        },
+        "api": {
+          "type": "object",
+          "properties": {
+            "image": {
+              "type": "string",
+              "maxLength": 256,
+              "pattern": "^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\\/[a-z0-9][a-z0-9-]*\\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$"
+            }
+          },
+          "required": [
+            "image"
+          ],
+          "additionalProperties": false
+        },
+        "mcp": {
+          "type": "object",
+          "properties": {
+            "image": {
+              "type": "string",
+              "maxLength": 256,
+              "pattern": "^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\\/[a-z0-9][a-z0-9-]*\\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$"
+            }
+          },
+          "required": [
+            "image"
+          ],
+          "additionalProperties": false
+        },
+        "worker": {
+          "type": "object",
+          "properties": {
+            "image": {
+              "type": "string",
+              "maxLength": 256,
+              "pattern": "^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\\/[a-z0-9][a-z0-9-]*\\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$"
+            }
+          },
+          "required": [
+            "image"
+          ],
+          "additionalProperties": false
+        },
+        "store": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "postgres",
+                "git",
+                "signoz"
+              ]
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "openapi": {
+      "type": "string",
+      "pattern": "^\\/api\\/v[1-9][0-9]*\\/openapi\\.json$"
+    },
+    "tools": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 64,
+        "pattern": "^[a-z][a-z0-9-]*__[a-z][a-z0-9_-]*$"
+      }
+    },
+    "widgets": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "element": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*-[a-z0-9-]+$"
+          },
+          "module": {
+            "type": "string",
+            "pattern": "^\\/ui\\/[^/]+\\/[^/]+\\.m?js$"
+          }
+        },
+        "required": [
+          "name",
+          "element",
+          "module"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "commands": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 32,
+        "pattern": "^[a-z][a-z0-9-]*$"
+      }
+    },
+    "host": {
+      "type": "string",
+      "maxLength": 270,
+      "pattern": "^(https:\\/\\/[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+|http:\\/\\/(127\\.0\\.0\\.1|localhost))(:[0-9]{1,5})?$"
+    }
+  },
+  "required": [
+    "id",
+    "version",
+    "commit",
+    "buildTime",
+    "parts",
+    "host"
+  ],
+  "additionalProperties": false
+}