@fabric-harness/sdk 2.1.1 → 2.1.2

package/connector-spec/channel.md

@@ -0,0 +1,61 @@
+<!-- Canonical Fabric Harness channel connector contract. Shipped with @fabric-harness/sdk. -->
+
+# Fabric Harness Channel Connector Spec
+
+A channel turns an authenticated provider event into a durable dispatch to a persistent agent. Produce a TypeScript module under `.fabricharness/channels/<provider>.ts` that exports a `Channel` created with `defineChannel()`.
+
+## Required shape
+
+```ts
+import { conversationKey, defineChannel, parseConversationKey } from '@fabric-harness/sdk';
+
+export const channel = defineChannel({
+  name: '<provider>',
+  routes: [{
+    method: 'POST',
+    path: '/events',
+    async handler(request, context) {
+      // 1. Read the exact body bytes once.
+      // 2. Verify the provider signature and timestamp before parsing/dispatching.
+      // 3. Normalize the event and ignore provider-owned bot messages.
+      // 4. Dispatch with stable instance, dedupe, tenant, and actor identity.
+      const receipt = await context.dispatch('<agent>', {
+        instanceId: conversationKey('<provider>', 'v1', '<conversation-id>'),
+        message: { kind: 'signal', signal: '<provider>.event', data: {} },
+        dedupeKey: '<provider-event-id>',
+        tenantId: '<workspace-or-account-id>',
+        actor: { id: '<provider-user-id>', type: 'user' },
+      });
+      return Response.json(receipt, { status: 202 });
+    },
+  }],
+  conversationKey(ref) {
+    const value = ref as { id: string };
+    return conversationKey('<provider>', 'v1', value.id);
+  },
+  parseConversationKey(id) {
+    return { id: parseConversationKey(id).segments[0] };
+  },
+});
+```
+
+## Security requirements
+
+1. Fail closed when the signing secret, public key, OAuth configuration, or expected bearer token is absent.
+2. Verify the exact request bytes. Use `readJsonBody()` when an HMAC provider requires both raw bytes and parsed JSON.
+3. Enforce the provider timestamp window or challenge protocol to prevent replay attacks.
+4. Use constant-time signature verification. Prefer Fabric's `verifyHmacSha256()` when the provider uses HMAC-SHA256.
+5. Use the provider event/delivery ID as `dedupeKey`. Do not invent a random value.
+6. Derive `instanceId` from the stable thread, conversation, ticket, order, or resource identifier.
+7. Propagate organization/account identity as `tenantId` and the initiating user as `actor`.
+8. Ignore messages/actions created by the integration itself to prevent response loops.
+9. Keep credentials in environment variables or a secret manager. Never put secrets in dispatch input, model context, errors, logs, or session artifacts.
+10. Apply a `CapabilityPolicy` to outbound write tools. Require approval for destructive, financial, public-posting, or customer-data mutations.
+
+## Outbound tools
+
+Expose provider writes through `defineTool()` with `effect: 'write'`. Bind tools to the addressed conversation/resource at persistent-agent initialization, and restrict OAuth scopes to the exact actions required. Include idempotency keys when the provider supports them.
+
+## Tests
+
+Add unit tests for valid and invalid signatures, stale timestamps, duplicate event IDs, bot-loop suppression, tenant/actor propagation, stable conversation keys, body-size limits, and outbound policy classification. Add an opt-in live test for provider webhook and permission changes.

package/connector-spec/tooling.md

@@ -0,0 +1,14 @@
+# Fabric Harness Tooling Connector Spec
+
+A tooling connector observes Fabric events, traces, metrics, or eval results without changing agent behavior. Produce a project-local module that uses public Fabric event, telemetry, or eval APIs.
+
+## Requirements
+
+1. Initialize the vendor SDK before Fabric runtime construction and dispose/flush it during graceful shutdown.
+2. Integrate from `onEvent`, `TelemetryExporter`, `createOpenTelemetryObserver()`, `runEvalSuite()`, or another documented public boundary. Do not monkey-patch model providers or session internals.
+3. Keep API keys in environment variables or a secret manager. Never add them to event attributes, errors, model context, or artifacts.
+4. Disable prompt, output, reasoning, tool argument/result, attachment, and customer-content capture by default. Require an explicit redaction/retention policy to enable any of it.
+5. Use stable low-cardinality job, agent, model, environment, and outcome attributes. Do not use session, submission, tenant, or user IDs as metric dimensions.
+6. Bound queues, retries, payload size, and shutdown time so telemetry failure cannot block agent execution indefinitely.
+7. Keep evaluation datasets and grading outputs separate from production session storage and apply access/retention controls.
+8. Add tests for redaction, exporter failure, flush behavior, disabled-content defaults, and correlation fields.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabric-harness/sdk",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Headless TypeScript framework for building durable, deployable autonomous agents — core SDK.",
   "license": "Apache-2.0",
   "author": "Fabric",