@assemblyline-agents/x 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Assembly Line contributors
+
+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/README.md

@@ -0,0 +1,68 @@
+# @assemblyline-agents/x
+
+Official Assembly Line direct X API connection plugin. It calls X API v2 from
+the runtime host and does not use MCP.
+
+## Install and configure
+
+```sh
+assembly-line add x agent
+```
+
+This creates `connections/x.ts`:
+
+```ts
+import { defineXConnection } from "@assemblyline-agents/x";
+
+export default defineXConnection({
+  // Reviewed reads and publishing are enabled by default.
+});
+```
+
+Create a confidential OAuth 2.0 App in the
+[X Developer Console](https://developer.x.com/en/portal/dashboard). Enable User
+authentication with Authorization Code + PKCE, then set:
+
+```sh
+X_API_CLIENT_ID=your_client_id
+X_API_CLIENT_SECRET=your_client_secret
+```
+
+Register the exact Assembly Line callback URL in the X App. It is the public
+runtime origin followed by `/assembly-line/connections/callback`. Set
+`X_API_REDIRECT_URI` only when the connection should override the runtime's
+derived callback URL.
+
+The full reviewed surface requests `bookmark.read`, `tweet.read`, `tweet.write`,
+`users.read`, and `offline.access`. The host uses PKCE, authenticates the
+confidential client at X's token endpoint, and stores refreshable user grants
+outside agent files and model context.
+
+## Reviewed surface
+
+Read tools return the connected account and its private bookmarks. Bookmark
+pages include author, referenced-post, note-post, article, and media context.
+The only write tool creates a text post or reply, with an optional provider
+reply setting. Arbitrary X mutations, bookmark changes, post deletion, and
+media upload remain unavailable until they receive an explicit tool contract
+and access classification.
+
+Use the read-only preset to hide publishing and omit `tweet.write` from OAuth:
+
+```ts
+export default defineXConnection({ access: "read-only" });
+```
+
+Use `access: "approval-required"` to require approval for each post or reply.
+X API reads may be metered, so callers should avoid unnecessary repeated
+bookmark scans.
+
+Official references:
+
+- [OAuth 2.0 Authorization Code with PKCE](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code)
+- [Get bookmarks](https://docs.x.com/x-api/users/get-bookmarks)
+- [Create a post](https://docs.x.com/x-api/posts/create-post)
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,3 @@
+import { type ConnectionAuthDefinition, type ConnectionPluginAccessSelection } from "@assemblyline-agents/core";
+export declare function xOAuth(access: ConnectionPluginAccessSelection | undefined): ConnectionAuthDefinition;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACrC,MAAM,2BAA2B,CAAC;AAKnC,wBAAgB,MAAM,CAAC,MAAM,EAAE,+BAA+B,GAAG,SAAS,GAAG,wBAAwB,CAoBpG"}

package/dist/auth.js

@@ -0,0 +1,30 @@
+import { defineOAuthAuthorization } from "@assemblyline-agents/core";
+const READ_SCOPES = ["bookmark.read", "tweet.read", "users.read", "offline.access"];
+const WRITE_SCOPES = ["bookmark.read", "tweet.read", "tweet.write", "users.read", "offline.access"];
+export function xOAuth(access) {
+    return ({ env }) => {
+        const clientId = env.X_API_CLIENT_ID?.trim();
+        const clientSecret = env.X_API_CLIENT_SECRET?.trim();
+        const redirectUri = env.X_API_REDIRECT_URI?.trim();
+        if (!clientId || !clientSecret) {
+            throw new Error("X OAuth requires X_API_CLIENT_ID and X_API_CLIENT_SECRET.");
+        }
+        return defineOAuthAuthorization({
+            displayName: "X",
+            authorizeUrl: "https://x.com/i/oauth2/authorize",
+            tokenUrl: "https://api.x.com/2/oauth2/token",
+            clientId,
+            clientSecret,
+            scopes: writesEnabled(access) ? [...WRITE_SCOPES] : [...READ_SCOPES],
+            ...(redirectUri ? { redirectUri } : {}),
+            tokenEndpointAuthMethod: "client_secret_basic",
+            pkce: true
+        });
+    };
+}
+function writesEnabled(access) {
+    if (access === "read-only")
+        return false;
+    return typeof access !== "object" || access.write !== false;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAGzB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,GAAG,CAAC,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,CAAU,CAAC;AAC7F,MAAM,YAAY,GAAG,CAAC,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,CAAU,CAAC;AAE7G,MAAM,UAAU,MAAM,CAAC,MAAmD;IACxE,OAAO,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;QACjB,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;QAC7C,MAAM,YAAY,GAAG,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,CAAC;QACrD,MAAM,WAAW,GAAG,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;QACnD,IAAI,CAAC,QAAQ,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,wBAAwB,CAAC;YAC9B,WAAW,EAAE,GAAG;YAChB,YAAY,EAAE,kCAAkC;YAChD,QAAQ,EAAE,kCAAkC;YAC5C,QAAQ;YACR,YAAY;YACZ,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;YACpE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,uBAAuB,EAAE,qBAAqB;YAC9C,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAAmD;IACxE,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,KAAK,KAAK,CAAC;AAC9D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type ConnectionAuthDefinition, type HttpApiPluginConnectionOptions } from "@assemblyline-agents/core";
+export interface XConnectionOptions extends Omit<HttpApiPluginConnectionOptions, "auth" | "operations"> {
+    auth?: ConnectionAuthDefinition | false;
+}
+export declare function defineXConnection(options?: XConnectionOptions): import("@assemblyline-agents/core").HttpApiConnectionDefinition;
+export declare const assemblyLinePlugin: import("@assemblyline-agents/core").PluginModule;
+//# 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,EAIL,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACpC,MAAM,2BAA2B,CAAC;AAMnC,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,8BAA8B,EAAE,MAAM,GAAG,YAAY,CAAC;IACrG,IAAI,CAAC,EAAE,wBAAwB,GAAG,KAAK,CAAC;CACzC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,mEAOjE;AAED,eAAO,MAAM,kBAAkB,kDAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+import { connectionPluginMetadata, defineHttpApiPluginConnection, definePlugin } from "@assemblyline-agents/core";
+import { xOAuth } from "./auth.js";
+import { X_OPERATIONS } from "./operations.js";
+const PLUGIN = connectionPluginMetadata("x");
+export function defineXConnection(options = {}) {
+    const { auth, ...connection } = options;
+    return defineHttpApiPluginConnection(PLUGIN, {
+        ...connection,
+        operations: X_OPERATIONS,
+        auth: auth === false ? false : auth ?? xOAuth(options.access)
+    });
+}
+export const assemblyLinePlugin = definePlugin({ connections: [PLUGIN] });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,6BAA6B,EAC7B,YAAY,EAGb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,MAAM,GAAG,wBAAwB,CAAC,GAAG,CAAE,CAAC;AAM9C,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IACxC,OAAO,6BAA6B,CAAC,MAAM,EAAE;QAC3C,GAAG,UAAU;QACb,UAAU,EAAE,YAAY;QACxB,IAAI,EAAE,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;KAC9D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/dist/operations.d.ts

@@ -0,0 +1,3 @@
+import type { HttpApiOperationDefinition } from "@assemblyline-agents/core";
+export declare const X_OPERATIONS: HttpApiOperationDefinition[];
+//# sourceMappingURL=operations.d.ts.map

package/dist/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAc,MAAM,2BAA2B,CAAC;AA2CxF,eAAO,MAAM,YAAY,EAAE,0BAA0B,EAkDpD,CAAC"}

package/dist/operations.js

@@ -0,0 +1,108 @@
+const POST_ID_PATTERN = "^[0-9]{1,19}$";
+const BOOKMARK_TWEET_FIELDS = [
+    "article",
+    "attachments",
+    "author_id",
+    "conversation_id",
+    "created_at",
+    "edit_history_tweet_ids",
+    "entities",
+    "lang",
+    "note_tweet",
+    "possibly_sensitive",
+    "referenced_tweets",
+    "withheld"
+].join(",");
+const BOOKMARK_EXPANSIONS = [
+    "author_id",
+    "attachments.media_keys",
+    "referenced_tweets.id",
+    "referenced_tweets.id.author_id",
+    "referenced_tweets.id.attachments.media_keys"
+].join(",");
+const BOOKMARK_MEDIA_FIELDS = [
+    "alt_text",
+    "duration_ms",
+    "height",
+    "media_key",
+    "preview_image_url",
+    "type",
+    "url",
+    "variants",
+    "width"
+].join(",");
+const X_USER_FIELDS = "id,name,profile_image_url,protected,username,verified";
+const postIdSchema = (description) => ({
+    type: "string",
+    pattern: POST_ID_PATTERN,
+    description
+});
+export const X_OPERATIONS = [
+    {
+        name: "x_get_authenticated_user",
+        description: "Get the id, name, username, and profile details of the connected X account.",
+        method: "GET",
+        path: "/users/me",
+        parameters: [constantQuery("user.fields", X_USER_FIELDS)]
+    },
+    {
+        name: "x_list_bookmarks",
+        description: "List private bookmarked posts for the connected X account. The user id must match x_get_authenticated_user. Continue with pagination_token when next_token is returned.",
+        method: "GET",
+        path: "/users/{id}/bookmarks",
+        parameters: [
+            path("id", "Authenticated X user id returned by x_get_authenticated_user."),
+            query("max_results", { type: "integer", minimum: 1, maximum: 100 }),
+            query("pagination_token", { type: "string", minLength: 1, description: "Opaque next_token returned by X." }),
+            constantQuery("tweet.fields", BOOKMARK_TWEET_FIELDS),
+            constantQuery("expansions", BOOKMARK_EXPANSIONS),
+            constantQuery("media.fields", BOOKMARK_MEDIA_FIELDS),
+            constantQuery("user.fields", X_USER_FIELDS)
+        ]
+    },
+    {
+        name: "x_create_post",
+        description: "Publish a text post or reply from the connected X account.",
+        method: "POST",
+        path: "/tweets",
+        body: {
+            contentType: "application/json",
+            field: "body",
+            schema: objectSchema({
+                text: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 25_000,
+                    description: "Post text. X applies the connected account's product-specific character limit."
+                },
+                reply: objectSchema({
+                    in_reply_to_tweet_id: postIdSchema("Post id to reply to.")
+                }, ["in_reply_to_tweet_id"]),
+                reply_settings: {
+                    type: "string",
+                    enum: ["following", "mentionedUsers", "subscribers", "verified"],
+                    description: "Optional restriction on who may reply to this post."
+                }
+            }, ["text"]),
+            required: true
+        }
+    }
+];
+function path(name, description) {
+    return { name, in: "path", required: true, schema: postIdSchema(description) };
+}
+function query(name, schema) {
+    return { name, in: "query", schema };
+}
+function constantQuery(name, value) {
+    return { name, in: "query", value };
+}
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false
+    };
+}
+//# sourceMappingURL=operations.js.map

package/dist/operations.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@assemblyline-agents/x",
+  "version": "3.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@assemblyline-agents/core": "3.0.0"
+  },
+  "description": "Official Assembly Line direct X API connection plugin.",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonbadeaux/assembly-line.git",
+    "directory": "packages/x"
+  },
+  "bugs": {
+    "url": "https://github.com/jasonbadeaux/assembly-line/issues"
+  },
+  "homepage": "https://github.com/jasonbadeaux/assembly-line#readme",
+  "author": "Assembly Line contributors",
+  "keywords": [
+    "assembly-line",
+    "ai",
+    "agents",
+    "x",
+    "social",
+    "oauth",
+    "connection",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}