thinkwork-cli 0.12.11 → 0.12.15

package/dist/plugins/lastmile/src/manifest.ts

@@ -0,0 +1,139 @@
+/**
+ * LastMile plugin manifest — v0.1.0.
+ *
+ * Endpoint/auth values were captured from LastMile's live RFC 9728
+ * protected-resource metadata on 2026-06-12 (plan 2026-06-12-001 U9; the
+ * recorded capture lives in `discovery.fixture.ts` next to this file and
+ * is asserted against the manifest by `lastmile-discovery.test.ts`):
+ *
+ *   - One authorization server (WorkOS AuthKit staging) covers all three
+ *     MCP servers, so a single app-level activation mints tokens for the
+ *     whole plugin.
+ *   - Per-server RFC 8707 resource indicators are the server base URLs.
+ *   - The Routing server publishes protected-resource metadata and
+ *     therefore REQUIRES OAuth, despite a stale `auth_type: 'none'`
+ *     direct-add row that existed on dev — the manifest declares oauth.
+ *   - Endpoint URLs intentionally match the existing manually-added dev
+ *     `tenant_mcp_servers` rows EXACTLY, so the URL-dedupe coexistence
+ *     path (plugin row wins over a same-URL manual row at dispatch) is
+ *     exercised for real.
+ *
+ * KNOWN v1 GAP — per-stage endpoints: these are LastMile's DEVELOP-stage
+ * endpoints (`dev-mcp.lastmile-tei.com`); production is
+ * `mcp.lastmile-tei.com`. The manifest format has no per-stage endpoint
+ * parameterization yet, so a prod rollout currently requires publishing a
+ * new manifest version with the prod URLs. Tracked as a follow-up to plan
+ * 2026-06-12-001.
+ */
+
+const LASTMILE_AUTH_DOMAIN =
+  "https://straightforward-dragon-14-staging.authkit.app";
+
+const LASTMILE_MCP_BASE = "https://dev-mcp.lastmile-tei.com";
+
+const CRM_BASICS_SKILL_MD = `---
+name: lastmile--crm-basics
+description: Look up, summarize, and update LastMile CRM records through the LastMile CRM MCP tools. Use when a request involves LastMile customers, accounts, opportunities, or account history.
+---
+
+# LastMile CRM basics
+
+Work LastMile CRM requests through the \`lastmile--crm\` MCP server's
+tools — never guess at record contents from memory. The server covers
+opportunities and accounts; list its tools first if you are unsure what
+is available, since the exact tool set can change between LastMile
+releases.
+
+## Listing and filtering opportunities
+
+1. Use \`opportunities_list\` to enumerate opportunities. Apply the
+   narrowest filter the tool's input schema supports (owner, stage,
+   account) rather than listing everything and filtering in prose.
+2. If a request names a specific account or customer, resolve the account
+   first, then scope the opportunity listing to it.
+3. When more rows match than you can usefully summarize, say so and ask
+   how to narrow, instead of truncating silently.
+
+## Updating records
+
+1. Read the current record first and show the user the fields you are
+   about to change.
+2. Apply the smallest update that satisfies the request; never bulk-edit
+   fields the user did not mention.
+3. After writing, re-read the record and confirm the change took effect.
+
+## Summarizing
+
+When asked for an account or pipeline summary, pull the relevant records
+and lead with what changed most recently. State clearly when a field is
+empty or a record was not found — do not fill gaps from memory.
+`;
+
+export const lastmileManifest = {
+  pluginKey: "lastmile",
+  displayName: "LastMile",
+  description:
+    "LastMile CRM, task, and routing tools for field-service teams, with bundled skills for working customer records.",
+  versions: [
+    {
+      version: "0.1.0",
+      // scopes_supported is identical across all three servers (captured
+      // 2026-06-12); offline_access keeps refresh tokens flowing so an
+      // activation outlives the first access token.
+      requiredOauthScopes: ["openid", "email", "profile", "offline_access"],
+      components: [
+        {
+          type: "mcp-server",
+          key: "crm",
+          displayName: "LastMile CRM",
+          description: "Customer accounts and sales opportunities.",
+          endpointUrl: `${LASTMILE_MCP_BASE}/crm`,
+          auth: {
+            mode: "oauth",
+            authDomain: LASTMILE_AUTH_DOMAIN,
+            resourceIndicator: `${LASTMILE_MCP_BASE}/crm`,
+          },
+          toolNotes: [
+            "Opportunity and account tools, including opportunities_list for listing/filtering opportunities.",
+          ],
+        },
+        {
+          type: "mcp-server",
+          key: "tasks",
+          displayName: "LastMile Tasks",
+          description: "Work orders and task assignments.",
+          endpointUrl: `${LASTMILE_MCP_BASE}/tasks`,
+          auth: {
+            mode: "oauth",
+            authDomain: LASTMILE_AUTH_DOMAIN,
+            resourceIndicator: `${LASTMILE_MCP_BASE}/tasks`,
+          },
+          toolNotes: ["Task management tools."],
+        },
+        {
+          type: "mcp-server",
+          key: "routing",
+          displayName: "LastMile Routing",
+          description: "Route planning and technician dispatch.",
+          endpointUrl: `${LASTMILE_MCP_BASE}/routing`,
+          auth: {
+            mode: "oauth",
+            authDomain: LASTMILE_AUTH_DOMAIN,
+            resourceIndicator: `${LASTMILE_MCP_BASE}/routing`,
+          },
+          toolNotes: ["Route optimization tools."],
+        },
+        {
+          type: "skills",
+          key: "skills",
+          skills: [
+            {
+              slug: "lastmile--crm-basics",
+              skillMd: CRM_BASICS_SKILL_MD,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};

package/dist/plugins/lastmile/test/api/tasks-adapter.test.ts

@@ -0,0 +1,266 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createLastMileTasksAdapter,
+  type LastMileMcpClient,
+} from "../../src/api/tasks-adapter.js";
+
+const baseCreateInput = {
+  tenantId: "tenant-1",
+  spaceId: "space-1",
+  threadId: "thread-1",
+  checklistItemId: "checklist-1",
+  idempotencyKey: "tenant-1:thread-1:checklist-1",
+  title: "Collect sales tax exemption",
+  required: true,
+  assignee: {
+    roleKey: "accounting",
+    externalId: "user-100",
+    displayName: "Accounting Owner",
+  },
+};
+
+describe("LastMile Tasks adapter", () => {
+  let client: LastMileMcpClient & {
+    callTool: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    client = {
+      callTool: vi.fn(),
+    };
+  });
+
+  it("creates a task through the configured MCP tool and normalizes the response", async () => {
+    client.callTool.mockResolvedValueOnce({
+      structuredContent: {
+        task: {
+          id: "LM-100",
+          url: "https://tasks.example/LM-100",
+          title: "Collect sales tax exemption",
+          status: "In Progress",
+          assignee: { id: "user-100", name: "Accounting Owner" },
+          dueDate: "2026-06-01",
+        },
+      },
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    await expect(adapter.createTask(baseCreateInput)).resolves.toEqual({
+      ok: true,
+      value: expect.objectContaining({
+        externalTaskId: "LM-100",
+        externalTaskUrl: "https://tasks.example/LM-100",
+        status: "in_progress",
+        blocked: false,
+        syncStatus: "synced",
+        assignee: {
+          externalId: "user-100",
+          displayName: "Accounting Owner",
+        },
+        dueAt: "2026-06-01",
+        idempotent: false,
+        needsTriage: false,
+      }),
+    });
+    expect(client.callTool).toHaveBeenCalledWith({
+      serverName: "lastmile-tasks",
+      toolName: "create_task",
+      arguments: expect.objectContaining({
+        idempotencyKey: "tenant-1:thread-1:checklist-1",
+        title: "Collect sales tax exemption",
+        assignee: expect.objectContaining({ externalId: "user-100" }),
+      }),
+    });
+  });
+
+  it("treats duplicate/idempotent creates as successful existing task snapshots", async () => {
+    client.callTool.mockResolvedValueOnce({
+      structuredContent: {
+        result: {
+          taskId: "LM-100",
+          externalTaskUrl: "https://tasks.example/LM-100",
+          status: "todo",
+          existing: true,
+        },
+      },
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    const result = await adapter.createTask(baseCreateInput);
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        externalTaskId: "LM-100",
+        idempotent: true,
+        status: "todo",
+      },
+    });
+  });
+
+  it("creates an unassigned task and marks triage when a role has no external owner", async () => {
+    client.callTool.mockResolvedValueOnce({
+      structuredContent: {
+        task: {
+          id: "LM-101",
+          status: "not started",
+        },
+      },
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    const result = await adapter.createTask({
+      ...baseCreateInput,
+      assignee: { roleKey: "finance", displayName: "Finance" },
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        externalTaskId: "LM-101",
+        assignee: null,
+        needsTriage: true,
+        syncStatus: "synced",
+      },
+    });
+    expect(client.callTool).toHaveBeenCalledWith(
+      expect.objectContaining({
+        arguments: expect.objectContaining({
+          assignee: {
+            roleKey: "finance",
+            externalId: null,
+            displayName: "Finance",
+          },
+        }),
+      }),
+    );
+  });
+
+  it("preserves sanitized provider error detail for outages", async () => {
+    client.callTool.mockRejectedValueOnce({
+      status: 503,
+      message: "LastMile unavailable",
+      apiKey: "super-secret",
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    const result = await adapter.readTask({ externalTaskId: "LM-100" });
+
+    expect(result).toMatchObject({
+      ok: false,
+      providerError: {
+        code: "MCP_CALL_FAILED",
+        message: "LastMile unavailable",
+        status: 503,
+        retryable: true,
+        detail: {
+          status: 503,
+          message: "LastMile unavailable",
+          apiKey: "[redacted]",
+        },
+      },
+    });
+  });
+
+  it("maps provider permission denial without throwing", async () => {
+    client.callTool.mockResolvedValueOnce({
+      isError: true,
+      structuredContent: {
+        code: "FORBIDDEN",
+        status: 403,
+        message: "not allowed",
+      },
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    await expect(adapter.createTask(baseCreateInput)).resolves.toMatchObject({
+      ok: false,
+      providerError: {
+        code: "FORBIDDEN",
+        status: 403,
+        retryable: false,
+        message: "not allowed",
+      },
+    });
+  });
+
+  it("treats a provider response without a task id as an unhealthy sync response", async () => {
+    client.callTool.mockResolvedValueOnce({
+      structuredContent: {
+        task: {
+          title: "Collect sales tax exemption",
+          status: "todo",
+        },
+      },
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    await expect(adapter.createTask(baseCreateInput)).resolves.toMatchObject({
+      ok: false,
+      providerError: {
+        code: "PROVIDER_RESPONSE_MISSING_TASK_ID",
+        retryable: false,
+        message: "LastMile task provider response did not include a task id",
+      },
+    });
+  });
+
+  it("gates external comments through Space writeback policy before calling MCP", async () => {
+    const adapter = createLastMileTasksAdapter({ client });
+
+    await expect(
+      adapter.postComment({
+        externalTaskId: "LM-100",
+        body: "Coordinator summary",
+        writeback: {
+          policy: "status_and_comments",
+          action: "agent_comment",
+        },
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      blockedByPolicy: expect.objectContaining({
+        reason: "agent_comment_confirmation_required",
+      }),
+    });
+    expect(client.callTool).not.toHaveBeenCalled();
+  });
+
+  it("posts confirmed comments through MCP", async () => {
+    client.callTool.mockResolvedValueOnce({
+      structuredContent: {
+        commentId: "comment-1",
+        postedAt: "2026-05-19T00:00:00Z",
+      },
+    });
+    const adapter = createLastMileTasksAdapter({ client });
+
+    await expect(
+      adapter.postComment({
+        externalTaskId: "LM-100",
+        body: "Ready for accounting review",
+        writeback: {
+          policy: "status_and_comments",
+          action: "agent_comment",
+          humanConfirmed: true,
+        },
+      }),
+    ).resolves.toMatchObject({
+      ok: true,
+      value: {
+        externalTaskId: "LM-100",
+        commentId: "comment-1",
+      },
+    });
+    expect(client.callTool).toHaveBeenCalledWith({
+      serverName: "lastmile-tasks",
+      toolName: "post_comment",
+      arguments: {
+        externalTaskId: "LM-100",
+        body: "Ready for accounting review",
+        metadata: {},
+      },
+    });
+  });
+});

package/dist/plugins/lastmile/test/discovery.test.ts

@@ -0,0 +1,88 @@
+/**
+ * LastMile manifest ↔ recorded discovery metadata drift guard
+ * (plan 2026-06-12-001 U9).
+ *
+ * Asserts the published manifest against the RFC 9728 protected-resource
+ * metadata captured from LastMile's live develop-stage servers. The live
+ * half of this guard lives in `plugins/lastmile/smoke/lastmile-plugin-smoke.mjs`,
+ * which re-fetches the same endpoints; this test pins the manifest to the
+ * recorded fixture so the two can only drift apart loudly.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  validatePluginManifest,
+  type McpServerComponent,
+} from "@thinkwork/plugin-catalog/contracts";
+
+import { lastmileDiscoveryFixture } from "../src/discovery.fixture";
+import { lastmileManifest } from "../src/manifest";
+
+const SERVER_KEYS = ["crm", "tasks", "routing"] as const;
+const validatedLastmileManifest = validatePluginManifest(lastmileManifest);
+
+function mcpServer(key: string): McpServerComponent {
+  const component = validatedLastmileManifest.versions[0].components.find(
+    (candidate) => candidate.type === "mcp-server" && candidate.key === key,
+  );
+  if (component?.type !== "mcp-server") {
+    throw new Error(`manifest is missing mcp-server component "${key}"`);
+  }
+  return component;
+}
+
+describe("lastmile manifest vs recorded discovery metadata", () => {
+  it("declares exactly the three discovered MCP servers", () => {
+    const keys = validatedLastmileManifest.versions[0].components
+      .filter((component) => component.type === "mcp-server")
+      .map((component) => component.key)
+      .sort();
+    expect(keys).toEqual([...SERVER_KEYS].sort());
+  });
+
+  it.each(SERVER_KEYS)(
+    "%s endpoint and resource indicator match the recorded resource",
+    (key) => {
+      const recorded = lastmileDiscoveryFixture[key];
+      const component = mcpServer(key);
+      expect(component.endpointUrl).toBe(recorded.resource);
+      if (component.auth.mode !== "oauth") {
+        throw new Error(`mcp-server "${key}" must declare oauth`);
+      }
+      expect(component.auth.resourceIndicator).toBe(recorded.resource);
+    },
+  );
+
+  it.each(SERVER_KEYS)(
+    "%s auth domain is the recorded authorization server",
+    (key) => {
+      const recorded = lastmileDiscoveryFixture[key];
+      const component = mcpServer(key);
+      if (component.auth.mode !== "oauth") {
+        throw new Error(`mcp-server "${key}" must declare oauth`);
+      }
+      expect(recorded.authorization_servers).toContain(
+        component.auth.authDomain,
+      );
+      // One AS covers the whole plugin — a single app-level activation.
+      expect(recorded.authorization_servers).toHaveLength(1);
+    },
+  );
+
+  it.each(SERVER_KEYS)(
+    "requiredOauthScopes are exactly the scopes %s supports",
+    (key) => {
+      const recorded = lastmileDiscoveryFixture[key];
+      expect(
+        [...validatedLastmileManifest.versions[0].requiredOauthScopes].sort(),
+      ).toEqual([...recorded.scopes_supported].sort());
+    },
+  );
+
+  it("contains no placeholder values", () => {
+    const serialized = JSON.stringify(lastmileManifest);
+    expect(serialized).not.toMatch(/\.invalid/);
+    expect(serialized).not.toMatch(/PLACEHOLDER/i);
+  });
+});

package/dist/plugins/lastmile/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": ["./**/*.ts"]
+}