From b44c3b49a94d68a4c23852f9e713e056cfa45ef6 Mon Sep 17 00:00:00 2001
From: Alessandro Pogliaghi <alessandro@posthog.com>
Date: Thu, 25 Jun 2026 10:23:47 +0100
Subject: [PATCH] feat(tasks): add skill bundle artifact contracts and metadata
 types

---
 packages/api-client/src/posthog-client.ts     |  7 ++++-
 .../src/sessions/cloudArtifactIdentifiers.ts  | 31 ++++++++++++++++++-
 packages/shared/src/index.ts                  |  2 ++
 packages/shared/src/skills.ts                 |  1 +
 packages/shared/src/task.ts                   | 14 ++++++++-
 5 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/packages/api-client/src/posthog-client.ts b/packages/api-client/src/posthog-client.ts
index eed207fd55..e0d6d890ae 100644
--- a/packages/api-client/src/posthog-client.ts
+++ b/packages/api-client/src/posthog-client.ts
@@ -6,6 +6,7 @@ import type {
   PrAuthorshipMode,
   SeatData,
   StoredLogEntry,
+  TaskRunArtifactMetadata,
 } from "@posthog/shared";
 import {
   DISMISSAL_REASON_OPTIONS,
@@ -432,10 +433,11 @@ export class FolderInstructionsConflictError extends Error {
 
 export interface TaskArtifactUploadRequest {
   name: string;
-  type: "user_attachment";
+  type: "user_attachment" | "skill_bundle";
   size: number;
   content_type?: string;
   source?: string;
+  metadata?: TaskRunArtifactMetadata;
 }
 
 export interface DirectUploadPresignedPost {
@@ -457,6 +459,7 @@ export interface FinalizedTaskArtifactUpload {
   source?: string;
   size?: number;
   content_type?: string;
+  metadata?: TaskArtifactUploadRequest["metadata"];
   storage_path: string;
   uploaded_at?: string;
 }
@@ -2361,6 +2364,7 @@ export class PostHogAPIClient {
             type: artifact.type,
             source: artifact.source,
             content_type: artifact.content_type,
+            metadata: artifact.metadata,
             storage_path: artifact.storage_path,
           })),
         }),
@@ -2436,6 +2440,7 @@ export class PostHogAPIClient {
             type: artifact.type,
             source: artifact.source,
             content_type: artifact.content_type,
+            metadata: artifact.metadata,
             storage_path: artifact.storage_path,
           })),
         }),
diff --git a/packages/core/src/sessions/cloudArtifactIdentifiers.ts b/packages/core/src/sessions/cloudArtifactIdentifiers.ts
index c2c8649341..d8714f3cf0 100644
--- a/packages/core/src/sessions/cloudArtifactIdentifiers.ts
+++ b/packages/core/src/sessions/cloudArtifactIdentifiers.ts
@@ -1,9 +1,15 @@
+import type {
+  TaskRunArtifactMetadata,
+  UploadableSkillSource,
+} from "@posthog/shared";
+
 export interface CloudArtifactUploadRequest {
   name: string;
-  type: "user_attachment";
+  type: "user_attachment" | "skill_bundle";
   size: number;
   content_type?: string;
   source?: string;
+  metadata?: TaskRunArtifactMetadata;
 }
 
 export interface CloudArtifactPresignedPost {
@@ -41,9 +47,32 @@ export interface CloudArtifactClient {
   ): Promise<FinalizedCloudArtifact[]>;
 }
 
+export interface CloudSkillBundleRef {
+  name: string;
+  source: UploadableSkillSource;
+  path: string;
+}
+
+export interface LocalSkillBundle {
+  name: string;
+  source: UploadableSkillSource;
+  fileName: string;
+  contentType: "application/zip";
+  contentBase64: string;
+  contentSha256: string;
+  size: number;
+}
+
+export type BundleLocalSkill = (
+  skillBundleRef: CloudSkillBundleRef,
+) => Promise<LocalSkillBundle>;
+
 export const CLOUD_ARTIFACT_SERVICE = Symbol.for(
   "posthog.core.sessions.cloudArtifactService",
 );
 export const CLOUD_ARTIFACT_READ_FILE_AS_BASE64 = Symbol.for(
   "posthog.core.sessions.cloudArtifactReadFileAsBase64",
 );
+export const CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL = Symbol.for(
+  "posthog.core.sessions.cloudArtifactBundleLocalSkill",
+);
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 8ecefc4d5e..9e50612630 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -169,6 +169,7 @@ export type {
   SkillFileEntry,
   SkillInfo,
   SkillSource,
+  UploadableSkillSource,
 } from "./skills";
 export { SKILL_EXISTS_MARKER, stripFrontmatter } from "./skills";
 export type {
@@ -176,6 +177,7 @@ export type {
   PostHogAPIConfig,
   TaskRun,
   TaskRunArtifact,
+  TaskRunArtifactMetadata,
   TaskRunEnvironment,
   TaskRunStatus,
 } from "./task";
diff --git a/packages/shared/src/skills.ts b/packages/shared/src/skills.ts
index d1e98463e9..540929b7be 100644
--- a/packages/shared/src/skills.ts
+++ b/packages/shared/src/skills.ts
@@ -1,4 +1,5 @@
 export type SkillSource = "bundled" | "user" | "repo" | "marketplace" | "codex";
+export type UploadableSkillSource = Exclude<SkillSource, "bundled">;
 
 export interface SkillInfo {
   name: string;
diff --git a/packages/shared/src/task.ts b/packages/shared/src/task.ts
index c0d6b3f98c..585d44bb1c 100644
--- a/packages/shared/src/task.ts
+++ b/packages/shared/src/task.ts
@@ -1,4 +1,6 @@
 // PostHog Task model (matches PostHog Code's OpenAPI schema)
+import type { UploadableSkillSource } from "./skills";
+
 export interface Task {
   id: string;
   task_number?: number;
@@ -37,7 +39,16 @@ export type ArtifactType =
   | "reference"
   | "output"
   | "artifact"
-  | "user_attachment";
+  | "user_attachment"
+  | "skill_bundle";
+
+export interface TaskRunArtifactMetadata {
+  skill_name: string;
+  skill_source: UploadableSkillSource;
+  content_sha256: string;
+  bundle_format: "zip";
+  schema_version: number;
+}
 
 export interface TaskRunArtifact {
   id?: string;
@@ -46,6 +57,7 @@ export interface TaskRunArtifact {
   source?: string;
   size?: number;
   content_type?: string;
+  metadata?: TaskRunArtifactMetadata;
   storage_path?: string;
   uploaded_at?: string;
 }