@tickernelz/paperclip-pro-shared 2026.925.0

package/dist/config-schema.test.js

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { findPaperclipConfigKeyWarnings, mergePaperclipConfig, paperclipConfigSchema, } from "./config-schema.js";
+describe("paperclip config schema", () => {
+    it("defaults omitted runtime paths to legacy instance-root locations", () => {
+        const parsed = paperclipConfigSchema.parse({
+            $meta: {
+                version: 1,
+                updatedAt: "2026-05-10T00:00:00.000Z",
+                source: "configure",
+            },
+            database: {
+                mode: "embedded-postgres",
+            },
+            logging: {
+                mode: "file",
+            },
+            server: {},
+        });
+        expect(parsed.database.embeddedPostgresDataDir).toBe("~/.paperclip-pro/instances/default/db");
+        expect(parsed.database.backup.dir).toBe("~/.paperclip-pro/instances/default/data/backups");
+        expect(parsed.logging.logDir).toBe("~/.paperclip-pro/instances/default/logs");
+        expect(parsed.storage.localDisk.baseDir).toBe("~/.paperclip-pro/instances/default/data/storage");
+        expect(parsed.secrets.localEncrypted.keyFilePath).toBe("~/.paperclip-pro/instances/default/secrets/master.key");
+    });
+    it("retains extension keys at the top level and every nested config boundary", () => {
+        const parsed = paperclipConfigSchema.parse({
+            $meta: {
+                version: 1,
+                updatedAt: "2026-05-10T00:00:00.000Z",
+                source: "configure",
+                extensionMeta: "keep",
+            },
+            database: {
+                mode: "embedded-postgres",
+                backup: {
+                    backupExtension: "keep",
+                },
+            },
+            logging: {
+                mode: "file",
+            },
+            server: {
+                serverExtension: "keep",
+            },
+            storage: {
+                localDisk: {
+                    driverExtension: "keep",
+                },
+                s3: {
+                    s3Extension: "keep",
+                },
+            },
+            secrets: {
+                localEncrypted: {
+                    providerExtension: "keep",
+                },
+            },
+            topLevelExtension: {
+                enabled: true,
+            },
+        });
+        expect(parsed).toMatchObject({
+            $meta: { extensionMeta: "keep" },
+            database: { backup: { backupExtension: "keep" } },
+            server: { serverExtension: "keep" },
+            storage: {
+                localDisk: { driverExtension: "keep" },
+                s3: { s3Extension: "keep" },
+            },
+            secrets: { localEncrypted: { providerExtension: "keep" } },
+            topLevelExtension: { enabled: true },
+        });
+    });
+    it("merges retained extensions without resurrecting removed known fields", () => {
+        const source = paperclipConfigSchema.parse({
+            $meta: {
+                version: 1,
+                updatedAt: "2026-05-10T00:00:00.000Z",
+                source: "configure",
+            },
+            llm: {
+                provider: "openai",
+                apiKey: "remove-me",
+                providerExtension: "keep",
+            },
+            database: { mode: "embedded-postgres" },
+            logging: { mode: "file" },
+            server: { port: 3100, serverExtension: "keep" },
+            topLevelExtension: "keep",
+        });
+        const update = paperclipConfigSchema.parse({
+            ...source,
+            llm: {
+                provider: "openai",
+            },
+            server: {
+                ...source.server,
+                port: 3200,
+            },
+        });
+        const merged = mergePaperclipConfig(source, update);
+        expect(merged.server.port).toBe(3200);
+        expect(merged.server.serverExtension).toBe("keep");
+        expect(merged.topLevelExtension).toBe("keep");
+        expect(merged.llm?.providerExtension).toBe("keep");
+        expect(merged.llm).not.toHaveProperty("apiKey");
+    });
+    it("warns about likely misspellings while leaving arbitrary extensions alone", () => {
+        expect(findPaperclipConfigKeyWarnings({
+            servr: {},
+            server: {
+                ports: 3100,
+                pluginOptions: {
+                    arbitrary: true,
+                },
+            },
+            extensionNamespace: {
+                port: 9999,
+            },
+        })).toEqual([
+            { path: "servr", suggestion: "server" },
+            { path: "server.ports", suggestion: "server.port" },
+        ]);
+    });
+});
+//# sourceMappingURL=config-schema.test.js.map

package/dist/config-schema.test.js.map

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

package/dist/connection-intent-guidance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Canonical instructions for the run-scoped connection tools.
+ *
+ * Keep this text provider-neutral and free of run identity, credentials, URLs,
+ * or bearer tokens: it is reused in prompts, adapter descriptors, CLI help,
+ * environment delivery, and MCP tool descriptions.
+ */
+export declare const CONNECTION_INTENT_AGENT_GUIDANCE: string;
+export declare const CONNECTIONS_SEARCH_TOOL_DESCRIPTION: string;
+export declare const CONNECTION_REQUEST_TOOL_DESCRIPTION: string;
+export declare const CONNECTION_RUNTIME_TOOL_NAMES: readonly ["connections_search", "connection_request"];
+//# sourceMappingURL=connection-intent-guidance.d.ts.map

package/dist/connection-intent-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-intent-guidance.d.ts","sourceRoot":"","sources":["../src/connection-intent-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,QAYjC,CAAC;AAEb,eAAO,MAAM,mCAAmC,QAIrC,CAAC;AAEZ,eAAO,MAAM,mCAAmC,QAIrC,CAAC;AAEZ,eAAO,MAAM,6BAA6B,YACxC,oBAAoB,EACpB,oBAAoB,CACZ,CAAC"}

package/dist/connection-intent-guidance.js

@@ -0,0 +1,35 @@
+/**
+ * Canonical instructions for the run-scoped connection tools.
+ *
+ * Keep this text provider-neutral and free of run identity, credentials, URLs,
+ * or bearer tokens: it is reused in prompts, adapter descriptors, CLI help,
+ * environment delivery, and MCP tool descriptions.
+ */
+export const CONNECTION_INTENT_AGENT_GUIDANCE = [
+    "Connection tools:",
+    "- When work requires a known external service and usable access is uncertain, call `connections_search` with the service name or capability.",
+    "- This applies both when the user explicitly asks to connect a service and when the requested work implicitly depends on that service.",
+    "- If search returns `ready`, use the installed connection; do not create a connection intent.",
+    "- If search returns `available` or `needs_user_action`, call `connection_request` with the returned service identifier.",
+    "- When the user has already asked to connect a known service, use the real connection request. Do not ask whether to connect again or imitate the Connect / Not now card with `ask_user_questions`, a generic confirmation, or a comment. Only `connection_request` creates the actual connection setup card.",
+    "- If search returns `unavailable`, explain that the service is unavailable and do not call `connection_request`.",
+    "- If `connection_request` returns `needs_user_action`, finish any independent work, then yield in a waiting posture. Do not retry the request, ask for credentials in comments, or claim access.",
+    "- Do not use connection tools for arbitrary MCP URLs, unsupported services, or work that does not require an external service.",
+    "- Keep an existing pending card across messages. Do not request again after the user declines unless they explicitly ask to retry.",
+    "- On a continuation run after connection setup, use the newly installed connection instead of requesting it again.",
+].join("\n");
+export const CONNECTIONS_SEARCH_TOOL_DESCRIPTION = [
+    "Search Paperclip's catalog services and authorized configured custom connections and report this run's agent-relative access state.",
+    "Use it when work requires a known external service and usable access is uncertain; do not use it for arbitrary MCP URLs or unrelated work.",
+    "If the user already asked to connect the service, search and request it through the connection tools instead of asking a generic confirmation question.",
+].join(" ");
+export const CONNECTION_REQUEST_TOOL_DESCRIPTION = [
+    "Request access to a known connectable service for this run's agent from the responsible user.",
+    "This creates the real Connect / Not now setup card. When the user already asked to connect, use this tool; do not recreate those choices with ask_user_questions, request_confirmation, or a comment. A generic question does not start connection setup.",
+    "Call it only with the service identifier returned as available or needs_user_action by connections_search; if user action is needed, finish independent work, then yield without retrying or asking for credentials in comments.",
+].join(" ");
+export const CONNECTION_RUNTIME_TOOL_NAMES = [
+    "connections_search",
+    "connection_request",
+];
+//# sourceMappingURL=connection-intent-guidance.js.map

package/dist/connection-intent-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-intent-guidance.js","sourceRoot":"","sources":["../src/connection-intent-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,mBAAmB;IACnB,8IAA8I;IAC9I,wIAAwI;IACxI,+FAA+F;IAC/F,yHAAyH;IACzH,+SAA+S;IAC/S,kHAAkH;IAClH,kMAAkM;IAClM,gIAAgI;IAChI,oIAAoI;IACpI,oHAAoH;CACrH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,mCAAmC,GAAG;IACjD,qIAAqI;IACrI,4IAA4I;IAC5I,yJAAyJ;CAC1J,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,MAAM,CAAC,MAAM,mCAAmC,GAAG;IACjD,+FAA+F;IAC/F,2PAA2P;IAC3P,kOAAkO;CACnO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,oBAAoB;IACpB,oBAAoB;CACZ,CAAC"}

package/dist/connection-intent-guidance.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connection-intent-guidance.test.d.ts.map

package/dist/connection-intent-guidance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-intent-guidance.test.d.ts","sourceRoot":"","sources":["../src/connection-intent-guidance.test.ts"],"names":[],"mappings":""}

package/dist/connection-intent-guidance.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { CONNECTION_INTENT_AGENT_GUIDANCE, CONNECTION_REQUEST_TOOL_DESCRIPTION, CONNECTION_RUNTIME_TOOL_NAMES, CONNECTIONS_SEARCH_TOOL_DESCRIPTION, } from "./connection-intent-guidance.js";
+describe("connection intent agent guidance", () => {
+    it.each([
+        [
+            "explicit connect request",
+            "explicitly asks to connect",
+            "connections_search",
+        ],
+        [
+            "implicit service dependency",
+            "implicitly depends on that service",
+            "connections_search",
+        ],
+        [
+            "already-ready service",
+            "returns `ready`",
+            "do not create a connection intent",
+        ],
+        [
+            "available service",
+            "returns `available` or `needs_user_action`",
+            "connection_request",
+        ],
+        [
+            "unavailable service",
+            "returns `unavailable`",
+            "do not call `connection_request`",
+        ],
+        ["arbitrary MCP URL", "arbitrary MCP URLs", "Do not use connection tools"],
+        [
+            "pending user action",
+            "returns `needs_user_action`",
+            "finish any independent work, then yield in a waiting posture",
+        ],
+        [
+            "continuation run",
+            "On a continuation run",
+            "instead of requesting it again",
+        ],
+    ])("gives an explicit instruction for %s", (_scenario, trigger, action) => {
+        expect(CONNECTION_INTENT_AGENT_GUIDANCE).toContain(trigger);
+        expect(CONNECTION_INTENT_AGENT_GUIDANCE).toContain(action);
+    });
+    it("names the canonical tools without embedding secrets or authorization URLs", () => {
+        expect(CONNECTION_RUNTIME_TOOL_NAMES).toEqual([
+            "connections_search",
+            "connection_request",
+        ]);
+        expect(CONNECTION_INTENT_AGENT_GUIDANCE).not.toMatch(/bearer|credential value|https?:\/\//i);
+    });
+    it("keeps MCP descriptions aligned with the guidance decision points", () => {
+        expect(CONNECTIONS_SEARCH_TOOL_DESCRIPTION).toContain("usable access is uncertain");
+        expect(CONNECTIONS_SEARCH_TOOL_DESCRIPTION).toContain("arbitrary MCP URLs");
+        expect(CONNECTION_REQUEST_TOOL_DESCRIPTION).toContain("available or needs_user_action");
+        expect(CONNECTION_REQUEST_TOOL_DESCRIPTION).toContain("finish independent work, then yield");
+        expect(CONNECTION_REQUEST_TOOL_DESCRIPTION).toContain("without retrying");
+    });
+});
+//# sourceMappingURL=connection-intent-guidance.test.js.map

package/dist/connection-intent-guidance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-intent-guidance.test.js","sourceRoot":"","sources":["../src/connection-intent-guidance.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,6BAA6B,EAC7B,mCAAmC,GACpC,MAAM,iCAAiC,CAAC;AAEzC,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,EAAE,CAAC,IAAI,CAAC;QACN;YACE,0BAA0B;YAC1B,4BAA4B;YAC5B,oBAAoB;SACrB;QACD;YACE,6BAA6B;YAC7B,oCAAoC;YACpC,oBAAoB;SACrB;QACD;YACE,uBAAuB;YACvB,iBAAiB;YACjB,mCAAmC;SACpC;QACD;YACE,mBAAmB;YACnB,4CAA4C;YAC5C,oBAAoB;SACrB;QACD;YACE,qBAAqB;YACrB,uBAAuB;YACvB,kCAAkC;SACnC;QACD,CAAC,mBAAmB,EAAE,oBAAoB,EAAE,6BAA6B,CAAC;QAC1E;YACE,qBAAqB;YACrB,6BAA6B;YAC7B,8DAA8D;SAC/D;QACD;YACE,kBAAkB;YAClB,uBAAuB;YACvB,gCAAgC;SACjC;KACF,CAAC,CAAC,sCAAsC,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;QACxE,MAAM,CAAC,gCAAgC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5D,MAAM,CAAC,gCAAgC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2EAA2E,EAAE,GAAG,EAAE;QACnF,MAAM,CAAC,6BAA6B,CAAC,CAAC,OAAO,CAAC;YAC5C,oBAAoB;YACpB,oBAAoB;SACrB,CAAC,CAAC;QACH,MAAM,CAAC,gCAAgC,CAAC,CAAC,GAAG,CAAC,OAAO,CAClD,sCAAsC,CACvC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,CAAC,mCAAmC,CAAC,CAAC,SAAS,CACnD,4BAA4B,CAC7B,CAAC;QACF,MAAM,CAAC,mCAAmC,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QAC5E,MAAM,CAAC,mCAAmC,CAAC,CAAC,SAAS,CACnD,gCAAgC,CACjC,CAAC;QACF,MAAM,CAAC,mCAAmC,CAAC,CAAC,SAAS,CAAC,qCAAqC,CAAC,CAAC;QAC7F,MAAM,CAAC,mCAAmC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}