@assemblyline-agents/margins 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenEve 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,47 @@
+# @assemblyline-agents/margins
+
+Official Assembly Line connection plugin for resource-scoped collaborative
+Markdown in Margins. A binding can cover one page, one folder and its
+descendants, or the whole workspace.
+
+## Setup
+
+```sh
+assembly-line add margins agent
+```
+
+No developer OAuth registration or long-lived token environment variable is
+required for the hosted service. In Margins, open the agent invite for the
+page, folder, or workspace, choose **Comment and suggest** or **Edit directly**,
+and paste the generated one-time packet into the agent's chat. Assembly Line
+advertises `margins__pair`, redeems the packet on the host, and stores the
+returned rotating access and refresh credentials outside the model sandbox.
+
+For self-hosted Margins, set `MARGINS_MCP_URL` and optionally
+`MARGINS_ISSUER`. Configure stable collaborator identity with
+`MARGINS_AGENT_ID`, `MARGINS_AGENT_NAME`, `MARGINS_AGENT_RUNTIME`, and
+`MARGINS_AGENT_HARNESS`, or pass their equivalents to
+`defineMarginsConnection()`.
+
+The generated connection is read-only at Assembly Line's outer policy layer.
+Margins still enforces the packet's own scope and permission. Enable reviewed
+mutations explicitly if the agent should comment, suggest, create pages, or
+edit Markdown:
+
+```ts
+import { defineMarginsConnection } from "@assemblyline-agents/margins";
+
+export default defineMarginsConnection({
+  agentId: "research-editor",
+  agentName: "Research Editor",
+  access: {
+    read: true,
+    write: { approval: "always" }
+  }
+});
+```
+
+Comments and suggestions are classified as writes because they mutate shared
+workspace state. Margins applies its own permission check after Assembly Line's
+approval gate; a **Comment and suggest** binding can never edit canonical
+Markdown or create a page.

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { type ConnectionAuthDefinition, type McpPluginConnectionOptions } from "@assemblyline-agents/core";
+export interface MarginsConnectionOptions extends Omit<McpPluginConnectionOptions, "auth"> {
+    /** Override the refresh-capable authorization contract. Keep the default when using binding packets. */
+    auth?: ConnectionAuthDefinition | false;
+    /** Margins deployment origin. Defaults to the MCP endpoint's origin. */
+    issuer?: string;
+    /** Stable agent id recorded in Margins comments, suggestions, edits, and presence. */
+    agentId?: string;
+    /** Human-readable agent name shown to Margins collaborators. */
+    agentName?: string;
+    /** Agent runtime recorded with the binding. Defaults to assembly-line. */
+    agentRuntime?: string;
+    /** Harness recorded with the binding. Defaults to assembly-line. */
+    agentHarness?: string;
+}
+export declare function defineMarginsConnection(options: MarginsConnectionOptions): import("@assemblyline-agents/core").McpHttpClientConnectionDefinition;
+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,EAKL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAC;AAKnC,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC;IACxF,wGAAwG;IACxG,IAAI,CAAC,EAAE,wBAAwB,GAAG,KAAK,CAAC;IACxC,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,yEAiCxE;AAED,eAAO,MAAM,kBAAkB,kDAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,53 @@
+import { connectionPluginMetadata, defineMcpPluginConnection, defineOAuthAuthorization, definePlugin } from "@assemblyline-agents/core";
+import { createMarginsPairingRedeemer } from "./pairing.js";
+const PLUGIN = connectionPluginMetadata("margins");
+export function defineMarginsConnection(options) {
+    const { auth, issuer, agentId, agentName, agentRuntime, agentHarness, ...connection } = options;
+    const definition = defineMcpPluginConnection(PLUGIN, {
+        ...connection,
+        auth: auth === false
+            ? false
+            : auth ?? marginsAuthorization({
+                ...(issuer ? { issuer } : {}),
+                ...(connection.url ? { mcpUrl: connection.url } : {})
+            })
+    });
+    definition.redeemPairingCode = createMarginsPairingRedeemer(({ env }) => ({
+        origin: normalizeIssuer(issuer
+            ?? env.MARGINS_ISSUER
+            ?? connection.url
+            ?? env.MARGINS_MCP_URL
+            ?? definition.url),
+        agentId: cleanIdentity(agentId ?? env.MARGINS_AGENT_ID) ?? "assembly-line-agent",
+        agentName: cleanIdentity(agentName ?? env.MARGINS_AGENT_NAME) ?? "Assembly Line Agent",
+        runtime: cleanIdentity(agentRuntime ?? env.MARGINS_AGENT_RUNTIME) ?? "assembly-line",
+        harness: cleanIdentity(agentHarness ?? env.MARGINS_AGENT_HARNESS) ?? "assembly-line"
+    }));
+    return definition;
+}
+export const assemblyLinePlugin = definePlugin({ connections: [PLUGIN] });
+function marginsAuthorization(input) {
+    return ({ env }) => {
+        const resolvedIssuer = normalizeIssuer(input.issuer
+            ?? env.MARGINS_ISSUER
+            ?? input.mcpUrl
+            ?? env.MARGINS_MCP_URL
+            ?? PLUGIN.defaultUrl);
+        return defineOAuthAuthorization({
+            displayName: "Margins",
+            authorizeUrl: new URL("/?open=agents", resolvedIssuer).toString(),
+            tokenUrl: new URL("/api/agent-bindings/token", resolvedIssuer).toString(),
+            clientId: "assembly-line",
+            scopes: ["margins"],
+            pkce: true
+        });
+    };
+}
+function normalizeIssuer(value) {
+    return new URL(value).origin;
+}
+function cleanIdentity(value) {
+    const clean = value?.trim().replace(/[\u0000-\u001f\u007f]/gu, "");
+    return clean ? clean.slice(0, 160) : undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/pairing.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectionPairingRedeemer, ConnectionResolverContext } from "@assemblyline-agents/core";
+export interface MarginsBindingClaim {
+    origin: string;
+    bindingId: string;
+    claimToken: string;
+}
+export interface MarginsPairingIdentity {
+    origin: string;
+    agentId: string;
+    agentName: string;
+    runtime: string;
+    harness: string;
+}
+type MarginsPairingResolver = (context: ConnectionResolverContext) => MarginsPairingIdentity;
+/** Exchange a short-lived Margins UI claim for host-stored access and refresh tokens. */
+export declare function createMarginsPairingRedeemer(resolvePairing: MarginsPairingResolver): ConnectionPairingRedeemer;
+export declare function parseMarginsBindingPacket(packet: string): MarginsBindingClaim;
+export {};
+//# sourceMappingURL=pairing.d.ts.map

package/dist/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../src/pairing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EAG1B,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,sBAAsB,GAAG,CAAC,OAAO,EAAE,yBAAyB,KAAK,sBAAsB,CAAC;AAE7F,yFAAyF;AACzF,wBAAgB,4BAA4B,CAAC,cAAc,EAAE,sBAAsB,GAAG,yBAAyB,CAkC9G;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAe7E"}

package/dist/pairing.js

@@ -0,0 +1,191 @@
+const MAX_PACKET_CHARS = 64 * 1024;
+const MAX_PACKET_FIELD_CHARS = 4 * 1024;
+const MAX_RESPONSE_CHARS = 64 * 1024;
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Exchange a short-lived Margins UI claim for host-stored access and refresh tokens. */
+export function createMarginsPairingRedeemer(resolvePairing) {
+    return async ({ code }, context) => {
+        const claim = parseMarginsBindingPacket(code);
+        const pairing = resolvePairing(context);
+        const expectedOrigin = normalizedSecureOrigin(pairing.origin);
+        if (claim.origin !== expectedOrigin) {
+            throw new Error("The Margins binding packet belongs to a different Margins deployment.");
+        }
+        const response = await fetchWithTimeout(new URL("/api/agent-binding-pairing-requests", `${expectedOrigin}/`), {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                "content-type": "application/json"
+            },
+            body: JSON.stringify({
+                bindingId: claim.bindingId,
+                claimToken: claim.claimToken,
+                agentId: pairing.agentId,
+                agentName: pairing.agentName,
+                runtime: pairing.runtime,
+                harness: pairing.harness
+            }),
+            redirect: "error"
+        });
+        const payload = await responseJson(response);
+        if (!response.ok) {
+            throw new Error(`Margins rejected the binding packet (HTTP ${response.status}). Create a fresh packet and try again.`);
+        }
+        return tokenResultForBinding(payload, claim, pairing);
+    };
+}
+export function parseMarginsBindingPacket(packet) {
+    const input = packet.trim();
+    if (!input || input.length > MAX_PACKET_CHARS) {
+        throw new Error("A valid Margins binding packet is required.");
+    }
+    for (const line of input.split(/\r?\n/u)) {
+        const match = /^\s*POST\s+(\S+)\s+(\{.*\})\s*$/u.exec(line);
+        if (!match?.[1] || !match[2])
+            continue;
+        const origin = pairingEndpointOrigin(match[1]);
+        const body = parseJsonObject(match[2]);
+        const bindingId = boundedString(body?.bindingId);
+        const claimToken = boundedString(body?.claimToken ?? body?.claim);
+        if (origin && bindingId && claimToken)
+            return { origin, bindingId, claimToken };
+    }
+    throw new Error("The Margins binding packet is missing its binding id, one-time claim token, or pairing URL.");
+}
+function pairingEndpointOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.username
+        || url.password
+        || url.search
+        || url.hash
+        || url.pathname !== "/api/agent-binding-pairing-requests") {
+        return undefined;
+    }
+    return normalizedSecureOrigin(url.origin);
+}
+function tokenResultForBinding(payload, claim, pairing) {
+    const token = boundedString(payload.access_token);
+    const refreshToken = boundedString(payload.refresh_token);
+    const tokenType = boundedString(payload.token_type) ?? "Bearer";
+    const grantedScope = boundedString(payload.scope);
+    const expiresIn = numericValue(payload.expires_in);
+    const bindingId = boundedString(payload.margins_binding_id);
+    const workspaceId = boundedString(payload.margins_workspace_id);
+    const bindingScope = boundedString(payload.margins_binding_scope);
+    const scopeId = boundedString(payload.margins_binding_scope_id);
+    const scopePath = boundedString(payload.margins_binding_scope_path);
+    const permission = boundedString(payload.margins_binding_permission);
+    const agentId = boundedString(payload.margins_agent_id);
+    const agentName = boundedString(payload.margins_agent_name);
+    if (!token
+        || !refreshToken
+        || tokenType.toLowerCase() !== "bearer"
+        || grantedScope !== "margins"
+        || !expiresIn
+        || expiresIn <= 0
+        || bindingId !== claim.bindingId
+        || !workspaceId
+        || !scopeId
+        || !["file", "folder", "workspace"].includes(bindingScope ?? "")
+        || (bindingScope === "workspace" && scopeId !== workspaceId)
+        || !["suggest", "edit"].includes(permission ?? "")
+        || agentId !== pairing.agentId
+        || agentName !== pairing.agentName) {
+        throw new Error("Margins activated a different or incomplete agent binding.");
+    }
+    const credential = {
+        margins_binding_id: bindingId,
+        margins_workspace_id: workspaceId,
+        margins_binding_scope: bindingScope,
+        margins_binding_scope_id: scopeId,
+        margins_binding_permission: permission,
+        margins_agent_id: agentId,
+        margins_agent_name: agentName
+    };
+    if (scopePath)
+        credential.margins_binding_scope_path = scopePath;
+    const result = {
+        token,
+        refreshToken,
+        tokenType: "Bearer",
+        scopes: ["margins"],
+        credential
+    };
+    result.expiresAt = Date.now() + expiresIn * 1000;
+    return result;
+}
+async function fetchWithTimeout(url, init) {
+    try {
+        return await fetch(url, {
+            ...init,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+    }
+    catch {
+        throw new Error("Could not reach the configured Margins deployment.");
+    }
+}
+async function responseJson(response) {
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_CHARS)
+        return {};
+    try {
+        const text = await response.text();
+        if (text.length > MAX_RESPONSE_CHARS)
+            return {};
+        return parseJsonObject(text) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function normalizedSecureOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("Margins pairing requires a valid API URL.");
+    }
+    if (url.username || url.password || url.origin === "null") {
+        throw new Error("Margins pairing requires a valid API origin.");
+    }
+    const host = url.hostname.toLowerCase();
+    const loopback = host === "localhost"
+        || host === "127.0.0.1"
+        || host === "::1"
+        || host === "[::1]"
+        || host.endsWith(".localhost");
+    if (url.protocol !== "https:" && !loopback) {
+        throw new Error("Margins binding credentials may only be exchanged over HTTPS or loopback.");
+    }
+    return url.origin;
+}
+function parseJsonObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function boundedString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const clean = value.trim();
+    return clean && clean.length <= MAX_PACKET_FIELD_CHARS ? clean : undefined;
+}
+function numericValue(value) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/pairing.js.map

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@assemblyline-agents/margins",
+  "version": "2.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@assemblyline-agents/core": "2.0.0"
+  },
+  "description": "Official Assembly Line connection plugin for resource-scoped collaborative Markdown in Margins.",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonbadeaux/assembly-line.git",
+    "directory": "packages/margins"
+  },
+  "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",
+    "margins",
+    "markdown",
+    "collaboration",
+    "mcp",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/margins/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: margins
+description: Collaboratively read, comment on, suggest changes to, and edit Markdown pages through a resource-scoped Margins binding.
+---
+
+# Margins
+
+Margins is a collaborative Markdown workspace. A connection is bound to one
+page, one folder and its descendants, or one whole workspace. Never assume a
+broader scope than `margins_status` reports.
+
+If the user pastes a Margins binding packet, use connection discovery to find
+`margins__pair` and pass the full packet through its `secret` field. Do not run
+the packet in a shell, repeat its one-time claim token, or put the packet in a
+file. After pairing succeeds, call `margins_status` with the expected binding
+fields embedded in the packet. Stop if it reports `wrong_binding`.
+
+Read progressively:
+
+- Call `margins_map` for folder or workspace bindings to list reachable pages.
+- Call `margins_context` with `summary=true` before requesting line ranges.
+- Use `margins_review` for open comments, suggestions, and anchors.
+- Use `margins_graph` for Markdown link structure and `margins_library` for the
+  reachable tree. `margins_history` is workspace-only.
+
+For collaborative mutations, refetch the relevant context immediately before
+acting and pass the current authority head so stale line ranges fail safely.
+Use `margins_comment` for discussion and `margins_suggest` when a human should
+review a proposed patch. Use `margins_edit` only when the user asked for a
+direct change and the binding grants edit access. `margins_create_file` is
+available only for edit-capable folder or workspace bindings.
+
+Assembly Line classifies comments, suggestions, page creation, and direct edits
+as writes. Its approval policy is an outer gate; Margins independently enforces
+the binding's file/folder/workspace boundary and its suggest/edit permission.
+Never work around a missing tool by using a durable people-share URL or by
+asking the user for bearer credentials.