feat(tasks): add skill bundle artifact contracts and metadata types

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,
           })),
         }),

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",
+);

packages/shared/src/index.ts

@@ -169,13 +169,15 @@ export type {
   SkillFileEntry,
   SkillInfo,
   SkillSource,
+  UploadableSkillSource,
 } from "./skills";
 export { SKILL_EXISTS_MARKER, stripFrontmatter } from "./skills";
 export type {
   ArtifactType,
   PostHogAPIConfig,
   TaskRun,
   TaskRunArtifact,
+  TaskRunArtifactMetadata,
   TaskRunEnvironment,
   TaskRunStatus,
 } from "./task";

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;

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;
 }