Fix tool result contracts

Author: RhysSullivan

apps/cloud/src/services/sources-api.node.test.ts

@@ -398,7 +398,7 @@ describe("sources api (HTTP)", () => {
         status: "completed",
         result: {
           ok: true,
-          data: [{ type: "text", text: "cloud-mcp-ok" }],
+          data: { content: [{ type: "text", text: "cloud-mcp-ok" }] },
         },
       });
       expect((yield* server.requests).length).toBeGreaterThanOrEqual(2);

apps/local/src/server/migrate-oauth-connections.test.ts

@@ -159,7 +159,7 @@ describe("0009_repair_openapi_oauth_cutover_residue", () => {
     `);
 
     db.prepare("INSERT INTO `openapi_source` (id, scope_id, oauth2) VALUES (?, ?, ?)").run(
-      "dealcloud_api",
+      "example_api",
       "org-1",
       JSON.stringify({
         kind: "oauth2",
@@ -174,27 +174,27 @@ describe("0009_repair_openapi_oauth_cutover_residue", () => {
       "INSERT INTO `connection` (id, scope_id, provider, provider_state, scope, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
     );
     insertConnection.run(
-      "openapi-oauth2-app-dealcloud_api",
+      "openapi-oauth2-app-example_api",
       "org-1",
       "oauth2",
       JSON.stringify({
         kind: "client-credentials",
-        tokenEndpoint: "https://resolve.dealcloud.com/oauth/token",
-        clientIdSecretId: "dealcloud-client-id",
-        clientSecretSecretId: "dealcloud-client-secret",
+        tokenEndpoint: "https://auth.example.test/oauth/token",
+        clientIdSecretId: "example-client-id",
+        clientSecretSecretId: "example-client-secret",
       }),
       null,
       now,
     );
     insertConnection.run(
-      "openapi-oauth2-app-dealcloud_api",
+      "openapi-oauth2-app-example_api",
       "user-org:user-jd:org-1",
       "openapi:oauth2",
       JSON.stringify({
         kind: "client-credentials",
-        tokenEndpoint: "https://resolve.dealcloud.com/oauth/token",
-        clientIdSecretId: "dealcloud-client-id-jd",
-        clientSecretSecretId: "dealcloud-client-secret-jd",
+        tokenEndpoint: "https://auth.example.test/oauth/token",
+        clientIdSecretId: "example-client-id-jd",
+        clientSecretSecretId: "example-client-secret-jd",
       }),
       null,
       now,
@@ -207,12 +207,12 @@ describe("0009_repair_openapi_oauth_cutover_residue", () => {
       "org-client-id",
       "org-1",
       "openapi",
-      "dealcloud_api",
+      "example_api",
       "org-1",
       "oauth2:oauth2:client-id",
       "secret",
       null,
-      "dealcloud-client-id-jd",
+      "example-client-id-jd",
       null,
       now,
       now,
@@ -221,12 +221,12 @@ describe("0009_repair_openapi_oauth_cutover_residue", () => {
       "org-client-secret",
       "org-1",
       "openapi",
-      "dealcloud_api",
+      "example_api",
       "org-1",
       "oauth2:oauth2:client-secret",
       "secret",
       null,
-      "dealcloud-client-secret-jd",
+      "example-client-secret-jd",
       null,
       now,
       now,
@@ -235,27 +235,27 @@ describe("0009_repair_openapi_oauth_cutover_residue", () => {
       "org-connection",
       "org-1",
       "openapi",
-      "dealcloud_api",
+      "example_api",
       "org-1",
       "oauth2:oauth2:connection",
       "connection",
       null,
       null,
-      "openapi-oauth2-app-dealcloud_api",
+      "openapi-oauth2-app-example_api",
       now,
       now,
     );
     insertBinding.run(
       "jd-connection",
       "user-org:user-jd:org-1",
       "openapi",
-      "dealcloud_api",
+      "example_api",
       "org-1",
       "oauth2:oauth2:connection",
       "connection",
       null,
       null,
-      "openapi-oauth2-app-dealcloud_api",
+      "openapi-oauth2-app-example_api",
       now,
       now,
     );
@@ -271,49 +271,49 @@ describe("0009_repair_openapi_oauth_cutover_residue", () => {
       .prepare(
         "SELECT scope_id, slot_key, kind, secret_id, connection_id FROM `credential_binding` WHERE source_id = ? ORDER BY scope_id, slot_key",
       )
-      .all("dealcloud_api");
+      .all("example_api");
     expect(bindings).toEqual([
       {
         scope_id: "org-1",
         slot_key: "oauth2:oauth2:client-id",
         kind: "secret",
-        secret_id: "dealcloud-client-id",
+        secret_id: "example-client-id",
         connection_id: null,
       },
       {
         scope_id: "org-1",
         slot_key: "oauth2:oauth2:client-secret",
         kind: "secret",
-        secret_id: "dealcloud-client-secret",
+        secret_id: "example-client-secret",
         connection_id: null,
       },
       {
         scope_id: "org-1",
         slot_key: "oauth2:oauth2:connection",
         kind: "connection",
         secret_id: null,
-        connection_id: "openapi-oauth2-app-dealcloud_api",
+        connection_id: "openapi-oauth2-app-example_api",
       },
       {
         scope_id: "user-org:user-jd:org-1",
         slot_key: "oauth2:oauth2:client-id",
         kind: "secret",
-        secret_id: "dealcloud-client-id-jd",
+        secret_id: "example-client-id-jd",
         connection_id: null,
       },
       {
         scope_id: "user-org:user-jd:org-1",
         slot_key: "oauth2:oauth2:client-secret",
         kind: "secret",
-        secret_id: "dealcloud-client-secret-jd",
+        secret_id: "example-client-secret-jd",
         connection_id: null,
       },
       {
         scope_id: "user-org:user-jd:org-1",
         slot_key: "oauth2:oauth2:connection",
         kind: "connection",
         secret_id: null,
-        connection_id: "openapi-oauth2-app-dealcloud_api",
+        connection_id: "openapi-oauth2-app-example_api",
       },
     ]);
   });

packages/core/execution/src/description.ts

@@ -48,6 +48,7 @@ const formatDescription = (sources: readonly Source[]): string => {
     "- `tools.search()` returns paginated, ranked matches: `{ items, total, hasMore, nextOffset }`. Best-first. Use short intent phrases like `github issues`, `repo details`, or `create calendar event`.",
     '- When you already know the namespace, narrow with `tools.search({ namespace: "github", query: "issues" })`.',
     "- `tools.executor.sources.list()` returns the same paged shape: `{ items: [{ id, toolCount, ... }], total, hasMore, nextOffset }`.",
+    "- Tool calls return a value union: `{ ok: true, data }` for success or `{ ok: false, error: { code, message, status?, details?, retryable? } }` for expected tool/domain failures. Branch on `result.ok`.",
     "- If `hasMore` is true and you didn't find what you need, fetch the next page: `tools.search({ query, offset: nextOffset, limit })`. Same `offset` parameter on `tools.executor.sources.list({ offset, limit })`.",
     "- Always use the namespace prefix when calling tools: `tools.<namespace>.<tool>(args)`. Example: `tools.home_assistant_rest_api.states.getState(...)` — not `tools.states.getState(...)`.",
     "- The `tools` object is a lazy proxy — `Object.keys(tools)` won't work. Use `tools.search()` or `tools.executor.sources.list()` instead.",

packages/core/execution/src/tool-invoker.leak.test.ts

@@ -12,10 +12,10 @@ const EmptyInputSchema = Schema.toStandardSchemaV1(
 
 const acceptAll = () => Effect.succeed(ElicitationResponse.make({ action: "accept" }));
 
-// Plugin-internal tagged error whose `cause` carries sensitive internal
-// context. The dispatcher must route this through the opaque-generic
-// path so none of that context reaches the sandbox via Error.message.
-class FakeOpenApiInvocationError extends Data.TaggedError("OpenApiInvocationError")<{
+// Plugin-internal tagged error whose `cause` carries internal diagnostics.
+// The dispatcher must route this through the opaque-generic path so none of
+// that context reaches the sandbox via Error.message.
+class FakePluginInvocationError extends Data.TaggedError("PluginInvocationError")<{
   readonly message: string;
   readonly cause: unknown;
 }> {}
@@ -35,18 +35,17 @@ const leakyPlugin = definePlugin(() => ({
           inputSchema: EmptyInputSchema,
           handler: () =>
             Effect.fail(
-              new FakeOpenApiInvocationError({
-                message: "HTTP request failed",
+              new FakePluginInvocationError({
+                message: "Upstream request failed",
                 cause: {
-                  _tag: "HttpClientError",
+                  _tag: "InternalTransportError",
                   request: {
                     method: "GET",
-                    url: "https://internal.dealcloud/v1/entities?accessToken=SECRET_TOKEN_xyz",
-                    headers: { Authorization: "Bearer SECRET_TOKEN_xyz" },
+                    url: "https://internal.service.local/v1/resources?trace=trace-123",
+                    headers: { "x-internal-routing": "private-cluster" },
                   },
-                  stack:
-                    "Error: ECONNREFUSED\n    at /home/svc/executor/packages/plugins/openapi/...:142:11",
-                  dbConnString: "postgres://app:p@ssw0rd@10.0.0.5:5432/executor",
+                  stack: "Error: connect failed\n    at plugin-transport.ts:42:11",
+                  note: "internal diagnostic detail",
                 },
               }),
             ),
@@ -87,11 +86,11 @@ describe("internal-error leak audit (opaque defects)", () => {
       // Must be the canonical opaque shape: "Internal tool error [<hex>]"
       expect(msg).toMatch(/^Internal tool error \[[0-9a-f]{8}\]$/);
       // Crucially, no internal context leaks
-      expect(msg).not.toContain("SECRET_TOKEN_xyz");
-      expect(msg).not.toContain("p@ssw0rd");
-      expect(msg).not.toContain("packages/plugins");
-      expect(msg).not.toContain("HttpClientError");
-      expect(msg).not.toContain("HTTP request failed");
+      expect(msg).not.toContain("trace-123");
+      expect(msg).not.toContain("private-cluster");
+      expect(msg).not.toContain("internal.service.local");
+      expect(msg).not.toContain("InternalTransportError");
+      expect(msg).not.toContain("Upstream request failed");
     }),
   );