@assemblyline-agents/mirror 0.1.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,68 @@
+# @assemblyline-agents/mirror
+
+Official Assembly Line connection plugin for [Mirror](https://github.com/jasonbadeaux/mirror).
+It gives each authenticated agent user an optional, separately authorized path
+to their mirrored source records and connected accounts.
+
+## Setup
+
+Choose a stable public client id for the agent deployment and set:
+
+```sh
+MIRROR_OAUTH_CLIENT_ID=my-assembly-line-agent
+```
+
+Mirror accepts Assembly Line's OAuth Authorization Code flow with mandatory PKCE
+S256. The normal callback is:
+
+```text
+https://YOUR-AGENT-HOST/openeve/connections/callback
+```
+
+The runtime also serves `/assembly-line/connections/callback`; callback-URL
+construction still emits the legacy `/openeve/...` path during the rename
+compatibility window, so register the URI shown above until it flips.
+
+The hosted service and MCP endpoint are used by default. Self-hosted
+deployments can set `MIRROR_MCP_URL` and, when OAuth is on a different origin,
+`MIRROR_OAUTH_ISSUER`. `MIRROR_OAUTH_REDIRECT_URI` overrides Assembly Line's normal
+callback only when necessary.
+
+```sh
+assembly-line add mirror agent
+```
+
+The generated connection exposes Mirror reads and hides all write-like tools.
+To permit approval creation, syncs, connection links, registration, or other
+mutations, opt in with an Assembly Line approval policy:
+
+```ts
+import { defineMirrorConnection } from "@assemblyline-agents/mirror";
+
+export default defineMirrorConnection({
+  access: {
+    read: true,
+    write: { approval: "always" }
+  }
+});
+```
+
+Mirror still enforces its own account grants and exact-action approval system;
+Assembly Line's approval is an additional outer gate.
+
+## Optional Mirror CLI
+
+The MCP connection is the default and works without a CLI. If the sandbox
+image already contains the `mirror` executable, opt in to a short-lived CLI
+profile:
+
+```ts
+export default defineMirrorConnection({
+  materializeCli: true,
+  access: { read: true, write: false }
+});
+```
+
+Assembly Line writes `/root/.mirror/config.json` with mode `0600`. Only the current
+access token is projected. The rotating refresh token stays in the host-side
+grant store and is never written into the sandbox.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type ConnectionAuthDefinition, type McpPluginConnectionOptions } from "@assemblyline-agents/core";
+export interface MirrorCliMaterializationOptions {
+    /** Sandbox path for the projected CLI profile. Defaults to /root/.mirror/config.json. */
+    path?: string;
+    /** Mirror CLI profile name. Defaults to openeve. */
+    profile?: string;
+    /** Runtime recorded in the projected profile. Defaults to openeve. */
+    runtime?: string;
+    /** Mirror API origin. Defaults to the configured MCP endpoint's origin. */
+    apiUrl?: string;
+}
+export interface MirrorConnectionOptions extends Omit<McpPluginConnectionOptions, "auth"> {
+    auth?: ConnectionAuthDefinition | false;
+    /** Stable public OAuth client id shown on Mirror's consent screen. */
+    clientId?: string;
+    /** Mirror authorization-server origin. Defaults to the MCP endpoint's origin. */
+    issuer?: string;
+    /** Override OpenEve's normal /openeve/connections/callback URI. */
+    redirectUri?: string;
+    /**
+     * Project the short-lived access token into a Mirror CLI profile.
+     * The sandbox image must already contain the `mirror` CLI. Refresh tokens
+     * always remain in OpenEve's host-side grant store.
+     */
+    materializeCli?: boolean | MirrorCliMaterializationOptions;
+}
+export declare function defineMirrorConnection(options: MirrorConnectionOptions): import("@assemblyline-agents/core").McpHttpClientConnectionDefinition;
+export declare const openevePlugin: 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;AAInC,MAAM,WAAW,+BAA+B;IAC9C,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC;IACvF,IAAI,CAAC,EAAE,wBAAwB,GAAG,KAAK,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,+BAA+B,CAAC;CAC5D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,yEAiDtE;AAED,eAAO,MAAM,aAAa,kDAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,71 @@
+import { connectionPluginMetadata, defineMcpPluginConnection, defineOAuthAuthorization, definePlugin } from "@assemblyline-agents/core";
+const PLUGIN = connectionPluginMetadata("mirror");
+export function defineMirrorConnection(options) {
+    const { auth, clientId, issuer, redirectUri, materializeCli, ...connection } = options;
+    const definition = defineMcpPluginConnection(PLUGIN, {
+        ...connection,
+        auth: auth === false
+            ? false
+            : auth ?? mirrorOAuth({
+                ...(clientId ? { clientId } : {}),
+                ...(issuer ? { issuer } : {}),
+                ...(redirectUri ? { redirectUri } : {}),
+                ...(connection.url ? { mcpUrl: connection.url } : {})
+            })
+    });
+    if (materializeCli) {
+        const settings = materializeCli === true ? {} : materializeCli;
+        const profile = settings.profile?.trim() || "openeve";
+        const runtime = settings.runtime?.trim() || "openeve";
+        const apiUrl = normalizeIssuer(settings.apiUrl ?? issuer ?? definition.url);
+        definition.materialize = {
+            files: [{
+                    path: settings.path?.trim() || "/root/.mirror/config.json",
+                    content: `${JSON.stringify({
+                        version: 1,
+                        currentProfile: profile,
+                        profiles: {
+                            [profile]: {
+                                apiUrl,
+                                userId: "{{credential.mirror_user_id}}",
+                                branchId: "{{credential.mirror_branch_id}}",
+                                bindingId: "{{credential.mirror_binding_id}}",
+                                bindingToken: "{{token}}",
+                                runtime
+                            }
+                        }
+                    }, null, 2)}\n`,
+                    mode: 0o600
+                }]
+        };
+    }
+    return definition;
+}
+export const openevePlugin = definePlugin({ connections: [PLUGIN] });
+function mirrorOAuth(input) {
+    return ({ env }) => {
+        const resolvedClientId = input.clientId?.trim() || env.MIRROR_OAUTH_CLIENT_ID?.trim();
+        if (!resolvedClientId) {
+            throw new Error("Mirror OAuth requires MIRROR_OAUTH_CLIENT_ID or clientId.");
+        }
+        const resolvedIssuer = normalizeIssuer(input.issuer
+            ?? env.MIRROR_OAUTH_ISSUER
+            ?? input.mcpUrl
+            ?? env.MIRROR_MCP_URL
+            ?? PLUGIN.defaultUrl);
+        const resolvedRedirectUri = input.redirectUri?.trim() || env.MIRROR_OAUTH_REDIRECT_URI?.trim();
+        return defineOAuthAuthorization({
+            displayName: "Mirror",
+            authorizeUrl: new URL("/oauth/authorize", resolvedIssuer).toString(),
+            tokenUrl: new URL("/oauth/token", resolvedIssuer).toString(),
+            clientId: resolvedClientId,
+            ...(resolvedRedirectUri ? { redirectUri: resolvedRedirectUri } : {}),
+            pkce: true
+        });
+    };
+}
+function normalizeIssuer(value) {
+    const url = new URL(value);
+    return url.origin;
+}
+//# 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,yBAAyB,EACzB,wBAAwB,EACxB,YAAY,EAGb,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,GAAG,wBAAwB,CAAC,QAAQ,CAAE,CAAC;AA6BnD,MAAM,UAAU,sBAAsB,CAAC,OAAgC;IACrE,MAAM,EACJ,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,WAAW,EACX,cAAc,EACd,GAAG,UAAU,EACd,GAAG,OAAO,CAAC;IACZ,MAAM,UAAU,GAAG,yBAAyB,CAAC,MAAM,EAAE;QACnD,GAAG,UAAU;QACb,IAAI,EAAE,IAAI,KAAK,KAAK;YAClB,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,IAAI,IAAI,WAAW,CAAC;gBAClB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtD,CAAC;KACP,CAAC,CAAC;IAEH,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,QAAQ,GAAG,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC;QAC/D,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;QACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;QACtD,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,MAAM,IAAI,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;QAC5E,UAAU,CAAC,WAAW,GAAG;YACvB,KAAK,EAAE,CAAC;oBACN,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,2BAA2B;oBAC1D,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;wBACzB,OAAO,EAAE,CAAC;wBACV,cAAc,EAAE,OAAO;wBACvB,QAAQ,EAAE;4BACR,CAAC,OAAO,CAAC,EAAE;gCACT,MAAM;gCACN,MAAM,EAAE,+BAA+B;gCACvC,QAAQ,EAAE,iCAAiC;gCAC3C,SAAS,EAAE,kCAAkC;gCAC7C,YAAY,EAAE,WAAW;gCACzB,OAAO;6BACR;yBACF;qBACF,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;oBACf,IAAI,EAAE,KAAK;iBACZ,CAAC;SACH,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAErE,SAAS,WAAW,CAAC,KAKpB;IACC,OAAO,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;QACjB,MAAM,gBAAgB,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,CAAC;QACtF,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,cAAc,GAAG,eAAe,CACpC,KAAK,CAAC,MAAM;eACT,GAAG,CAAC,mBAAmB;eACvB,KAAK,CAAC,MAAM;eACZ,GAAG,CAAC,cAAc;eAClB,MAAM,CAAC,UAAW,CACtB,CAAC;QACF,MAAM,mBAAmB,GAAG,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE,CAAC;QAC/F,OAAO,wBAAwB,CAAC;YAC9B,WAAW,EAAE,QAAQ;YACrB,YAAY,EAAE,IAAI,GAAG,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC,QAAQ,EAAE;YACpE,QAAQ,EAAE,IAAI,GAAG,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,QAAQ,EAAE;YAC5D,QAAQ,EAAE,gBAAgB;YAC1B,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3B,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@assemblyline-agents/mirror",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@assemblyline-agents/core": "0.1.0"
+  },
+  "description": "Official OpenEve connection plugin for user-scoped Mirror accounts.",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonbadeaux/openeve.git",
+    "directory": "packages/mirror"
+  },
+  "bugs": {
+    "url": "https://github.com/jasonbadeaux/openeve/issues"
+  },
+  "homepage": "https://github.com/jasonbadeaux/openeve#readme",
+  "author": "OpenEve contributors",
+  "keywords": [
+    "openeve",
+    "ai",
+    "agents",
+    "mirror",
+    "mcp",
+    "oauth",
+    "connected-accounts",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/mirror/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: mirror
+description: Use a connected Mirror account to inspect the user's allowed connected providers, query mirrored records, perform bounded live reads, and stage approval-gated actions.
+---
+
+# Mirror
+
+Mirror is the user's connected-context layer. It holds downstream provider
+credentials and exposes only the providers and accounts granted to this agent.
+Never ask for, print, or store raw provider credentials.
+
+Start with `mirror.whoami`, then `mirror.connected_providers`. Inspect each
+lane's access and mirror policy before choosing a tool:
+
+- Use `mirror.query_records` for normal recall from a mirrored lane.
+- Use `mirror.get_source` for one exact raw record.
+- Use `mirror.live_read` only for current state or detail absent from the
+  mirror.
+- Use `mirror.get_pending_approvals` to inspect unresolved action requests.
+
+Keep reads bounded by provider, account, identifiers, dates, and explicit
+limits. Check message authorship metadata rather than inferring who wrote a
+message from its prose.
+
+Write-like provider operations, syncs, setup links, agent registration,
+approval creation/redemption, and credential export are classified as writes
+by Assembly Line. Use them only when the connection exposes write authority and its
+approval gate permits the call. Mirror may apply an additional exact-action
+approval before executing a downstream mutation.
+
+The MCP tools are the normal Assembly Line connection surface. If the deployment
+owner installed the optional `mirror` CLI and enabled `materializeCli`, the CLI
+may be used inside the sandbox; its profile contains only a short-lived access
+token. Refresh credentials remain on the Assembly Line host.