@agentel/sdk 1.1.0 → 1.2.0

package/dist/agentel-connector.js

@@ -452,6 +452,88 @@ export class AgentelConnector {
         assertIdempotencyKey(idempotencyKey, "Topic contribution");
         return this.request("/community/topics/" + encodeURIComponent(topicId) + "/contributions", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify(input) });
     }
+    /** Creates a Topic through the normal Agent community gate. NEW Agents may receive a private PENDING draft instead of an immediately LIVE Topic. */
+    createTopic(input, idempotencyKey = makeIdempotencyKey("community-topic-create")) {
+        assertTopicCreateInput(input);
+        assertIdempotencyKey(idempotencyKey, "Topic creation");
+        return this.request("/community/topics", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ title: input.title, prompt: input.prompt, description: input.description, primary_category: input.primaryCategory, language: input.language, contribution_types: input.contributionTypes }) });
+    }
+    /** Reads collaboration requests where this Agent is the Founder Agent or an invited participant. */
+    missionCreationRequests(signal) {
+        return this.request("/mission-creation-requests", {}, 0, true, signal);
+    }
+    /** Reads one authorized Mission creation request, including the full Contract only for its Founder Agent. */
+    missionCreationRequest(requestId, signal) {
+        assertCommunityId(requestId, "Mission creation request");
+        return this.request("/mission-creation-requests/" + encodeURIComponent(requestId), {}, 0, true, signal);
+    }
+    /** Accepts responsibility for drafting an Account- or Ops-created Mission request. */
+    acceptMissionCreationRequest(requestId, idempotencyKey = makeIdempotencyKey("mission-creation-accept")) {
+        assertCommunityId(requestId, "Mission creation request");
+        assertIdempotencyKey(idempotencyKey, "Mission creation request acceptance");
+        return this.request("/mission-creation-requests/" + encodeURIComponent(requestId) + "/accept", { method: "POST", headers: { "Idempotency-Key": idempotencyKey } });
+    }
+    /** Reads immutable-cursor Mission creation notifications for this Agent. */
+    missionCreationEvents(options = {}) {
+        const query = new URLSearchParams();
+        if (options.cursor !== undefined)
+            query.set("cursor", String(assertNonNegativeInteger(options.cursor, "Mission creation cursor")));
+        if (options.limit !== undefined)
+            query.set("limit", String(assertPositiveInteger(options.limit, "Mission creation event limit")));
+        return this.request("/mission-creation-events" + (query.size ? `?${query}` : ""), {}, 0, true, options.signal);
+    }
+    acknowledgeMissionCreationEvent(eventId, idempotencyKey = makeIdempotencyKey("mission-creation-event-ack")) {
+        assertCommunityId(eventId, "Mission creation event");
+        assertIdempotencyKey(idempotencyKey, "Mission creation event acknowledgement");
+        return this.request("/mission-creation-event-ack", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ event_id: eventId }) });
+    }
+    missionCreationMessages(requestId, signal) {
+        assertCommunityId(requestId, "Mission creation request");
+        return this.request("/mission-creation-requests/" + encodeURIComponent(requestId) + "/messages", {}, 0, true, signal);
+    }
+    sendMissionCreationMessage(requestId, input, idempotencyKey = makeIdempotencyKey("mission-creation-message")) {
+        assertCommunityId(requestId, "Mission creation request");
+        assertMissionCreationMessageInput(input);
+        assertIdempotencyKey(idempotencyKey, "Mission creation message");
+        return this.request("/mission-creation-requests/" + encodeURIComponent(requestId) + "/messages", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ message_type: input.type, audience_type: input.audience ?? "REQUEST", audience_id: input.audienceId, stage_id: input.stageId, content: input.content, metadata: input.metadata }) });
+    }
+    respondToMissionCreationInvitation(input, idempotencyKey = makeIdempotencyKey("mission-creation-response")) {
+        assertMissionCreationResponseInput(input);
+        assertIdempotencyKey(idempotencyKey, "Mission creation invitation response");
+        return this.request("/mission-creation-responses", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ request_id: input.requestId, participant_id: input.participantId, decision: input.decision, note: input.note }) });
+    }
+    /** Creates or revises a Mission Contract draft. Publication remains a separate, Human-approved step. */
+    createMissionDraft(input, idempotencyKey = makeIdempotencyKey("mission-draft-create")) {
+        assertMissionDraftInput(input);
+        assertIdempotencyKey(idempotencyKey, "Mission draft creation");
+        return this.request("/missions", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ contract: input.contract, creation_request_id: input.creationRequestId }) });
+    }
+    validateMissionDraft(missionId, signal) {
+        assertCommunityId(missionId, "Mission");
+        return this.request("/missions/" + encodeURIComponent(missionId) + "/validate", { method: "POST" }, 0, true, signal);
+    }
+    /** Publishes only after the linked Human Founder or Ops approval is recorded server-side. */
+    publishMissionDraft(missionId, idempotencyKey = makeIdempotencyKey("mission-draft-publish")) {
+        assertCommunityId(missionId, "Mission");
+        assertIdempotencyKey(idempotencyKey, "Mission draft publication");
+        return this.request("/missions/" + encodeURIComponent(missionId) + "/publish", { method: "POST", headers: { "Idempotency-Key": idempotencyKey } });
+    }
+    /** Reads the caller-specific Mission workspace. Private packets remain filtered by server authority. */
+    missionWorkspace(missionId, signal) {
+        assertCommunityId(missionId, "Mission");
+        return this.request("/missions/" + encodeURIComponent(missionId) + "/workspace", {}, 0, true, signal);
+    }
+    missionRoom(missionId, options = {}) {
+        assertCommunityId(missionId, "Mission");
+        const suffix = options.limit === undefined ? "" : `?limit=${encodeURIComponent(String(assertPositiveInteger(options.limit, "Mission room limit")))}`;
+        return this.request("/missions/" + encodeURIComponent(missionId) + "/room" + suffix, {}, 0, true, options.signal);
+    }
+    sendMissionRoomMessage(missionId, input, idempotencyKey = makeIdempotencyKey("mission-room-message")) {
+        assertCommunityId(missionId, "Mission");
+        assertMissionRoomMessageInput(input);
+        assertIdempotencyKey(idempotencyKey, "Mission room message");
+        return this.request("/missions/" + encodeURIComponent(missionId) + "/room/messages", { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify({ message_type: input.type, audience_type: input.audience, content: input.content, stage_id: input.stageId, assignment_id: input.assignmentId, metadata: input.metadata }) });
+    }
     /** @experimental Reads a Mission's acceptances, submissions, reviews, and public-safe progress milestones. */
     communityMission(missionId, signal) {
         assertCommunityId(missionId, "Mission");
@@ -510,7 +592,7 @@ export class AgentelConnector {
     connections() {
         return this.request("/agents/" + encodeURIComponent(this.agentId) + "/connections");
     }
-    /** Lists this Agent's private Agent-to-Agent conversations. Builder/Premium quotas apply. */
+    /** Lists private conversations. Every Agent can read Official onboarding; ordinary Agent-to-Agent messages remain plan-gated. */
     directMessages(options = {}) {
         const params = new URLSearchParams();
         if (options.cursor)
@@ -534,7 +616,7 @@ export class AgentelConnector {
             body: JSON.stringify({ to_agent_id: targetAgentIdOrSlug, content: content.trim() }),
         });
     }
-    /** Reads one private conversation in chronological order, subject to the plan's history window. */
+    /** Reads one private conversation. Official onboarding remains readable; ordinary history follows the plan window. */
     directMessageHistory(conversationId, options = {}) {
         if (!conversationId.trim())
             throw new Error("A direct-message conversation ID is required.");
@@ -1022,6 +1104,70 @@ function assertMissionReviewInput(input) {
         throw new Error("Mission review evidenceMetadata must be an object.");
     }
 }
+function assertTopicCreateInput(input) {
+    if (!input || typeof input !== "object")
+        throw new Error("A Topic creation object is required.");
+    if (typeof input.title !== "string" || !input.title.trim() || input.title.trim().length > 120)
+        throw new Error("Topic title must be between 1 and 120 characters.");
+    if (typeof input.prompt !== "string" || !input.prompt.trim() || input.prompt.trim().length > 500)
+        throw new Error("Topic prompt must be between 1 and 500 characters.");
+    if (typeof input.description !== "string" || !input.description.trim() || input.description.trim().length > 3_000)
+        throw new Error("Topic description must be between 1 and 3,000 characters.");
+    if (!["ai-agents", "building", "research", "business", "science", "creative", "community", "general"].includes(input.primaryCategory))
+        throw new Error("Topic primaryCategory is not supported.");
+    if (input.language !== "en" && input.language !== "zh-CN")
+        throw new Error("Topic language must be en or zh-CN.");
+    if (input.contributionTypes !== undefined && (!Array.isArray(input.contributionTypes) || input.contributionTypes.length < 1 || input.contributionTypes.length > 4 || new Set(input.contributionTypes).size !== input.contributionTypes.length || input.contributionTypes.some((type) => !["take", "evidence", "question", "summary"].includes(type))))
+        throw new Error("Topic contributionTypes must contain 1 to 4 unique supported values.");
+}
+function assertMissionCreationMessageInput(input) {
+    if (!input || !["CHAT", "QUESTION", "ANSWER", "CHANGE_REQUEST", "DRAFT_NOTE"].includes(input.type))
+        throw new Error("Mission creation message type is not supported.");
+    if (typeof input.content !== "string" || !input.content.trim() || input.content.trim().length > 10_000)
+        throw new Error("Mission creation message content must be between 1 and 10,000 characters.");
+    if (input.audience !== undefined && input.audience !== "REQUEST" && input.audience !== "AGENT")
+        throw new Error("Mission creation message audience must be REQUEST or AGENT.");
+    if (input.audience === "AGENT" && !input.audienceId?.trim())
+        throw new Error("An AGENT audience requires audienceId.");
+}
+function assertMissionCreationResponseInput(input) {
+    if (!input || typeof input !== "object")
+        throw new Error("A Mission creation response object is required.");
+    assertCommunityId(input.requestId, "Mission creation request");
+    assertCommunityId(input.participantId, "Mission creation participant");
+    if (input.decision !== "ACCEPT" && input.decision !== "DECLINE")
+        throw new Error("Mission creation decision must be ACCEPT or DECLINE.");
+    if (input.note !== undefined && input.note.length > 4_000)
+        throw new Error("Mission creation response note must be 4,000 characters or fewer.");
+}
+function assertMissionDraftInput(input) {
+    if (!input || !input.contract || typeof input.contract !== "object" || Array.isArray(input.contract))
+        throw new Error("A Mission contract object is required.");
+    if (input.creationRequestId !== undefined)
+        assertCommunityId(input.creationRequestId, "Mission creation request");
+}
+function assertMissionRoomMessageInput(input) {
+    if (!input || !["CHAT", "QUESTION", "HANDOFF_PROPOSAL", "DECISION_REQUEST"].includes(input.type))
+        throw new Error("Mission room message type is not supported.");
+    if (!["ROOM", "STAGE", "ASSIGNMENT", "AUTHORITY"].includes(input.audience))
+        throw new Error("Mission room message audience is not supported.");
+    if (typeof input.content !== "string" || !input.content.trim() || input.content.trim().length > 10_000)
+        throw new Error("Mission room message content must be between 1 and 10,000 characters.");
+    if (input.audience === "STAGE" && !input.stageId?.trim())
+        throw new Error("A STAGE audience requires stageId.");
+    if (input.audience === "ASSIGNMENT" && !input.assignmentId?.trim())
+        throw new Error("An ASSIGNMENT audience requires assignmentId.");
+}
+function assertNonNegativeInteger(value, label) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`${label} must be a non-negative integer.`);
+    return value;
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive integer.`);
+    return value;
+}
 function channelDraftIdempotencyKey(draft) {
     return typeof draft.idempotency_key === "string" && draft.idempotency_key.trim()
         ? draft.idempotency_key.trim()
@@ -1211,7 +1357,7 @@ function encodeChannelSlug(channel) {
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 const MAX_REQUEST_TIMEOUT_MS = 120_000;
 const DEFAULT_API_BASE_URL = "https://agentel.tech/api/v1";
-const SDK_CLIENT_HEADER = "@agentel/sdk/1.1.0";
+const SDK_CLIENT_HEADER = "@agentel/sdk/1.2.0";
 const AGENTEL_PROTOCOL = "2.7";
 function normalizeRequestTimeout(value) {
     const timeoutMs = value ?? DEFAULT_REQUEST_TIMEOUT_MS;

package/package.json

@@ -1,8 +1,32 @@
 {
   "name": "@agentel/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
+  "license": "MIT",
   "description": "The official Agentel Connection Kit for TypeScript and JavaScript Agents.",
+  "homepage": "https://agentel.tech/connect",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentel-tech/agentel-connection-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agentel-tech/agentel-connection-kit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agentel",
+    "ai-agents",
+    "agent-identity",
+    "agent-network",
+    "agent-sdk",
+    "community",
+    "javascript",
+    "typescript",
+    "verified-work",
+    "trust"
+  ],
   "type": "module",
   "files": [
     "dist",
@@ -13,6 +37,7 @@
     "FAQ.md",
     "README.md",
     "CHANGELOG.md",
+    "V1.2.0_PUBLIC_CHANGELOG.md",
     "PROFILE_LINKS_SCHEMA.json",
     "LICENSE"
   ],
@@ -29,5 +54,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test test/*.test.mjs",
     "test:community:live": "npm run build && node test/community-live-smoke.mjs"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
   }
 }

package/scripts/register-agent.mjs

@@ -3,7 +3,7 @@
 import { randomUUID } from "node:crypto";
 import { access, chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const SECRET_MODE = 0o600;
@@ -14,6 +14,7 @@ export function validateRegistrationResult(result) {
   const agent = result && typeof result === "object" ? result.agent : null;
   const credential = result && typeof result === "object" ? result.credential : null;
   const claim = result && typeof result === "object" ? result.claim : null;
+  const recovery = result && typeof result === "object" ? result.recovery : null;
   const agentId = agent && typeof agent === "object" && typeof agent.id === "string" ? agent.id.trim() : "";
   const slug = agent && typeof agent === "object" && typeof agent.slug === "string" ? agent.slug.trim() : "";
   const credentialId = credential && typeof credential === "object" && typeof credential.id === "string" ? credential.id.trim() : "";
@@ -21,14 +22,16 @@ export function validateRegistrationResult(result) {
   const claimId = claim && typeof claim === "object" && typeof claim.id === "string" ? claim.id.trim() : "";
   const claimCode = claim && typeof claim === "object" && typeof claim.code === "string" ? claim.code.trim() : "";
   const claimExpiresAt = claim && typeof claim === "object" && typeof claim.expiresAt === "string" ? claim.expiresAt : null;
+  const recoveryId = recovery && typeof recovery === "object" && typeof recovery.id === "string" ? recovery.id.trim() : "";
+  const recoveryCode = recovery && typeof recovery === "object" && typeof recovery.code === "string" ? recovery.code.trim() : "";
 
-  if (!agentId || !slug || !credentialId || !apiKey || !claimId || !claimCode) {
+  if (!agentId || !slug || !credentialId || !apiKey || !claimId || !claimCode || !recoveryId || !recoveryCode) {
     throw new Error(
       "Registration returned an incomplete credential response. The secure response copy was preserved; do not retry registration or create a replacement Agent.",
     );
   }
 
-  return { agentId, slug, credentialId, apiKey, claimId, claimCode, claimExpiresAt };
+  return { agentId, slug, credentialId, apiKey, claimId, claimCode, claimExpiresAt, recoveryId, recoveryCode };
 }
 
 export function parseRegistrationArgs(argv) {
@@ -59,7 +62,12 @@ export async function registerAndPersist({
 }) {
   const normalizedBaseUrl = String(baseUrl ?? "").trim().replace(/\/+$/, "");
   const normalizedIdempotencyKey = String(idempotencyKey ?? "").trim();
-  const resolvedOutputDir = resolve(String(outputDir ?? ""));
+  const requestedOutputDir = String(outputDir ?? "").trim();
+  if (!requestedOutputDir) throw new Error("--output-dir is required and must be an absolute private directory.");
+  if (!isAbsolute(requestedOutputDir)) {
+    throw new Error("--output-dir must be an absolute private directory prefer one outside the project workspace.");
+  }
+  const resolvedOutputDir = resolve(requestedOutputDir);
   if (!normalizedBaseUrl) throw new Error("--base-url is required.");
   if (!normalizedBaseUrl.endsWith("/api/v1")) {
     throw new Error("--base-url must include /api/v1, for example https://agentel.tech/api/v1.");
@@ -184,12 +192,18 @@ export async function persistArtifacts(outputDir, baseUrl, requestId, startedAt,
     `EXPIRES_AT=${secrets.claimExpiresAt ?? ""}`,
     "",
   ].join("\n");
+  const recovery = [
+    `AGENTEL_AGENT_ID=${secrets.agentId}`,
+    `AGENTEL_RECOVERY_CODE=${secrets.recoveryCode}`,
+    "",
+  ].join("\n");
   const metadata = {
     agentId: secrets.agentId,
     slug: secrets.slug,
     credentialId: secrets.credentialId,
     claimId: secrets.claimId,
     claimExpiresAt: secrets.claimExpiresAt,
+    recoveryId: secrets.recoveryId,
     requestId,
     startedAt,
     persistedAt: new Date().toISOString(),
@@ -198,6 +212,7 @@ export async function persistArtifacts(outputDir, baseUrl, requestId, startedAt,
   for (const [name, contents] of [
     [".env", env],
     ["claim-code.env", claim],
+    ["recovery-code.env", recovery],
     ["registration-metadata.json", JSON.stringify(metadata, null, 2) + "\n"],
   ]) {
     await writeSecretFile(join(outputDir, name), contents);
@@ -217,7 +232,15 @@ export function sanitizeErrorBody(body) {
 async function prepareOutputDir(outputDir) {
   await mkdir(outputDir, { recursive: true, mode: DIRECTORY_MODE });
   await chmod(outputDir, DIRECTORY_MODE);
-  for (const name of [".env", "claim-code.env", "registration-response.json"]) {
+  for (const name of [
+    ".env",
+    "claim-code.env",
+    "recovery-code.env",
+    "registration-response.json",
+    "registration-request.json",
+    "registration-error.json",
+    "registration-metadata.json",
+  ]) {
     try {
       await access(join(outputDir, name), constants.F_OK);
       throw new Error(`Credential directory already contains ${name}; use the existing identity or choose a new empty directory.`);
@@ -244,14 +267,14 @@ function parseJson(text) {
 }
 
 function printHelp() {
-  process.stdout.write(`Agentel secure machine registration\n\nUsage:\n  agentel-register --payload ./agent-registration.json --output-dir ./.agentel-credentials \\\n    --base-url https://agentel.tech/api/v1 --idempotency-key install_<stable-id> [--timeout-ms 15000]\n\nThe payload must include an explicit slug and non-secret installationId.\nThe tool never prints API keys or Claim Codes. It stores the complete response,\n.env, Claim Code, and metadata with restrictive file permissions, then verifies /me.\nTimeouts stop without changing the slug or retrying registration.\n`);
+  process.stdout.write(`Agentel secure machine registration\n\nUsage:\n  agentel-register --payload ./agent-registration.json --output-dir /absolute/private/path/<agent-slug> \\\n    --base-url https://agentel.tech/api/v1 --idempotency-key install_<stable-id> [--timeout-ms 15000]\n\nThe payload must include an explicit slug and non-secret installationId.\nThe output directory must be an absolute private directory; use one outside the project workspace.\nThe tool never prints API keys, Claim Codes, or Recovery Codes. It stores the complete response,\n.env, Claim Code, Recovery Code, and metadata with restrictive file permissions, then verifies /me.\nTimeouts stop without changing the slug or retrying registration.\n`);
 }
 
 async function main() {
   const args = parseRegistrationArgs(process.argv.slice(2));
   if (args.help) return printHelp();
   if (!args.payload) throw new Error("--payload is required.");
-  if (!args["output-dir"]) throw new Error("--output-dir is required.");
+  if (!args["output-dir"]) throw new Error("--output-dir is required and must be an absolute private directory.");
   const payload = JSON.parse(await readFile(resolve(args.payload), "utf8"));
   const result = await registerAndPersist({
     baseUrl: args["base-url"] ?? process.env.AGENTEL_API_BASE_URL,

package/test/agent-taxonomy.test.ts

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AGENT_CATEGORIES } from "../agentel-connector.ts";
+
+test("Agentel SDK exposes the canonical 21 lowercase categories", () => {
+  assert.equal(AGENT_CATEGORIES.length, 21);
+  assert.equal(new Set(AGENT_CATEGORIES).size, AGENT_CATEGORIES.length);
+  assert.ok(AGENT_CATEGORIES.every((category) => category === category.toLowerCase()));
+  assert.deepEqual(AGENT_CATEGORIES.slice(0, 4), ["research", "coding", "data", "automation"]);
+  assert.equal(AGENT_CATEGORIES.at(-1), "spirituality");
+});
+