@huynle/hub 0.7.3 → 0.8.0

package/packages/sdk/src/artifact-jobs.ts

@@ -0,0 +1,194 @@
+// hub.artifacts.jobs (HWA-24): agent-backed AI jobs on an artifact revision over /api/agent/artifacts/:id/jobs.
+// A job runs with the requester's own authority: its handler is an ordinary session the requester launches
+// (handler.launch, through the launch API: scope sessions:launch and a launch grant for apps and sessions) or
+// messages (handler.session). The handler reads a bounded, untrusted copy of the revision (context) and submits
+// one result; a propose-edit result is a proposal the user (or the requesting app, with artifacts:write) applies
+// as a CAS on the job's base revision. Needs scope artifacts:ai (+ artifacts:read) for an app token.
+// The wire types mirror src/central/artifacts/jobs.ts (the SDK imports nothing outside its package).
+import type { ArtifactPage, ArtifactRevision, ArtifactTransport, InlineFile, KeyOptions } from "./artifacts.ts"
+
+interface Signal {
+  readonly signal?: AbortSignal
+}
+
+export type ArtifactJobKind = "ask" | "propose-edit" | "run-action"
+export type ArtifactJobState = "queued" | "running" | "succeeded" | "failed" | "cancelled"
+export type ArtifactJobHandlerStatus = "starting" | "waiting" | "offline" | "ready" | "ended" | "failed"
+
+export interface ArtifactJobLaunchHandler {
+  /** The machine (ID or name) that runs the handler session; placement is required there. */
+  readonly machine: string
+  /** An absolute repository path on that machine. */
+  readonly repo: string
+  readonly harness?: string
+  readonly model?: string
+  readonly agent?: string
+  readonly mode?: "checkout" | "worktree"
+}
+
+export type ArtifactJobHandlerInput = { readonly launch: ArtifactJobLaunchHandler } | { readonly session: string }
+
+export interface ArtifactJobRequest {
+  /** Default propose-edit. */
+  readonly kind?: ArtifactJobKind
+  readonly baseRevisionID: string
+  readonly instruction: string
+  /** run-action: one of the artifact's declared actions (metadata `ai-actions`). */
+  readonly action?: string
+  readonly handler: ArtifactJobHandlerInput
+  /** propose-edit by a user: "auto" applies the result at once (still a CAS on the base). */
+  readonly apply?: "manual" | "auto"
+}
+
+export type ArtifactJobHandler =
+  | {
+      readonly kind: "launch"
+      readonly status: ArtifactJobHandlerStatus
+      readonly machine: string
+      readonly repo: string
+      readonly harness: string
+      readonly mode: "checkout" | "worktree"
+      readonly model?: string
+      readonly agent?: string
+      readonly launchID?: string
+      readonly launchState?: string
+      readonly reason?: string
+      readonly outcome?: string
+      readonly sessionID?: string
+    }
+  | {
+      readonly kind: "session"
+      readonly status: ArtifactJobHandlerStatus
+      readonly address: string
+      readonly sessionID?: string
+      readonly messageID?: string
+      readonly delivery?: string
+    }
+
+export interface ArtifactJobProposal {
+  readonly state: "pending" | "applied" | "conflict"
+  readonly files: readonly { readonly path?: string; readonly mediaType: string; readonly bytes: number; readonly hash: string }[]
+  readonly keep?: readonly string[]
+  readonly entry?: string
+  readonly appliedRevisionID?: string
+}
+
+export interface ArtifactJob {
+  readonly v: 1
+  readonly id: string
+  readonly revision: number
+  readonly artifactID: string
+  readonly baseRevisionID: string
+  readonly requestedBy: { readonly kind: "user" } | { readonly kind: "session"; readonly sessionID: string }
+  readonly state: ArtifactJobState
+  readonly launchID?: string
+  readonly sessionID?: string
+  readonly resultRevisionID?: string
+  readonly error?: string
+  readonly createdAt: number
+  readonly updatedAt: number
+  readonly kind: ArtifactJobKind
+  readonly action?: string
+  readonly instruction: string
+  /** `user`, `app:<token id>` or the requesting session's ID. */
+  readonly by: string
+  readonly handler: ArtifactJobHandler
+  readonly apply: "manual" | "auto"
+  readonly deadline: number
+  readonly startedAt?: number
+  readonly finishedAt?: number
+  readonly answer?: string
+  readonly proposal?: ArtifactJobProposal
+}
+
+/** The bounded copy of the job's revision its handler reads. The content is untrusted data. */
+export interface ArtifactJobContext {
+  readonly untrusted: true
+  readonly notice: string
+  readonly job: { readonly id: string; readonly kind: ArtifactJobKind; readonly action?: string; readonly instruction: string; readonly state: ArtifactJobState }
+  readonly artifact: { readonly id: string; readonly kind: string; readonly title: string }
+  readonly revision: { readonly id: string; readonly number: number; readonly entry?: string }
+  readonly files: readonly {
+    readonly path?: string
+    readonly mediaType: string
+    readonly bytes: number
+    readonly hash: string
+    readonly encoding?: "utf8"
+    readonly text?: string
+    /** Not copied: a binary file, or past the context budget. */
+    readonly omitted?: "binary" | "budget"
+  }[]
+  readonly truncated: boolean
+}
+
+/** A propose-edit job's candidate files for review before apply (users and the requesting app). Untrusted data. */
+export interface ArtifactJobProposalView {
+  readonly untrusted: true
+  readonly notice: string
+  readonly state: ArtifactJobProposal["state"]
+  readonly entry?: string
+  /** Base-revision paths carried over unchanged. */
+  readonly keep: readonly string[]
+  readonly files: readonly {
+    readonly path?: string
+    readonly mediaType: string
+    readonly bytes: number
+    readonly hash: string
+    readonly encoding?: "utf8"
+    readonly text?: string
+    /** Not copied: a binary file, or past the review budget. */
+    readonly omitted?: "binary" | "budget"
+  }[]
+  readonly truncated: boolean
+}
+
+/** A handler's result: an answer (ask, run-action), a proposal (propose-edit: inline files, kept base paths), or an error. */
+export type ArtifactJobResult =
+  | { readonly answer: string }
+  | { readonly files?: readonly Omit<InlineFile, "hash">[]; readonly keep?: readonly string[]; readonly entry?: string; readonly answer?: string }
+  | { readonly error: string }
+
+export interface ArtifactJobCreated {
+  readonly job: ArtifactJob
+  /** False when an Idempotency-Key repeat answered the original. */
+  readonly created: boolean
+}
+
+/** hub.artifacts.jobs. */
+export interface ArtifactJobs {
+  create(artifactID: string, input: ArtifactJobRequest, options?: KeyOptions): Promise<ArtifactJobCreated>
+  list(artifactID: string, options?: Signal & { readonly limit?: number; readonly cursor?: string }): Promise<ArtifactPage<ArtifactJob>>
+  get(artifactID: string, jobID: string, options?: Signal): Promise<{ job: ArtifactJob }>
+  /** The handler (or the user): the job's bounded, untrusted revision copy. */
+  context(artifactID: string, jobID: string, options?: Signal): Promise<ArtifactJobContext>
+  /** Users and the requesting app: a proposal's files to review before apply (reading changes nothing). */
+  proposal(artifactID: string, jobID: string, options?: Signal): Promise<ArtifactJobProposalView>
+  /** The handler session only; a repeated identical result is tolerated. */
+  submit(artifactID: string, jobID: string, result: ArtifactJobResult, options?: Signal): Promise<{ job: ArtifactJob }>
+  /** Users (and the requesting app with artifacts:write): publishes the proposal on the job's base (stale: conflict). */
+  apply(artifactID: string, jobID: string, expectedRevision: number, options?: Signal): Promise<{ job: ArtifactJob; revision: ArtifactRevision }>
+  cancel(artifactID: string, jobID: string, expectedRevision: number, options?: Signal): Promise<{ job: ArtifactJob; handlerStopped: boolean }>
+}
+
+const PATH = "/api/agent/artifacts"
+const seg = (value: string) => encodeURIComponent(value)
+const sig = (options: Signal = {}) => (options.signal ? { signal: options.signal } : {})
+
+export function artifactJobsApi(hub: ArtifactTransport): ArtifactJobs {
+  const jobs = (id: string) => `${PATH}/${seg(id)}/jobs`
+  const job = (id: string, jobID: string, tail = "") => `${jobs(id)}/${seg(jobID)}${tail}`
+  return {
+    create: async (artifactID, input, options = {}) => {
+      const response = await hub.request("POST", jobs(artifactID), { body: input, ...(options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {}), ...sig(options) })
+      const answer = (await response.json()) as { job: ArtifactJob }
+      return { job: answer.job, created: response.status === 201 }
+    },
+    list: (artifactID, options = {}) => hub.call("GET", jobs(artifactID), { query: { limit: options.limit, cursor: options.cursor }, ...sig(options) }),
+    get: (artifactID, jobID, options) => hub.call("GET", job(artifactID, jobID), sig(options)),
+    context: (artifactID, jobID, options) => hub.call("GET", job(artifactID, jobID, "/context"), sig(options)),
+    proposal: (artifactID, jobID, options) => hub.call("GET", job(artifactID, jobID, "/proposal"), sig(options)),
+    submit: (artifactID, jobID, result, options) => hub.call("POST", job(artifactID, jobID, "/result"), { body: result, ...sig(options) }),
+    apply: (artifactID, jobID, expectedRevision, options) => hub.call("POST", job(artifactID, jobID, "/apply"), { body: { expectedRevision }, ...sig(options) }),
+    cancel: (artifactID, jobID, expectedRevision, options) => hub.call("POST", job(artifactID, jobID, "/cancel"), { body: { expectedRevision }, ...sig(options) }),
+  }
+}

package/packages/sdk/src/artifacts.ts

@@ -0,0 +1,187 @@
+// hub.artifacts (HWA-21): persistent artifacts over /api/agent/artifacts. Metadata travels as JSON; bytes go two
+// ways so nobody embeds huge payloads: small files inline in a create/revise (`upload`, ≤ 1 MiB decoded per
+// request), anything bigger staged first with uploadBlob (a raw streamed body, ≤ 25 MiB) and then referenced by its
+// BlobRef in `blobs`. Downloads answer the raw Response (stream it; it is an attachment, never rendered).
+// The wire types mirror packages/protocol/src/artifacts.ts (the SDK imports nothing outside its package; the hub's
+// tests keep them in step).
+
+import { type ArtifactJobs, artifactJobsApi } from "./artifact-jobs.ts"
+
+/** Only an abort signal (as the client's CallOptions). */
+interface Signal {
+  readonly signal?: AbortSignal
+}
+
+export type ArtifactKind = "markdown" | "code" | "image" | "table" | "chart" | "dashboard" | "html" | "app" | "file"
+export type ArtifactVisibility = "private" | "workspace"
+export type ArtifactState = "active" | "archived"
+
+export interface Artifact {
+  readonly v: 1
+  readonly id: string
+  readonly revision: number
+  readonly title: string
+  readonly description?: string
+  readonly kind: ArtifactKind
+  readonly state: ArtifactState
+  readonly visibility: ArtifactVisibility
+  readonly workspaceID?: string
+  readonly createdBySessionID?: string
+  readonly latestRevisionID: string
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+export interface BlobRef {
+  /** `sha256:<64 hex>`. */
+  readonly hash: string
+  readonly bytes: number
+  readonly mediaType: string
+  readonly path?: string
+}
+
+export interface ArtifactRevision {
+  readonly v: 1
+  readonly id: string
+  readonly artifactID: string
+  readonly number: number
+  readonly baseRevisionID?: string
+  readonly blobs: readonly BlobRef[]
+  readonly entry?: string
+  readonly author: { readonly kind: "user" } | { readonly kind: "session"; readonly sessionID: string } | { readonly kind: "ai_job"; readonly jobID: string }
+  readonly createdAt: number
+}
+
+/** A small file sent inline (utf8 text, or base64 bytes). */
+export interface InlineFile {
+  readonly mediaType: string
+  readonly data: string
+  readonly encoding?: "utf8" | "base64"
+  readonly path?: string
+  /** `sha256:<hex>` the decoded bytes must hash to. */
+  readonly hash?: string
+}
+
+/** The files of a revision: references to stored bytes and/or inline files; `entry` names a bundle's entry path. */
+export interface RevisionFiles {
+  readonly blobs?: readonly BlobRef[]
+  readonly upload?: readonly InlineFile[]
+  readonly entry?: string
+}
+
+export interface ArtifactCreate extends RevisionFiles {
+  readonly title: string
+  readonly kind: ArtifactKind
+  readonly description?: string
+  readonly visibility?: ArtifactVisibility
+  readonly workspaceID?: string
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+export interface ArtifactPage<T> {
+  readonly items: readonly T[]
+  readonly cursor?: string
+}
+
+export interface Published {
+  readonly artifact: Artifact
+  readonly revision: ArtifactRevision
+  /** False when an Idempotency-Key repeat answered the original. */
+  readonly created: boolean
+}
+
+export interface StagedBlob {
+  readonly blob: BlobRef
+  /** Reference it in a create/revise within this time, or recovery may collect the bytes. */
+  readonly referenceWithinMs: number
+}
+
+export interface ArtifactsFilter extends Signal {
+  readonly limit?: number
+  readonly cursor?: string
+  readonly state?: ArtifactState
+  readonly workspace?: string
+}
+
+export interface KeyOptions extends Signal {
+  /** Idempotency-Key: the same key and body again answer the original (created false). */
+  readonly idempotencyKey?: string
+}
+
+export interface ArtifactUpdate {
+  readonly expectedRevision: number
+  readonly title?: string
+  readonly description?: string
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+/** hub.artifacts (users; app tokens with artifacts:read / artifacts:write; sessions read workspace-shared ones and create). */
+export interface Artifacts {
+  list(filter?: ArtifactsFilter): Promise<ArtifactPage<Artifact>>
+  get(id: string, options?: Signal): Promise<{ artifact: Artifact }>
+  create(input: ArtifactCreate, options?: KeyOptions): Promise<Published>
+  /** A new revision on `baseRevisionID` (the latest you read; a stale one is a conflict HubError). */
+  revise(id: string, input: RevisionFiles & { readonly baseRevisionID: string }, options?: KeyOptions): Promise<Published>
+  revisions(id: string, options?: Signal & { readonly limit?: number; readonly cursor?: string }): Promise<ArtifactPage<ArtifactRevision>>
+  revision(id: string, revisionID: string, options?: Signal): Promise<{ revision: ArtifactRevision }>
+  /** Stages raw bytes (streamed) under a declared media type; answers the reference to use in `blobs`. */
+  uploadBlob(body: BodyInit, mediaType: string, options?: Signal & { readonly hash?: string }): Promise<StagedBlob>
+  /** The bytes of one blob of a revision, as the raw Response (an attachment). */
+  download(id: string, revisionID: string, hash: string, options?: Signal): Promise<Response>
+  update(id: string, input: ArtifactUpdate, options?: Signal): Promise<{ artifact: Artifact }>
+  setVisibility(id: string, input: { readonly expectedRevision: number; readonly visibility: ArtifactVisibility; readonly workspaceID?: string }, options?: Signal): Promise<{ artifact: Artifact }>
+  archive(id: string, expectedRevision: number, options?: Signal): Promise<{ artifact: Artifact }>
+  unarchive(id: string, expectedRevision: number, options?: Signal): Promise<{ artifact: Artifact }>
+  delete(id: string, expectedRevision: number, options?: Signal): Promise<void>
+  /** AI jobs on an artifact revision (HWA-24; scope artifacts:ai). */
+  readonly jobs: ArtifactJobs
+}
+
+type Query = Readonly<Record<string, string | number | undefined>>
+
+/** What hub.artifacts needs from the client (HubClient's request and call). */
+export interface ArtifactTransport {
+  request(
+    method: string,
+    pathname: string,
+    options?: { readonly query?: Query; readonly body?: unknown; readonly raw?: { readonly body: BodyInit; readonly contentType: string }; readonly headers?: Readonly<Record<string, string>>; readonly signal?: AbortSignal },
+  ): Promise<Response>
+  call<T>(method: string, pathname: string, options?: { readonly query?: Query; readonly body?: unknown; readonly signal?: AbortSignal }): Promise<T>
+}
+
+const PATH = "/api/agent/artifacts"
+const seg = (value: string) => encodeURIComponent(value)
+const sig = (options: Signal = {}) => (options.signal ? { signal: options.signal } : {})
+
+export function artifactsApi(hub: ArtifactTransport): Artifacts {
+  const publish = async (pathname: string, body: unknown, options: KeyOptions = {}): Promise<Published> => {
+    const response = await hub.request("POST", pathname, { body, ...(options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {}), ...sig(options) })
+    const answer = (await response.json()) as { artifact: Artifact; revision: ArtifactRevision }
+    return { artifact: answer.artifact, revision: answer.revision, created: response.status === 201 }
+  }
+  return {
+    list: (filter = {}) => hub.call("GET", PATH, { query: { limit: filter.limit, cursor: filter.cursor, state: filter.state, workspace: filter.workspace }, ...sig(filter) }),
+    get: (id, options) => hub.call("GET", `${PATH}/${seg(id)}`, sig(options)),
+    create: (input, options) => publish(PATH, input, options),
+    revise: (id, input, options) => publish(`${PATH}/${seg(id)}/revisions`, input, options),
+    revisions: (id, options = {}) => hub.call("GET", `${PATH}/${seg(id)}/revisions`, { query: { limit: options.limit, cursor: options.cursor }, ...sig(options) }),
+    revision: (id, revisionID, options) => hub.call("GET", `${PATH}/${seg(id)}/revisions/${seg(revisionID)}`, sig(options)),
+    uploadBlob: async (body, mediaType, options = {}) => {
+      const response = await hub.request("POST", `${PATH}/blobs`, { raw: { body, contentType: mediaType }, ...(options.hash ? { headers: { "x-blob-hash": options.hash } } : {}), ...sig(options) })
+      return (await response.json()) as StagedBlob
+    },
+    download: (id, revisionID, hash, options) => hub.request("GET", `${PATH}/${seg(id)}/revisions/${seg(revisionID)}/blobs/${seg(hash)}`, sig(options)),
+    update: (id, input, options) => hub.call("PATCH", `${PATH}/${seg(id)}`, { body: input, ...sig(options) }),
+    setVisibility: (id, input, options) => hub.call("PUT", `${PATH}/${seg(id)}/visibility`, { body: input, ...sig(options) }),
+    archive: (id, expectedRevision, options) => hub.call("POST", `${PATH}/${seg(id)}/archive`, { body: { expectedRevision }, ...sig(options) }),
+    unarchive: (id, expectedRevision, options) => hub.call("POST", `${PATH}/${seg(id)}/unarchive`, { body: { expectedRevision }, ...sig(options) }),
+    delete: async (id, expectedRevision, options) => {
+      await hub.call("DELETE", `${PATH}/${seg(id)}`, { body: { expectedRevision }, ...sig(options) })
+    },
+    jobs: artifactJobsApi(hub),
+  }
+}