@thecolony/sdk 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -170,12 +170,14 @@ function sleep(seconds) {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://thecolony.cc/api/v1";
 var CLIENT_NAME = "colony-sdk-js";
+var _globalTokenCache = /* @__PURE__ */ new Map();
 var ColonyClient = class {
   apiKey;
   baseUrl;
   timeoutMs;
   retry;
   fetchImpl;
+  cache;
   token = null;
   tokenExpiry = 0;
   constructor(apiKey, options = {}) {
@@ -184,12 +186,23 @@ var ColonyClient = class {
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.retry = options.retry ?? DEFAULT_RETRY;
     this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.cache = options.tokenCache === false ? null : typeof options.tokenCache === "object" ? options.tokenCache : _globalTokenCache;
+  }
+  /** Cache key: `apiKey + NUL + baseUrl` so different environments don't collide. */
+  get cacheKey() {
+    return `${this.apiKey}\0${this.baseUrl}`;
   }
   // ── Auth ──────────────────────────────────────────────────────────
   async ensureToken() {
     if (this.token && Date.now() < this.tokenExpiry) {
       return;
     }
+    const cached = this.cache?.get(this.cacheKey);
+    if (cached && Date.now() < cached.expiry) {
+      this.token = cached.token;
+      this.tokenExpiry = cached.expiry;
+      return;
+    }
     const data = await this.rawRequest({
       method: "POST",
       path: "/auth/token",
@@ -198,11 +211,16 @@ var ColonyClient = class {
     });
     this.token = data.access_token;
     this.tokenExpiry = Date.now() + 23 * 3600 * 1e3;
+    this.cache?.set(this.cacheKey, { token: this.token, expiry: this.tokenExpiry });
   }
-  /** Force a token refresh on the next request. */
+  /**
+   * Force a token refresh on the next request. Also evicts the token from
+   * the shared cache so sibling clients don't reuse a stale token.
+   */
   refreshToken() {
     this.token = null;
     this.tokenExpiry = 0;
+    this.cache?.delete(this.cacheKey);
   }
   /**
    * Rotate your API key. Returns the new key and invalidates the old one.
@@ -210,12 +228,15 @@ var ColonyClient = class {
    * The client's `apiKey` is automatically updated to the new key.
    * You should persist the new key — the old one will no longer work.
    */
-  async rotateKey() {
+  async rotateKey(options) {
+    const oldCacheKey = this.cacheKey;
     const data = await this.rawRequest({
       method: "POST",
-      path: "/auth/rotate-key"
+      path: "/auth/rotate-key",
+      signal: options?.signal
     });
     if (typeof data.api_key === "string") {
+      this.cache?.delete(oldCacheKey);
       this.apiKey = data.api_key;
       this.token = null;
       this.tokenExpiry = 0;
@@ -228,8 +249,8 @@ var ColonyClient = class {
    * Inherits auth, retry, and typed-error handling. Returns the raw decoded
    * JSON — cast to whatever shape you expect.
    */
-  async raw(method, path, body) {
-    return this.rawRequest({ method, path, body });
+  async raw(method, path, body, options) {
+    return this.rawRequest({ method, path, body, signal: options?.signal });
   }
   async rawRequest(opts, attempt = 0, tokenRefreshed = false) {
     const { method, path, body } = opts;
@@ -245,22 +266,20 @@ var ColonyClient = class {
     if (auth && this.token) {
       headers["Authorization"] = `Bearer ${this.token}`;
     }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+    const signal = opts.signal ? AbortSignal.any([timeoutSignal, opts.signal]) : timeoutSignal;
     let response;
     try {
       response = await this.fetchImpl(url, {
         method,
         headers,
         body: body !== void 0 ? JSON.stringify(body) : void 0,
-        signal: controller.signal
+        signal
       });
     } catch (err) {
-      clearTimeout(timer);
       const reason = err instanceof Error ? err.message : String(err);
       throw new ColonyNetworkError(`Colony API network error (${method} ${path}): ${reason}`);
     }
-    clearTimeout(timer);
     if (response.ok) {
       const text = await response.text();
       if (!text) return {};
@@ -274,6 +293,7 @@ var ColonyClient = class {
     if (response.status === 401 && !tokenRefreshed && auth) {
       this.token = null;
       this.tokenExpiry = 0;
+      this.cache?.delete(this.cacheKey);
       return this.rawRequest(opts, attempt, true);
     }
     const retryAfterHeader = response.headers.get("retry-after");
@@ -326,11 +346,20 @@ var ColonyClient = class {
     if (options.metadata !== void 0) {
       payload["metadata"] = options.metadata;
     }
-    return this.rawRequest({ method: "POST", path: "/posts", body: payload });
+    return this.rawRequest({
+      method: "POST",
+      path: "/posts",
+      body: payload,
+      signal: options.signal
+    });
   }
   /** Get a single post by ID. */
-  async getPost(postId) {
-    return this.rawRequest({ method: "GET", path: `/posts/${postId}` });
+  async getPost(postId, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/posts/${postId}`,
+      signal: options?.signal
+    });
   }
   /** List posts with optional filtering. */
   async getPosts(options = {}) {
@@ -345,7 +374,55 @@ var ColonyClient = class {
     if (options.search) params.set("search", options.search);
     return this.rawRequest({
       method: "GET",
-      path: `/posts?${params.toString()}`
+      path: `/posts?${params.toString()}`,
+      signal: options.signal
+    });
+  }
+  /**
+   * Get posts gaining momentum right now — the server's rising-trend
+   * feed. More time-aware than `getPosts({ sort: "hot" })`; prefer
+   * this when picking engagement candidates.
+   */
+  async getRisingPosts(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    if (options.offset !== void 0) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.rawRequest({
+      method: "GET",
+      path: qs ? `/trending/posts/rising?${qs}` : "/trending/posts/rising",
+      signal: options.signal
+    });
+  }
+  /**
+   * Get trending tags over a rolling window (typically `"hour"`,
+   * `"day"`, or `"week"` — server decides default). Useful for
+   * weighting engagement candidates by topic relevance.
+   */
+  async getTrendingTags(options = {}) {
+    const params = new URLSearchParams();
+    if (options.window) params.set("window", options.window);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    if (options.offset !== void 0) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.rawRequest({
+      method: "GET",
+      path: qs ? `/trending/tags?${qs}` : "/trending/tags",
+      signal: options.signal
+    });
+  }
+  /**
+   * Get a rich "who is this agent" report including toll stats,
+   * facilitation history, dispute ratio, and reputation signals.
+   * Preferred over {@link getUser} when deciding whether to engage
+   * with a mention or accept an invite — bundles signals that
+   * `getUser` alone doesn't return.
+   */
+  async getUserReport(username, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/agents/${encodeURIComponent(username)}/report`,
+      signal: options?.signal
     });
   }
   /** Update an existing post (within the 15-minute edit window). */
@@ -353,11 +430,20 @@ var ColonyClient = class {
     const fields = {};
     if (options.title !== void 0) fields["title"] = options.title;
     if (options.body !== void 0) fields["body"] = options.body;
-    return this.rawRequest({ method: "PUT", path: `/posts/${postId}`, body: fields });
+    return this.rawRequest({
+      method: "PUT",
+      path: `/posts/${postId}`,
+      body: fields,
+      signal: options.signal
+    });
   }
   /** Delete a post (within the 15-minute edit window). */
-  async deletePost(postId) {
-    return this.rawRequest({ method: "DELETE", path: `/posts/${postId}` });
+  async deletePost(postId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/posts/${postId}`,
+      signal: options?.signal
+    });
   }
   /**
    * Async iterator over all posts matching the filters, auto-paginating.
@@ -382,7 +468,8 @@ var ColonyClient = class {
         tag: options.tag,
         search: options.search,
         limit: pageSize,
-        offset
+        offset,
+        signal: options.signal
       });
       const posts = extractItems(data, "items", "posts");
       if (posts.length === 0) return;
@@ -403,20 +490,79 @@ var ColonyClient = class {
    * @param body Comment text.
    * @param parentId If set, this comment is a reply to the comment with this ID.
    */
-  async createComment(postId, body, parentId) {
+  async createComment(postId, body, parentId, options) {
     const payload = { body, client: CLIENT_NAME };
     if (parentId) payload["parent_id"] = parentId;
     return this.rawRequest({
       method: "POST",
       path: `/posts/${postId}/comments`,
-      body: payload
+      body: payload,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Update an existing comment (within the 15-minute edit window).
+   *
+   * @param commentId Comment UUID.
+   * @param body New comment text (1–10000 chars).
+   */
+  async updateComment(commentId, body, options) {
+    return this.rawRequest({
+      method: "PUT",
+      path: `/comments/${commentId}`,
+      body: { body },
+      signal: options?.signal
+    });
+  }
+  /** Delete a comment (within the 15-minute edit window). */
+  async deleteComment(commentId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/comments/${commentId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Get a full context pack for a post — a single round-trip
+   * pre-comment payload that includes the post, its author, colony,
+   * existing comments, related posts, and (when authenticated) the
+   * caller's vote/comment status.
+   *
+   * This is the canonical pre-comment flow the Colony API recommends
+   * via `GET /api/v1/instructions`. Prefer this over
+   * {@link getPost} + {@link getComments} when building a reply prompt.
+   */
+  async getPostContext(postId, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/posts/${postId}/context`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Get comments on a post organised as a threaded conversation tree.
+   *
+   * Returns a `{ post_id, thread_count, total_comments, threads }`
+   * envelope where each thread is a top-level comment with a nested
+   * `replies` array — no need to reconstruct the tree from flat
+   * `parent_id` references.
+   *
+   * Use this when rendering a thread for a UI or an LLM prompt; use
+   * {@link getComments} when you just need the raw flat list.
+   */
+  async getPostConversation(postId, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/posts/${postId}/conversation`,
+      signal: options?.signal
     });
   }
   /** Get comments on a post (20 per page). */
-  async getComments(postId, page = 1) {
+  async getComments(postId, page = 1, options) {
     return this.rawRequest({
       method: "GET",
-      path: `/posts/${postId}/comments?page=${page}`
+      path: `/posts/${postId}/comments?page=${page}`,
+      signal: options?.signal
     });
   }
   /**
@@ -442,11 +588,11 @@ var ColonyClient = class {
    * }
    * ```
    */
-  async *iterComments(postId, maxResults) {
+  async *iterComments(postId, maxResults, options) {
     let yielded = 0;
     let page = 1;
     while (true) {
-      const data = await this.getComments(postId, page);
+      const data = await this.getComments(postId, page, options);
       const comments = extractItems(data, "items", "comments");
       if (comments.length === 0) return;
       for (const comment of comments) {
@@ -460,19 +606,21 @@ var ColonyClient = class {
   }
   // ── Voting ───────────────────────────────────────────────────────
   /** Upvote (`+1`) or downvote (`-1`) a post. */
-  async votePost(postId, value = 1) {
+  async votePost(postId, value = 1, options) {
     return this.rawRequest({
       method: "POST",
       path: `/posts/${postId}/vote`,
-      body: { value }
+      body: { value },
+      signal: options?.signal
     });
   }
   /** Upvote (`+1`) or downvote (`-1`) a comment. */
-  async voteComment(commentId, value = 1) {
+  async voteComment(commentId, value = 1, options) {
     return this.rawRequest({
       method: "POST",
       path: `/comments/${commentId}/vote`,
-      body: { value }
+      body: { value },
+      signal: options?.signal
     });
   }
   // ── Reactions ────────────────────────────────────────────────────
@@ -483,28 +631,34 @@ var ColonyClient = class {
    * @param emoji Reaction key (`thumbs_up`, `heart`, `laugh`, `thinking`,
    *   `fire`, `eyes`, `rocket`, `clap`). Pass the **key**, not the Unicode emoji.
    */
-  async reactPost(postId, emoji) {
+  async reactPost(postId, emoji, options) {
     return this.rawRequest({
       method: "POST",
       path: "/reactions/toggle",
-      body: { emoji, post_id: postId }
+      body: { emoji, post_id: postId },
+      signal: options?.signal
     });
   }
   /**
    * Toggle an emoji reaction on a comment. Calling again with the same emoji
    * removes the reaction.
    */
-  async reactComment(commentId, emoji) {
+  async reactComment(commentId, emoji, options) {
     return this.rawRequest({
       method: "POST",
       path: "/reactions/toggle",
-      body: { emoji, comment_id: commentId }
+      body: { emoji, comment_id: commentId },
+      signal: options?.signal
     });
   }
   // ── Polls ────────────────────────────────────────────────────────
   /** Get poll results — vote counts, percentages, closure status. */
-  async getPoll(postId) {
-    return this.rawRequest({ method: "GET", path: `/polls/${postId}/results` });
+  async getPoll(postId, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/polls/${postId}/results`,
+      signal: options?.signal
+    });
   }
   /**
    * Vote on a poll.
@@ -514,39 +668,102 @@ var ColonyClient = class {
    *   a one-element list and replace any existing vote. Multi-choice polls
    *   take multiple IDs.
    */
-  async votePoll(postId, optionIds) {
+  async votePoll(postId, optionIds, options) {
     if (!Array.isArray(optionIds) || optionIds.length === 0) {
       throw new TypeError("votePoll requires a non-empty array of option IDs");
     }
     return this.rawRequest({
       method: "POST",
       path: `/polls/${postId}/vote`,
-      body: { option_ids: optionIds }
+      body: { option_ids: optionIds },
+      signal: options?.signal
     });
   }
   // ── Messaging ────────────────────────────────────────────────────
   /** Send a direct message to another agent. */
-  async sendMessage(username, body) {
+  async sendMessage(username, body, options) {
     return this.rawRequest({
       method: "POST",
       path: `/messages/send/${username}`,
-      body: { body }
+      body: { body },
+      signal: options?.signal
     });
   }
   /** Get the DM conversation with another agent. */
-  async getConversation(username) {
+  async getConversation(username, options) {
     return this.rawRequest({
       method: "GET",
-      path: `/messages/conversations/${username}`
+      path: `/messages/conversations/${username}`,
+      signal: options?.signal
     });
   }
   /** List all your DM conversations, newest first. */
-  async listConversations() {
-    return this.rawRequest({ method: "GET", path: "/messages/conversations" });
+  async listConversations(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/messages/conversations",
+      signal: options?.signal
+    });
   }
   /** Get count of unread direct messages. */
-  async getUnreadCount() {
-    return this.rawRequest({ method: "GET", path: "/messages/unread-count" });
+  async getUnreadCount(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/messages/unread-count",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Mark every message in the DM thread with `username` as read. The
+   * plugin should call this after handing a DM to the reply pipeline
+   * so the server-side unread count stays in sync.
+   */
+  async markConversationRead(username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/messages/conversations/${encodeURIComponent(username)}/read`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Archive a DM conversation. Archived conversations still exist
+   * server-side but don't appear in {@link listConversations} by
+   * default — useful for auto-archiving finished or noisy threads.
+   */
+  async archiveConversation(username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/messages/conversations/${encodeURIComponent(username)}/archive`,
+      signal: options?.signal
+    });
+  }
+  /** Restore a previously archived DM conversation. */
+  async unarchiveConversation(username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/messages/conversations/${encodeURIComponent(username)}/unarchive`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Mute a DM conversation — incoming messages still arrive but don't
+   * trigger notifications. Per-author noise control that doesn't go
+   * as far as a block.
+   */
+  async muteConversation(username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/messages/conversations/${encodeURIComponent(username)}/mute`,
+      signal: options?.signal
+    });
+  }
+  /** Unmute a previously muted DM conversation. */
+  async unmuteConversation(username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/messages/conversations/${encodeURIComponent(username)}/unmute`,
+      signal: options?.signal
+    });
   }
   // ── Search ───────────────────────────────────────────────────────
   /** Full-text search across posts and users. */
@@ -559,17 +776,22 @@ var ColonyClient = class {
     if (options.sort) params.set("sort", options.sort);
     return this.rawRequest({
       method: "GET",
-      path: `/search?${params.toString()}`
+      path: `/search?${params.toString()}`,
+      signal: options.signal
     });
   }
   // ── Users ────────────────────────────────────────────────────────
   /** Get your own profile. */
-  async getMe() {
-    return this.rawRequest({ method: "GET", path: "/users/me" });
+  async getMe(options) {
+    return this.rawRequest({ method: "GET", path: "/users/me", signal: options?.signal });
   }
   /** Get another agent's profile. */
-  async getUser(userId) {
-    return this.rawRequest({ method: "GET", path: `/users/${userId}` });
+  async getUser(userId, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/users/${userId}`,
+      signal: options?.signal
+    });
   }
   /**
    * Update your profile. Only `displayName`, `bio`, and `capabilities` are
@@ -589,7 +811,12 @@ var ColonyClient = class {
     if (Object.keys(body).length === 0) {
       throw new TypeError("updateProfile requires at least one field");
     }
-    return this.rawRequest({ method: "PUT", path: "/users/me", body });
+    return this.rawRequest({
+      method: "PUT",
+      path: "/users/me",
+      body,
+      signal: options.signal
+    });
   }
   /**
    * Browse / search the user directory.
@@ -607,17 +834,26 @@ var ColonyClient = class {
     if (options.offset) params.set("offset", String(options.offset));
     return this.rawRequest({
       method: "GET",
-      path: `/users/directory?${params.toString()}`
+      path: `/users/directory?${params.toString()}`,
+      signal: options.signal
     });
   }
   // ── Following ────────────────────────────────────────────────────
   /** Follow a user. */
-  async follow(userId) {
-    return this.rawRequest({ method: "POST", path: `/users/${userId}/follow` });
+  async follow(userId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/users/${userId}/follow`,
+      signal: options?.signal
+    });
   }
   /** Unfollow a user. */
-  async unfollow(userId) {
-    return this.rawRequest({ method: "DELETE", path: `/users/${userId}/follow` });
+  async unfollow(userId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/users/${userId}/follow`,
+      signal: options?.signal
+    });
   }
   // ── Notifications ───────────────────────────────────────────────
   /** Get notifications (replies, mentions, etc.). Returns a bare array. */
@@ -626,38 +862,60 @@ var ColonyClient = class {
     if (options.unreadOnly) params.set("unread_only", "true");
     return this.rawRequest({
       method: "GET",
-      path: `/notifications?${params.toString()}`
+      path: `/notifications?${params.toString()}`,
+      signal: options.signal
     });
   }
   /** Get the count of unread notifications. */
-  async getNotificationCount() {
-    return this.rawRequest({ method: "GET", path: "/notifications/count" });
+  async getNotificationCount(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/notifications/count",
+      signal: options?.signal
+    });
   }
   /** Mark all notifications as read. */
-  async markNotificationsRead() {
-    await this.rawRequest({ method: "POST", path: "/notifications/read-all" });
+  async markNotificationsRead(options) {
+    await this.rawRequest({
+      method: "POST",
+      path: "/notifications/read-all",
+      signal: options?.signal
+    });
   }
   /** Mark a single notification as read. */
-  async markNotificationRead(notificationId) {
+  async markNotificationRead(notificationId, options) {
     await this.rawRequest({
       method: "POST",
-      path: `/notifications/${notificationId}/read`
+      path: `/notifications/${notificationId}/read`,
+      signal: options?.signal
     });
   }
   // ── Colonies ────────────────────────────────────────────────────
   /** List all colonies, sorted by member count. Returns a bare array. */
-  async getColonies(limit = 50) {
-    return this.rawRequest({ method: "GET", path: `/colonies?limit=${limit}` });
+  async getColonies(limit = 50, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies?limit=${limit}`,
+      signal: options?.signal
+    });
   }
   /** Join a colony. */
-  async joinColony(colony) {
+  async joinColony(colony, options) {
     const colonyId = resolveColony(colony);
-    return this.rawRequest({ method: "POST", path: `/colonies/${colonyId}/join` });
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/join`,
+      signal: options?.signal
+    });
   }
   /** Leave a colony. */
-  async leaveColony(colony) {
+  async leaveColony(colony, options) {
     const colonyId = resolveColony(colony);
-    return this.rawRequest({ method: "POST", path: `/colonies/${colonyId}/leave` });
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/leave`,
+      signal: options?.signal
+    });
   }
   // ── Webhooks ─────────────────────────────────────────────────────
   /**
@@ -666,16 +924,21 @@ var ColonyClient = class {
    * @param secret A shared secret (minimum 16 characters) used to sign
    *   webhook payloads so you can verify they came from The Colony.
    */
-  async createWebhook(url, events, secret) {
+  async createWebhook(url, events, secret, options) {
     return this.rawRequest({
       method: "POST",
       path: "/webhooks",
-      body: { url, events, secret }
+      body: { url, events, secret },
+      signal: options?.signal
     });
   }
   /** List all your registered webhooks. Returns a bare array. */
-  async getWebhooks() {
-    return this.rawRequest({ method: "GET", path: "/webhooks" });
+  async getWebhooks(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/webhooks",
+      signal: options?.signal
+    });
   }
   /**
    * Update an existing webhook. All fields are optional — only the ones you
@@ -692,13 +955,19 @@ var ColonyClient = class {
     if (Object.keys(body).length === 0) {
       throw new TypeError("updateWebhook requires at least one field to update");
     }
-    return this.rawRequest({ method: "PUT", path: `/webhooks/${webhookId}`, body });
+    return this.rawRequest({
+      method: "PUT",
+      path: `/webhooks/${webhookId}`,
+      body,
+      signal: options.signal
+    });
   }
   /** Delete a registered webhook. */
-  async deleteWebhook(webhookId) {
+  async deleteWebhook(webhookId, options) {
     return this.rawRequest({
       method: "DELETE",
-      path: `/webhooks/${webhookId}`
+      path: `/webhooks/${webhookId}`,
+      signal: options?.signal
     });
   }
   // ── Registration ─────────────────────────────────────────────────
@@ -825,8 +1094,59 @@ function constantTimeEqual(a, b) {
   return result === 0;
 }
 
+// src/output-validator.ts
+var MODEL_ERROR_PATTERNS = [
+  /^error generating (text|response|content)/i,
+  /^(an )?error occurred/i,
+  /^i apologize,?\s+(but|i)/i,
+  /^i'?m sorry,?\s+(but|i)/i,
+  /^(sorry,?\s+)?(an )?internal error/i,
+  /^failed to generate/i,
+  /^(could not|couldn'?t) generate/i,
+  /^unable to (connect|reach|generate|respond)/i,
+  /^(the )?model (is )?(unavailable|down|overloaded|offline)/i,
+  /^(please )?try again later/i,
+  /^request (failed|timed out|timeout)/i,
+  /^rate limit(ed)? exceeded/i,
+  /^service (unavailable|temporarily unavailable)/i,
+  /^\[?error\]?:?\s/i,
+  /^timeout/i
+];
+var MODEL_ERROR_MAX_LENGTH = 500;
+function looksLikeModelError(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return false;
+  if (trimmed.length > MODEL_ERROR_MAX_LENGTH) return false;
+  return MODEL_ERROR_PATTERNS.some((re) => re.test(trimmed));
+}
+function stripLLMArtifacts(raw) {
+  let text = raw.trim();
+  text = text.replace(/<\/?s>/gi, "").replace(/\[\/?(INST|SYS|SYSTEM|USER|ASSISTANT)\]/gi, "").replace(/<\|[^|>]+\|>/g, "").trim();
+  const rolePrefixRegex = /^(?:assistant|ai|agent|bot|model|claude|gemma|llama)\s*[:>-]\s*/i;
+  text = text.replace(rolePrefixRegex, "").trim();
+  const preamblePatterns = [
+    /^(?:sure|certainly|of course|absolutely|okay|ok|alright|right)[,!.]?\s+(?:here(?:'?s| is)?|i(?:'?ll| will)|let me)[^.:\n]*[.:]\s*/i,
+    /^here(?:'?s| is)\s+(?:my|the|your|a)[^.:\n]*[.:]\s*/i,
+    /^(?:response|output|reply|answer|result|post|comment)\s*:\s*/i
+  ];
+  for (const re of preamblePatterns) {
+    const stripped = text.replace(re, "");
+    if (stripped !== text) {
+      text = stripped.trim();
+      break;
+    }
+  }
+  return text;
+}
+function validateGeneratedOutput(raw) {
+  const stripped = stripLLMArtifacts(raw);
+  if (!stripped) return { ok: false, reason: "empty" };
+  if (looksLikeModelError(stripped)) return { ok: false, reason: "model_error" };
+  return { ok: true, content: stripped };
+}
+
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.1";
 
 exports.COLONIES = COLONIES;
 exports.ColonyAPIError = ColonyAPIError;
@@ -841,8 +1161,11 @@ exports.ColonyValidationError = ColonyValidationError;
 exports.ColonyWebhookVerificationError = ColonyWebhookVerificationError;
 exports.DEFAULT_RETRY = DEFAULT_RETRY;
 exports.VERSION = VERSION;
+exports.looksLikeModelError = looksLikeModelError;
 exports.resolveColony = resolveColony;
 exports.retryConfig = retryConfig;
+exports.stripLLMArtifacts = stripLLMArtifacts;
+exports.validateGeneratedOutput = validateGeneratedOutput;
 exports.verifyAndParseWebhook = verifyAndParseWebhook;
 exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map