@cursor/july 0.1.25 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/src/channels/github/github-channel.ts

@@ -10,6 +10,7 @@ import {
 import { isDevMode } from "../../internal/dev-mode.js";
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   ChannelDefinition,
   ChannelEventHandlers,
@@ -68,7 +69,7 @@ import type {
  */
 type GitHubParsedContext = Omit<
   GitHubEventContext,
-  "github" | "thread" | "host"
+  "github" | "thread" | "host" | "artifacts"
 >;
 
 const DEFAULT_PULL_REQUEST_ACTIONS: ReadonlySet<string> = new Set([
@@ -737,6 +738,7 @@ async function handlePullRequest(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch =
     input.options.onPullRequest === undefined
@@ -828,6 +830,7 @@ async function handleIssueComment(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
 
   const dispatch =
@@ -918,6 +921,7 @@ async function handleReviewComment(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
 
   const dispatch =
@@ -994,6 +998,7 @@ async function handleIssue(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onIssue(ctx, parsed.issue);
   if (dispatch === null) {
@@ -1053,6 +1058,7 @@ async function handleCheckSuite(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.checkSuite
     );
@@ -1079,6 +1085,7 @@ async function handleCheckSuite(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onCheckSuite(ctx, parsed.checkSuite);
   if (dispatch === null) {
@@ -1143,6 +1150,7 @@ async function handleCheckRun(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.checkRun
     );
@@ -1169,6 +1177,7 @@ async function handleCheckRun(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onCheckRun(ctx, parsed.checkRun);
   if (dispatch === null) {
@@ -1229,6 +1238,7 @@ async function handleWorkflowRun(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.workflowRun
     );
@@ -1255,6 +1265,7 @@ async function handleWorkflowRun(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onWorkflowRun(ctx, parsed.workflowRun);
   if (dispatch === null) {
@@ -1326,6 +1337,7 @@ async function handleStatus(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onStatus(ctx, parsed.status);
   if (dispatch === null) {
@@ -1399,6 +1411,7 @@ async function handleGenericEvent(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onEvent(ctx, parsed.event);
   if (dispatch === null) {
@@ -2224,11 +2237,12 @@ function escapeRegExp(value: string): string {
  */
 function enrichEventContext(input: {
   bindingConfig: GitHubBindingConfig;
-  ctx: Omit<GitHubEventContext, "github" | "thread" | "host"> &
+  ctx: Omit<GitHubEventContext, "github" | "thread" | "host" | "artifacts"> &
     Partial<Pick<GitHubEventContext, "github" | "thread">>;
   bindingState: GitHubBindingState;
   installationId?: number;
   host: HostContext;
+  artifacts: ArtifactsApi;
 }): GitHubEventContext {
   const { github, thread } = buildGitHubBinding({
     config: input.bindingConfig,
@@ -2242,6 +2256,7 @@ function enrichEventContext(input: {
     github,
     thread,
     host: input.host,
+    artifacts: input.artifacts,
   };
 }
 
@@ -2254,6 +2269,7 @@ function enrichCiContext(input: {
   ctx: GitHubParsedContext;
   installationId?: number;
   host: HostContext;
+  artifacts: ArtifactsApi;
 }): GitHubEventContext {
   const binding = githubBindingStateForEvent({
     kind: input.ctx.conversation.kind,
@@ -2269,6 +2285,7 @@ function enrichCiContext(input: {
     bindingState: binding,
     installationId: input.installationId,
     host: input.host,
+    artifacts: input.artifacts,
   });
 }
 

package/src/channels/github/github.test.ts

@@ -2,6 +2,7 @@ import { createHmac } from "node:crypto";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { scmMetadataToGitHubPayload } from "../../internal/cursor-event-relay.js";
 import type {
+  ArtifactsApi,
   ChannelHandlerArgs,
   ChannelRouteHandler,
   ChannelSession,
@@ -334,6 +335,47 @@ describe("githubChannel", () => {
     );
   });
 
+  it("hands the artifacts facade to inbound hooks (ctx.artifacts)", async () => {
+    const tags: Array<Parameters<ArtifactsApi["tag"]>[0]> = [];
+    const artifacts: ArtifactsApi = {
+      tag: async (input) => {
+        tags.push(input);
+        return {
+          id: `art_${tags.length}`,
+          kind: input.kind ?? "artifact",
+          key: input.key,
+          data: input.data,
+          source: "host",
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        };
+      },
+      list: async () => [],
+    };
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        onPullRequest: async (ctx, pr) => {
+          await ctx.artifacts.tag({
+            key: `pr:${pr.number}`,
+            data: { headSha: pr.headSha },
+          });
+          return null;
+        },
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload()),
+      }),
+      { ...handlerArgs(send), artifacts }
+    );
+    await expect(response.json()).resolves.toMatchObject({ ok: true });
+    expect(tags).toEqual([{ key: "pr:42", data: { headSha: "abc123" } }]);
+  });
+
   it("dispatches @mention issue comments via the default onComment gate", async () => {
     const send = vi.fn<SendMessageFn>(async () => fakeSession());
     const response = await routeHandler(

package/src/channels/github/types.ts

@@ -1,5 +1,6 @@
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   AuthPolicy,
   ChannelEventHandlers,
@@ -306,6 +307,11 @@ export interface GitHubEventContext {
   thread: GitHubThread;
   /** Shared host services (MCP / host GitHub / Slack). Same as tool `ctx.host`. */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — the hook runs before any session is
+   * admitted; pass `sessionId` in `tag` input to attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**

package/src/channels/slack/api.ts

@@ -3,7 +3,7 @@
  */
 
 import { ErrorCode, type WebAPIPlatformError, WebClient } from "@slack/web-api";
-import type { HostContext } from "../../types.js";
+import type { ArtifactsApi, HostContext } from "../../types.js";
 import {
   SLACK_DEFAULT_LOADING_MESSAGES,
   SLACK_LOADING_MESSAGE_MAX_LEN,
@@ -540,6 +540,7 @@ export function buildSlackBinding(args: {
   threadTs: string;
   teamId?: string;
   host: HostContext;
+  artifacts: ArtifactsApi;
   onThreadTsChanged?: (threadTs: string) => void;
   log?: SlackLog;
 }): SlackBinding {
@@ -643,5 +644,6 @@ export function buildSlackBinding(args: {
       ...(args.teamId === undefined ? {} : { teamId: args.teamId }),
     },
     host: args.host,
+    artifacts: args.artifacts,
   };
 }

package/src/channels/slack/block-actions.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import type { ChannelSession, SendMessageFn } from "../../types.js";
+import type {
+  ArtifactsApi,
+  ChannelSession,
+  SendMessageFn,
+} from "../../types.js";
 import { blockActionAuth } from "./auth.js";
 import {
   mrkdwnSections,
@@ -57,6 +61,15 @@ function createSendRecorder(): {
   return { send, calls };
 }
 
+function testArtifacts(): ArtifactsApi {
+  return {
+    tag: async () => {
+      throw new Error("artifacts not configured in test");
+    },
+    list: async () => [],
+  };
+}
+
 function testHost() {
   return {
     mcp: {
@@ -171,6 +184,7 @@ describe("dispatchBlockAction", () => {
       },
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host: testHost(),
       log: createSlackLogger(() => undefined),
     });
@@ -204,6 +218,7 @@ describe("dispatchBlockAction", () => {
       handler: () => ({ auth: testAuth }),
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host: testHost(),
       log: createSlackLogger(() => undefined),
     });
@@ -217,6 +232,7 @@ describe("dispatchBlockAction", () => {
       handler: () => null,
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host: testHost(),
       log: createSlackLogger(() => undefined),
     });
@@ -232,6 +248,7 @@ describe("dispatchBlockAction", () => {
         handler: () => ({ auth: testAuth }),
         send,
         credentials: undefined,
+        artifacts: testArtifacts(),
         host: testHost(),
         log: createSlackLogger(() => undefined),
       }

package/src/channels/slack/cursor-account.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import type { HostContext, SendMessageFn } from "../../types.js";
+import type { ArtifactsApi, HostContext, SendMessageFn } from "../../types.js";
 import {
   type CursorSlackEnvelope,
   createPendingSlackApiTransport,
@@ -33,6 +33,15 @@ function fakeHost(): HostContext {
   return {} as HostContext;
 }
 
+function testArtifacts(): ArtifactsApi {
+  return {
+    tag: async () => {
+      throw new Error("artifacts not configured in test");
+    },
+    list: async () => [],
+  };
+}
+
 describe("slackChannel({ cursorAccount: true })", () => {
   it("registers a runtime with a pending transport and no Socket Mode routes", () => {
     const definition = slackChannel({ cursorAccount: true });
@@ -167,6 +176,7 @@ describe("dispatchCursorSlackEnvelope", () => {
       envelope: envelope(),
       send,
       host: fakeHost(),
+      artifacts: testArtifacts(),
     });
 
     expect(sent).toHaveLength(1);
@@ -184,6 +194,39 @@ describe("dispatchCursorSlackEnvelope", () => {
     expect(methods).toContain("assistant.threads.setStatus");
   });
 
+  it("hands the artifacts facade to the mention handler binding", async () => {
+    const tags: Array<Parameters<ArtifactsApi["tag"]>[0]> = [];
+    const artifacts: ArtifactsApi = {
+      tag: async (input) => {
+        tags.push(input);
+        return {
+          id: `art_${tags.length}`,
+          kind: input.kind ?? "artifact",
+          key: input.key,
+          data: input.data,
+          source: "host",
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        };
+      },
+      list: async () => [],
+    };
+    const { runtime, send } = setup({
+      onAppMention: async (ctx) => {
+        await ctx.artifacts.tag({ key: "from-relay", data: "r" });
+        return null;
+      },
+    });
+    await dispatchCursorSlackEnvelope({
+      runtime,
+      envelope: envelope(),
+      send,
+      host: fakeHost(),
+      artifacts,
+    });
+    expect(tags).toEqual([{ key: "from-relay", data: "r" }]);
+  });
+
   it("routes DMs to the direct-message handler", async () => {
     const kinds: string[] = [];
     const { runtime, send } = setup({
@@ -205,12 +248,14 @@ describe("dispatchCursorSlackEnvelope", () => {
       }),
       send,
       host: fakeHost(),
+      artifacts: testArtifacts(),
     });
     await dispatchCursorSlackEnvelope({
       runtime,
       envelope: envelope({ eventId: "Ev3" }),
       send,
       host: fakeHost(),
+      artifacts: testArtifacts(),
     });
     expect(kinds).toEqual(["dm", "mention"]);
   });
@@ -222,12 +267,14 @@ describe("dispatchCursorSlackEnvelope", () => {
       envelope: envelope({ eventId: "EvDup" }),
       send,
       host: fakeHost(),
+      artifacts: testArtifacts(),
     });
     await dispatchCursorSlackEnvelope({
       runtime,
       envelope: envelope({ eventId: "EvDup" }),
       send,
       host: fakeHost(),
+      artifacts: testArtifacts(),
     });
     expect(sent).toHaveLength(1);
   });
@@ -245,6 +292,7 @@ describe("dispatchCursorSlackEnvelope", () => {
       }),
       send,
       host: fakeHost(),
+      artifacts: testArtifacts(),
     });
     expect(sent).toHaveLength(1);
     expect(sent[0].options.continuationToken).toBe("C0100:111.222");

package/src/channels/slack/cursor-account.ts

@@ -12,7 +12,7 @@
  * dispatches relayed envelopes through the pack's normal inbound path.
  */
 
-import type { HostContext, SendMessageFn } from "../../types.js";
+import type { ArtifactsApi, HostContext, SendMessageFn } from "../../types.js";
 import { dispatchInboundMessage } from "./dispatch.js";
 import type { EventIdDedupe } from "./event-id-dedupe.js";
 import { slackTextToMarkdown } from "./inbound.js";
@@ -114,6 +114,7 @@ export async function dispatchCursorSlackEnvelope(args: {
   envelope: CursorSlackEnvelope;
   send: SendMessageFn;
   host: HostContext;
+  artifacts: ArtifactsApi;
   hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
   isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
   getContinuationLastBotMessageTs?: (
@@ -167,6 +168,7 @@ export async function dispatchCursorSlackEnvelope(args: {
     send: args.send,
     credentials: runtime.credentials,
     host: args.host,
+    artifacts: args.artifacts,
     log,
     evalCommandsEnabled: runtime.options.evalCommands !== false,
     cursorAgentName: envelope.agentName,

package/src/channels/slack/dispatch.test.ts

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type {
+  ArtifactsApi,
   ChannelSession,
   HostContext,
   SendMessageFn,
@@ -67,6 +68,15 @@ function acceptHandler(): SlackMessageHandler {
   return async () => ({ auth: testAuth });
 }
 
+function testArtifacts(): ArtifactsApi {
+  return {
+    tag: async () => {
+      throw new Error("artifacts not configured in test");
+    },
+    list: async () => [],
+  };
+}
+
 function testHost(options?: {
   nudgeRoot?: string;
   askRoot?: string;
@@ -170,6 +180,7 @@ describe("dispatchInboundFromEventBody", () => {
       onAppMention: acceptHandler(),
       onDirectMessage: async () => null,
       credentials: undefined,
+      artifacts: testArtifacts(),
       eventIds: createEventIdDedupe(),
       host: testHost(),
       log: createSlackLogger((line) => lines.push(line)),
@@ -196,6 +207,7 @@ describe("dispatchInboundFromEventBody", () => {
       onAppMention: acceptHandler(),
       onDirectMessage: async () => null,
       credentials: undefined as undefined,
+      artifacts: testArtifacts(),
       host: testHost(),
       eventIds,
       log: createSlackLogger(() => undefined),
@@ -219,6 +231,7 @@ describe("dispatchInboundFromEventBody", () => {
       onAppMention: async () => null,
       onDirectMessage: async () => null,
       credentials: undefined,
+      artifacts: testArtifacts(),
       eventIds: createEventIdDedupe(),
       host: testHost(),
     });
@@ -239,6 +252,7 @@ describe("dispatchInboundFromEventBody", () => {
       },
       onDirectMessage: async () => null,
       credentials: undefined,
+      artifacts: testArtifacts(),
       eventIds: createEventIdDedupe(),
       host: testHost(),
       log: createSlackLogger(() => undefined),
@@ -273,6 +287,7 @@ describe("dispatchInboundFromEventBody", () => {
         onAppMention: async () => null,
         onDirectMessage: acceptHandler(),
         credentials: undefined,
+        artifacts: testArtifacts(),
         eventIds: createEventIdDedupe(),
         host: testHost(),
       }
@@ -292,6 +307,7 @@ describe("dispatchInboundFromEventBody", () => {
           onAppMention: async () => null,
           onDirectMessage: async () => null,
           credentials: undefined,
+          artifacts: testArtifacts(),
           eventIds: createEventIdDedupe(),
           host: testHost(),
         }
@@ -324,6 +340,7 @@ describe("dispatchInboundFromEventBody", () => {
       }),
       onDirectMessage: async () => null,
       credentials: undefined,
+      artifacts: testArtifacts(),
       eventIds: createEventIdDedupe(),
       host: testHost(),
     });
@@ -357,6 +374,7 @@ describe("engagement routing", () => {
       onAppMention: acceptHandler(),
       onDirectMessage: async () => null,
       credentials: undefined,
+      artifacts: testArtifacts(),
       eventIds: createEventIdDedupe(),
       host: testHost(),
       log: createSlackLogger(() => undefined),
@@ -379,6 +397,7 @@ describe("engagement routing", () => {
       onAppMention: acceptHandler(),
       onDirectMessage: async () => null,
       credentials: undefined as undefined,
+      artifacts: testArtifacts(),
       eventIds: createEventIdDedupe(),
       host: testHost(),
       log: createSlackLogger(() => undefined),
@@ -433,6 +452,7 @@ describe("engagement routing", () => {
         onAppMention: acceptHandler(),
         onDirectMessage: async () => null,
         credentials: undefined,
+        artifacts: testArtifacts(),
         eventIds: createEventIdDedupe(),
         host: testHost(),
         log: createSlackLogger(() => undefined),
@@ -443,6 +463,56 @@ describe("engagement routing", () => {
 });
 
 describe("dispatchInboundMessage", () => {
+  it("hands the artifacts facade to the handler binding (ctx.artifacts)", async () => {
+    const tags: Array<Parameters<ArtifactsApi["tag"]>[0]> = [];
+    const artifacts: ArtifactsApi = {
+      tag: async (input) => {
+        tags.push(input);
+        return {
+          id: `art_${tags.length}`,
+          kind: input.kind ?? "artifact",
+          key: input.key,
+          data: input.data,
+          source: "host",
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        };
+      },
+      list: async () => [],
+    };
+    const { send, calls } = createSendRecorder();
+    await dispatchInboundMessage({
+      kind: "channel_post",
+      message: {
+        text: "alert fired",
+        body: "alert fired",
+        markdown: "alert fired",
+        ts: "2.0",
+        threadTs: "1.0",
+        channelId: "C1",
+        teamId: "T1",
+        author: { userId: "U1", isBot: false },
+      },
+      handler: async (ctx) => {
+        await ctx.artifacts.tag({
+          kind: "alert_watch",
+          key: `${ctx.slack.channelId}:${ctx.slack.threadTs}`,
+          data: { status: "watching" },
+        });
+        return { auth: testAuth };
+      },
+      send,
+      credentials: undefined,
+      artifacts,
+      host: testHost(),
+      log: createSlackLogger(() => undefined),
+    });
+    expect(tags).toEqual([
+      { kind: "alert_watch", key: "C1:1.0", data: { status: "watching" } },
+    ]);
+    expect(calls).toHaveLength(1);
+  });
+
   it("logs delivery failure when send throws", async () => {
     const lines: string[] = [];
     await dispatchInboundMessage({
@@ -462,6 +532,7 @@ describe("dispatchInboundMessage", () => {
         throw new Error("engine down");
       },
       credentials: undefined,
+      artifacts: testArtifacts(),
       host: testHost(),
       log: createSlackLogger((line) => lines.push(line)),
     });
@@ -500,6 +571,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: { botToken: "xoxb-test" },
+      artifacts: testArtifacts(),
       host,
       hasContinuationSession: async () => true,
       log: createSlackLogger((line) => lines.push(line)),
@@ -538,6 +610,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: { botToken: "xoxb-test" },
+      artifacts: testArtifacts(),
       host: testHost({
         nudgeRoot: join(root, "nudges"),
         askRoot: join(root, "asks"),
@@ -572,6 +645,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: { botToken: "xoxb-test" },
+      artifacts: testArtifacts(),
       host: testHost({
         evals: {
           list: async () => {
@@ -613,6 +687,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host: testHost({
         evals: {
           list: async () => {
@@ -657,6 +732,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host,
     });
     await dispatchInboundMessage({
@@ -665,6 +741,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host,
     });
     expect(calls).toHaveLength(1);
@@ -705,6 +782,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: { botToken: "xoxb-test" },
+      artifacts: testArtifacts(),
       host: testHost(),
       log: createSlackLogger((line) => lines.push(line)),
     });
@@ -749,6 +827,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: { botToken: "xoxb-test" },
+      artifacts: testArtifacts(),
       host: testHost(),
       hasContinuationSession: async () => true,
       // Agent watermark (not Datadog's parent) — human reply at 2.0 is in delta.
@@ -787,6 +866,7 @@ describe("dispatchInboundMessage", () => {
       handler: acceptHandler(),
       send,
       credentials: undefined,
+      artifacts: testArtifacts(),
       host,
       log: createSlackLogger(() => undefined),
     });

package/src/channels/slack/dispatch.ts

@@ -2,7 +2,12 @@
  * Shared inbound dispatch for Slack Events API bodies and Socket Mode.
  */
 
-import type { HostContext, JsonValue, SendMessageFn } from "../../types.js";
+import type {
+  ArtifactsApi,
+  HostContext,
+  JsonValue,
+  SendMessageFn,
+} from "../../types.js";
 import { buildSlackBinding, slackContinuationKey } from "./api.js";
 import { firstLineTitle, maybeSetThreadTitle } from "./assistant.js";
 import type { SlackBotMentionGate } from "./bot-mentions.js";
@@ -65,6 +70,8 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
   credentials: SlackCredentials | undefined;
   eventIds: EventIdDedupe;
   host: HostContext;
+  /** Unbound artifacts facade handed to handler bindings (`ctx.artifacts`). */
+  artifacts: ArtifactsApi;
   log?: SlackLog;
   /** Dispatch on `app_mention`. Defaults to `true`. */
   mentionsEnabled?: boolean;
@@ -110,6 +117,7 @@ export async function dispatchInboundMessage(args: {
   send: SendMessageFn;
   credentials: SlackCredentials | undefined;
   host: HostContext;
+  artifacts: ArtifactsApi;
   hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
   isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
   getContinuationLastBotMessageTs?: (
@@ -132,6 +140,7 @@ export async function dispatchInboundMessage(args: {
     channelId: message.channelId,
     threadTs: message.threadTs,
     host: args.host,
+    artifacts: args.artifacts,
     log,
     ...(message.teamId === undefined ? {} : { teamId: message.teamId }),
   });
@@ -450,6 +459,7 @@ export function dispatchInboundFromEventBody(
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,
+        artifacts: deps.artifacts,
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
@@ -490,6 +500,7 @@ export function dispatchInboundFromEventBody(
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,
+        artifacts: deps.artifacts,
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,

package/src/channels/slack/interactive.ts

@@ -9,6 +9,7 @@
 
 import type {
   ApprovalDecision,
+  ArtifactsApi,
   AuthContext,
   ChannelSession,
   HostContext,
@@ -275,6 +276,7 @@ export interface SlackBlockActionDispatchDeps extends SlackContinuationProbes {
   send: SendMessageFn;
   credentials: SlackCredentials | undefined;
   host: HostContext;
+  artifacts: ArtifactsApi;
   log?: SlackLog;
 }
 
@@ -347,6 +349,7 @@ export async function dispatchBlockAction(
     send: deps.send,
     credentials: deps.credentials,
     host: deps.host,
+    artifacts: deps.artifacts,
     log,
     // Click text is synthetic — never treat it as a stop/eval directive.
     evalCommandsEnabled: false,

package/src/channels/slack/slack-channel.ts

@@ -9,6 +9,7 @@
 
 import { allowAll, defineChannel } from "../../channels.js";
 import type {
+  ArtifactsApi,
   ChannelDefinition,
   ChannelEventHandlers,
   HostContext,
@@ -215,6 +216,7 @@ export function slackChannel<const Name extends string = string>(
     send: SendMessageFn;
     waitUntil: (promise: Promise<unknown>) => void;
     host: HostContext;
+    artifacts: ArtifactsApi;
     hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
     isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
     getContinuationLastBotMessageTs?: (
@@ -230,6 +232,7 @@ export function slackChannel<const Name extends string = string>(
       credentials,
       eventIds,
       host: args.host,
+      artifacts: args.artifacts,
       log: getLog(),
       mentionsEnabled,
       directMessagesEnabled,
@@ -410,6 +413,7 @@ export function slackChannel<const Name extends string = string>(
                   send: args.send,
                   credentials,
                   host: args.host,
+                  artifacts: args.artifacts,
                   log: getLog(),
                   evalCommandsEnabled,
                   ...(args.hasContinuationSession === undefined
@@ -454,6 +458,7 @@ export function slackChannel<const Name extends string = string>(
               send: args.send,
               waitUntil: args.waitUntil,
               host: args.host,
+              artifacts: args.artifacts,
               ...(args.hasContinuationSession === undefined
                 ? {}
                 : { hasContinuationSession: args.hasContinuationSession }),
@@ -496,6 +501,7 @@ export function slackChannel<const Name extends string = string>(
             send: args.send,
             credentials,
             host: args.host,
+            artifacts: args.artifacts,
             log: getLog(),
             hasContinuationSession: args.hasContinuationSession,
             isContinuationBusy: args.isContinuationBusy,

package/src/channels/slack/types.ts

@@ -4,6 +4,7 @@
 
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   ChannelEventHandlers,
   HostContext,
@@ -189,6 +190,11 @@ export interface SlackBinding {
   };
   /** Shared host services (MCP / GitHub / Slack). */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — the handler runs before any session is
+   * admitted; pass `sessionId` in `tag` input to attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export type SlackMessageHandler = (

package/src/internal/reminder-runner.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { defineStorage } from "../storage.js";
-import type { JsonValue } from "../types.js";
+import type { ArtifactRecord, ArtifactsApi, JsonValue } from "../types.js";
 import { ReminderRunner, ReminderValidationError } from "./reminder-runner.js";
 import type { SessionEngine } from "./session-engine.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
@@ -25,9 +25,28 @@ function mockEngine(
     getEventStream: () => ({}) as never,
     waitForCompletion: async () => ({ status: "completed" as const }),
   }));
+  const artifactRows: ArtifactRecord[] = [];
+  const artifacts: ArtifactsApi = {
+    tag: async (input) => {
+      const record: ArtifactRecord = {
+        id: `art_${artifactRows.length + 1}`,
+        kind: input.kind ?? "artifact",
+        key: input.key,
+        data: input.data,
+        sessionId: input.sessionId,
+        source: "host",
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      artifactRows.push(record);
+      return record;
+    },
+    list: async () => [...artifactRows],
+  };
   return {
     stateRoot,
     storage,
+    artifacts,
     host: {
       mcp: {} as never,
       github: {} as never,
@@ -145,6 +164,29 @@ describe("ReminderRunner", () => {
     expect(message).toContain("check ci");
   });
 
+  it("run handlers get the unbound artifacts facade", async () => {
+    dir = await mkdtemp(join(tmpdir(), "rem-runner-"));
+    const engine = mockEngine(dir);
+    const runner = new ReminderRunner(engine);
+    await runner.start();
+
+    const created = await runner.create({
+      purpose: "alert_watch",
+      channelId: "drive",
+      continuationToken: "tok",
+      every: "1m",
+      run: async ({ artifacts }) => {
+        await artifacts.tag({ key: "from-reminder", data: "r" });
+        return { action: "skip" };
+      },
+    });
+    await runner.dispatch(created.id);
+
+    const rows = await engine.artifacts.list();
+    expect(rows.map((row) => row.key)).toEqual(["from-reminder"]);
+    expect(rows[0]?.sessionId).toBeUndefined();
+  });
+
   it("disarms prompt reminders when the bound session is gone", async () => {
     dir = await mkdtemp(join(tmpdir(), "rem-runner-"));
     const engine = mockEngine(dir);

package/src/internal/reminder-runner.ts

@@ -664,6 +664,7 @@ export class ReminderRunner {
       host: this.engine.host,
       mcp: this.engine.host.mcp,
       appAuth: APP_AUTH,
+      artifacts: this.engine.artifacts,
       async followup(args: { message: string }) {
         const auth = await self.resolveFollowupAuth(
           record.channelId,

package/src/internal/schedule-runner.ts

@@ -151,6 +151,7 @@ export class ScheduleRunner {
       },
       appAuth: APP_AUTH,
       host: this.engine.host,
+      artifacts: this.engine.artifacts,
     });
     // Collect ids from receive() calls the handler chose not to await
     // (commonly wrapped in waitUntil); receive resolves at message accept,

package/src/internal/server.artifacts.test.ts

@@ -4,12 +4,13 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { z } from "zod";
 import { defineArtifacts } from "../artifacts.js";
-import { httpChannel } from "../channels.js";
+import { defineChannel, httpChannel } from "../channels.js";
 import { defineTool } from "../tools.js";
 import type {
   AgentProject,
   ArtifactRecord,
   AuthContext,
+  DiscoveredChannel,
   DiscoveredTool,
   ServeOptions,
 } from "../types.js";
@@ -35,7 +36,10 @@ const seedTool = defineTool({
   },
 });
 
-function testProject(rootDir: string): AgentProject {
+function testProject(
+  rootDir: string,
+  options?: { channels?: DiscoveredChannel[] }
+): AgentProject {
   const discovered: DiscoveredTool = {
     name: "seed",
     description: seedTool.description,
@@ -59,7 +63,7 @@ function testProject(rootDir: string): AgentProject {
       seedFiles: [],
     },
     httpChannel: httpChannel(),
-    channels: [],
+    channels: options?.channels ?? [],
     schedules: [],
     hooks: [],
     abs: [],
@@ -87,10 +91,15 @@ afterEach(async () => {
   }
 });
 
-async function startTestServer(options?: Partial<ServeOptions>) {
+async function startTestServer(
+  options?: Partial<ServeOptions>,
+  projectOptions?: { channels?: DiscoveredChannel[] }
+) {
   const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-artroute-"));
   cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
-  const mounts: AgentMount[] = [{ slug: "", project: testProject(stateRoot) }];
+  const mounts: AgentMount[] = [
+    { slug: "", project: testProject(stateRoot, projectOptions) },
+  ];
   const handle = await startServer(mounts, {
     port: 0,
     stateRoot,
@@ -181,6 +190,28 @@ describe("GET /v1/artifacts", () => {
     expect(listed.artifacts).toEqual([]);
   });
 
+  it("channel onStart gets the unbound artifacts facade", async () => {
+    const channel: DiscoveredChannel = {
+      id: "starter",
+      definition: defineChannel({
+        async onStart({ artifacts }) {
+          await artifacts.tag({
+            kind: "report",
+            key: "from-onstart",
+            data: 1,
+          });
+        },
+      }),
+    };
+    const handle = await startTestServer(
+      { dev: true },
+      { channels: [channel] }
+    );
+    const listed = await listArtifacts(handle.url);
+    expect(listed.artifacts.map((a) => a.key)).toEqual(["from-onstart"]);
+    expect(listed.artifacts[0]?.sessionId).toBeUndefined();
+  });
+
   it("requires the bearer token when one is configured", async () => {
     const handle = await startTestServer({ authToken: "sekrit" });
     const denied = await fetch(`${handle.url}/v1/artifacts`);

package/src/internal/server.ts

@@ -494,6 +494,7 @@ export async function startServer(
           interruptContinuation: (continuationToken) =>
             engine.interruptContinuation(channel.id, continuationToken),
           logger,
+          artifacts: engine.artifacts,
         };
         try {
           await definition.onStart(startArgs);
@@ -1778,6 +1779,7 @@ async function startCursorSlackRelay(input: {
         envelope,
         send: args.send,
         host: args.host,
+        artifacts: args.artifacts,
         hasContinuationSession: (continuationToken) =>
           target.runtime.engine.hasContinuationSession(
             target.channelId,

package/src/internal/session-engine.artifacts.test.ts

@@ -3,17 +3,21 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { defineArtifacts } from "../artifacts.js";
-import { httpChannel } from "../channels.js";
+import { defineChannel, httpChannel } from "../channels.js";
 import { defineHook } from "../hooks.js";
+import { defineSchedule } from "../schedules.js";
 import { defineTool } from "../tools.js";
 import type {
   AgentProject,
   ArtifactsDefinition,
+  DiscoveredChannel,
   DiscoveredHook,
+  DiscoveredSchedule,
   DiscoveredTool,
   JsonObject,
   ToolContext,
 } from "../types.js";
+import { ScheduleRunner } from "./schedule-runner.js";
 import type { AgentRunner } from "./sdk-runner.js";
 import { SessionEngine } from "./session-engine.js";
 
@@ -46,6 +50,8 @@ function testProject(options?: {
   artifacts?: ArtifactsDefinition;
   tools?: DiscoveredTool[];
   hooks?: DiscoveredHook[];
+  schedules?: DiscoveredSchedule[];
+  channels?: DiscoveredChannel[];
 }): AgentProject {
   return {
     rootDir: "/tmp/artifacts-fixture",
@@ -62,8 +68,8 @@ function testProject(options?: {
       seedFiles: [],
     },
     httpChannel: httpChannel(),
-    channels: [],
-    schedules: [],
+    channels: options?.channels ?? [],
+    schedules: options?.schedules ?? [],
     hooks: options?.hooks ?? [],
     abs: [],
     artifacts: options?.artifacts,
@@ -198,6 +204,50 @@ describe("session engine artifacts wiring", () => {
     expect(await engine.artifacts.list()).toHaveLength(0);
   });
 
+  it("schedule handlers get the unbound artifacts facade", async () => {
+    const cron = "* * * * *";
+    const schedule: DiscoveredSchedule = {
+      name: "tagger",
+      cron,
+      kind: "run",
+      definition: defineSchedule({
+        cron,
+        async run({ artifacts }) {
+          await artifacts.tag({ key: "from-schedule", data: "s" });
+        },
+      }),
+    };
+    const project = testProject({ schedules: [schedule] });
+    const engine = await makeEngine(project, echoRunner());
+    const runner = new ScheduleRunner(engine, project);
+    await runner.dispatch("tagger");
+
+    const rows = await engine.artifacts.list();
+    expect(rows.map((row) => row.key)).toEqual(["from-schedule"]);
+    expect(rows[0]?.sessionId).toBeUndefined();
+  });
+
+  it("channel receive hooks get the unbound artifacts facade", async () => {
+    const channel: DiscoveredChannel = {
+      id: "handoff",
+      definition: defineChannel({
+        async receive(input, { send, artifacts }) {
+          await artifacts.tag({ key: "from-receive", data: "r" });
+          return send(input.message, { auth: input.auth });
+        },
+      }),
+    };
+    const engine = await makeEngine(
+      testProject({ channels: [channel] }),
+      echoRunner()
+    );
+    await engine.receive("handoff", { message: "hand-off", auth: null });
+
+    const rows = await engine.artifacts.list();
+    expect(rows.map((row) => row.key)).toEqual(["from-receive"]);
+    expect(rows[0]?.sessionId).toBeUndefined();
+  });
+
   it("hook ctx.artifacts is bound to the hook's session", async () => {
     const hook: DiscoveredHook = {
       name: "tagger",

package/src/internal/session-engine.ts

@@ -716,7 +716,10 @@ export class SessionEngine {
         lastCreated = session;
         return session;
       };
-      const returned = await definition.receive(input, { send });
+      const returned = await definition.receive(input, {
+        send,
+        artifacts: this.artifactsApi(),
+      });
       const session = returned ?? lastCreated;
       if (session === undefined) {
         throw new Error(

package/src/types.ts

@@ -1505,6 +1505,12 @@ export interface ChannelStartArgs {
    * should prefer this over `console.*` so CLI/eval hosts can redirect.
    */
   logger: (line: string) => void;
+  /**
+   * Durable artifacts (unbound, same facade as
+   * {@link ChannelHandlerArgs.artifacts}) — for host pipelines the channel
+   * drives outside any route handler.
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**
@@ -1551,7 +1557,7 @@ export interface ChannelConfig<TState = JsonValue> {
    */
   receive?: (
     input: ReceiveInput,
-    args: { send: SendMessageFn }
+    args: { send: SendMessageFn; artifacts: ArtifactsApi }
     // biome-ignore lint/suspicious/noConfusingVoidType: hooks may return a session, nothing, or an async nothing
   ) => Promise<ChannelSession | undefined | void> | ChannelSession | void;
   /** Stream-event handlers for sessions owned by this channel. */
@@ -1742,6 +1748,11 @@ export interface ScheduleHandlerArgs {
   appAuth: AuthContext;
   /** Shared host services (MCP / GitHub / Slack). Same as tool `ctx.host`. */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — schedule handlers have no ambient session;
+   * pass `sessionId` explicitly to attribute).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export interface ScheduleConfig {
@@ -1795,6 +1806,12 @@ export interface ReminderFireContext extends ReminderUntilContext {
   /** Wake the reminder's already-bound session (target is implicit). */
   followup(args: { message: string }): Promise<ChannelSession>;
   cancel(reason?: string): Promise<void>;
+  /**
+   * Durable artifacts (unbound — the reminder is bound to a continuation
+   * token, not a resolved session; pass `sessionId` in `tag` input to
+   * attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**