@pstdio/sdk 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,357 @@
+# @pstdio/sdk
+
+TypeScript SDK for Prompt Studio.
+
+This package is the public integration surface for:
+
+- calling the Prompt Studio HTTP API
+- importing shared request and resource types
+- rendering prompt templates
+- authoring Prompt Studio plugins, actions, and lifecycle hooks
+
+The package is ESM-only and is published through subpath exports. Import from the entrypoint you need, not from `@pstdio/sdk` directly.
+
+## Install
+
+```bash
+bun add @pstdio/sdk
+```
+
+## Entry Points
+
+| Import path             | Purpose                                                   |
+| ----------------------- | --------------------------------------------------------- |
+| `@pstdio/sdk/client`    | Runtime HTTP client for Prompt Studio                     |
+| `@pstdio/sdk/api`       | Request and response payload types                        |
+| `@pstdio/sdk/resources` | Shared resource/entity types                              |
+| `@pstdio/sdk/plugins`   | Plugin definition types, hook types, and helper utilities |
+| `@pstdio/sdk/prompts`   | Prompt rendering helpers                                  |
+| `@pstdio/sdk/hooks`     | Hook context and hook client types                        |
+
+Example:
+
+```ts
+import { createClient, PstdioApiError } from "@pstdio/sdk/client";
+import type { CreateTicketInput } from "@pstdio/sdk/api";
+import type { TicketDetail } from "@pstdio/sdk/resources";
+import { createSession, definePlugin } from "@pstdio/sdk/plugins";
+import { renderPrompt } from "@pstdio/sdk/prompts";
+import type { AttemptStatusChangeContext } from "@pstdio/sdk/hooks";
+```
+
+## HTTP Client
+
+Create a client with `createClient()`:
+
+```ts
+import { createClient } from "@pstdio/sdk/client";
+
+const client = createClient({
+  baseUrl: process.env.PSTDIO_API_URL,
+  token: process.env.PSTDIO_API_TOKEN,
+});
+
+const tickets = await client.tickets.list("proj_123", {
+  status: "wip",
+  tag: ["backend", "bug"],
+});
+```
+
+### Client options
+
+- `baseUrl`: API base URL. Defaults to `process.env.PSTDIO_API_URL ?? "http://localhost:19840"`.
+- `token`: Optional bearer token. Sent as `Authorization: Bearer <token>`.
+- `fetch`: Optional `fetch` implementation override for tests or custom runtimes.
+
+The client expects a runtime with `fetch` available, or an explicit `fetch` passed in through options.
+
+### Error handling
+
+The request layer throws `PstdioApiError` for non-2xx responses.
+
+- `error.message`: API error message
+- `error.status`: HTTP status code
+- when the API returns `hook_output`, it is appended to `message`
+
+```ts
+import { PstdioApiError, createClient } from "@pstdio/sdk/client";
+
+const client = createClient();
+
+try {
+  await client.workspaces.updateAttemptStatus("ws_123", {
+    status: "review-ready",
+  });
+} catch (error) {
+  if (error instanceof PstdioApiError) {
+    console.error(error.status, error.message);
+  }
+  throw error;
+}
+```
+
+### Client groups
+
+`createClient()` returns a grouped client with these domains:
+
+| Group        | Methods                                                                                                                                            |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `projects`   | `list`, `get`, `create`, `delete`, `listRepos`, `registerRepo`, `removeRepo`                                                                       |
+| `tickets`    | `list`, `get`, `create`, `update`, `delete`, `createAttempt`, `updateWhenAttemptStatus`, `listFiles`, `getFileContent`, `uploadFile`, `deleteFile` |
+| `workspaces` | `list`, `getByShorthand`, `create`, `updateAttemptStatus`, `removeWorktree`, `delete`                                                              |
+| `sessions`   | `list`, `get`, `create`, `archive`, `followUp`, `approve`, `getConversation`, `resolveSessionId`, `updateStatus`                                   |
+| `statuses`   | `list`, `create`, `update`, `setDefault`, `delete`, `listAttemptStatuses`, `createAttemptStatus`, `updateAttemptStatus`, `deleteAttemptStatus`     |
+| `tags`       | `list`, `create`, `update`, `delete`, `createOption`, `updateOption`, `deleteOption`                                                               |
+| `templates`  | `list`, `get`, `create`, `update`, `delete`                                                                                                        |
+| `skills`     | `list`, `get`, `update`                                                                                                                            |
+| `agents`     | `list`, `info`, `models`, `setup`, `setupAvailable`, `update`, `delete`                                                                            |
+| `actions`    | `list`, `execute`                                                                                                                                  |
+
+Notes:
+
+- `tickets.list(projectId, filters)` supports `status`, `tag`, `archived`, `draft`, `parent_id`, `shorthand`, and `search`.
+- `tickets.getFileContent(ticketId, fileId)` returns `Uint8Array`, not JSON.
+- `createRequest()` is also exported if you want the lower-level request function without the grouped client.
+
+## API Types
+
+`@pstdio/sdk/api` re-exports the public request and response types used by the HTTP client.
+
+```ts
+import type {
+  CreateSessionInput,
+  CreateTicketInput,
+  UpdateTicketInput,
+} from "@pstdio/sdk/api";
+```
+
+Most of these types come from `pstdio-api-contracts`. The SDK also defines a few client-facing types:
+
+- `ListTicketsInput`
+- `TicketAttemptResponse`
+- `ActionResult`
+- `ExecuteActionInput`
+
+Use `import type` for this entrypoint. It does not expose runtime helpers.
+
+## Resource Types
+
+`@pstdio/sdk/resources` re-exports the shared Prompt Studio entities used across the API and plugin system.
+
+Common exports include `Project`, `Repo`, `Ticket`, `TicketDetail`, `TicketListItem`, `TicketFile`, `Workspace`,
+`WorkspaceListItem`, `Session`, `SessionStatus`, `Status`, `AttemptStatus`, `Tag`, `TagOption`, `Template`,
+`TemplateWithContent`, `TemplateType`, `Skill`, `SkillWithContent`, `AgentConfig`, `AgentInfo`, `AgentModel`,
+`AgentAvailabilityType`, and `FileRecord`.
+
+```ts
+import type {
+  Session,
+  TicketDetail,
+  WorkspaceListItem,
+} from "@pstdio/sdk/resources";
+```
+
+## Prompt Rendering
+
+`@pstdio/sdk/prompts` exposes `renderPrompt(template, data)`, a small wrapper around Mustache.
+
+```ts
+import { renderPrompt } from "@pstdio/sdk/prompts";
+
+const prompt = renderPrompt("Implement ticket {{ticket}}", {
+  ticket: "PS-42",
+});
+```
+
+Use this when a session prompt or action prompt is stored as a reusable template with variables.
+
+## Plugins
+
+Prompt Studio plugins export a default `definePlugin(...)` result from a TypeScript or JavaScript module.
+
+Plugins can provide:
+
+- `actions`: user-triggered actions attached to tickets, workspaces, or sessions
+- `hooks`: lifecycle handlers that run before or after Prompt Studio events
+
+### Action example
+
+```ts
+import { createSession, definePlugin } from "@pstdio/sdk/plugins";
+
+export default definePlugin({
+  actions: [
+    {
+      key: "refine-ticket",
+      label: "Refine ticket",
+      targetType: "ticket",
+      placement: "overflow",
+      params: [
+        {
+          key: "context",
+          label: "Additional context",
+          type: "longtext",
+          required: false,
+        },
+      ],
+      async trigger(ctx) {
+        const context = ctx.params.context as string | undefined;
+
+        const parts = [`Refine ticket: ${ctx.target.shorthand}`];
+        if (context) parts.push(`Additional context:\n${context}`);
+
+        await createSession(ctx, {
+          title: `Refine ticket: ${ctx.target.shorthand}`,
+          prompt: parts.join("\n\n"),
+        });
+      },
+    },
+  ],
+});
+```
+
+### Hook example
+
+```ts
+import { definePlugin, runCommand } from "@pstdio/sdk/plugins";
+
+export default definePlugin({
+  hooks: {
+    async preAttemptStatusChange(ctx) {
+      if (ctx.toStatus !== "review-ready") return;
+      if (!ctx.worktreePath) return;
+
+      const validation = await runCommand(ctx.worktreePath, [
+        "bun",
+        "run",
+        "validate",
+      ]);
+      if (validation.exitCode === 0) return;
+
+      const output = [validation.stdout, validation.stderr]
+        .filter(Boolean)
+        .join("\n\n");
+
+      return {
+        reject: true,
+        reason: output || "bun run validate failed",
+      };
+    },
+  },
+});
+```
+
+### Plugin types
+
+The plugin entrypoint exports the core types used by plugin authors, including `PluginDefinition`, `PluginHooks`,
+`PrePluginHooks`, `PostPluginHooks`, `HookResponse`, `PreHookReturn`, `PostHookReturn`, `ActionDefinition`,
+`ActionDescriptor`, `ActionInput`, `ActionTriggerContext`, `ActionParamDef`, `TargetType`, and `ActionPlacement`.
+
+Action parameter definitions support `text`, `longtext`, `select`, `template-select`, `agent`, and `repo`.
+Action targets support `ticket`, `workspace`, and `session`. Action placement supports `primary`, `secondary`,
+and `overflow`.
+
+`definePlugin()` is intentionally small. Today it mainly validates that every declared action has a `trigger(ctx)` function and then returns the plugin definition unchanged.
+
+### Lifecycle hooks
+
+Pre hooks may return `{ reject, reason, data }` to stop an operation. Post hooks return `void`.
+
+Available pre hooks:
+
+- `preTicketCreation`
+- `preTicketStatusChange`
+- `preTicketArchive`
+- `preTicketDeletion`
+- `preWorktreeCreate`
+- `preWorktreeRemove`
+- `preCommit`
+- `preRebase`
+- `preMerge`
+- `preAttemptStatusChange`
+
+Available post hooks:
+
+- `postTicketCreation`
+- `postTicketStatusChange`
+- `postTicketArchive`
+- `postTicketDeletion`
+- `postSessionStart`
+- `postSessionSuccess`
+- `postSessionFail`
+- `postSessionResume`
+- `postSessionAwaitInput`
+- `postWorktreeCreate`
+- `postWorktreeRemove`
+- `postCommit`
+- `postRebase`
+- `postMerge`
+- `onConflict`
+- `postAttemptStatusChange`
+
+### Plugin helpers
+
+`@pstdio/sdk/plugins` also exports helper functions for common workflow automation:
+
+| Helper                             | Purpose                                                                                      |
+| ---------------------------------- | -------------------------------------------------------------------------------------------- |
+| `createAttempt`                    | Create a ticket attempt and start a session                                                  |
+| `createWorkspace`                  | Create a ticket attempt without starting a session                                           |
+| `createSession`                    | Create a session using `ctx.projectId` automatically                                         |
+| `followupSession`                  | Send a follow-up message using an explicit or contextual session id                          |
+| `findTicketByRef`                  | Resolve a ticket by id or shorthand                                                          |
+| `findWorkspaceByRef`               | Resolve a workspace by id or shorthand                                                       |
+| `getAttemptsForTicket`             | List workspaces for a ticket                                                                 |
+| `workspacesForTicket`              | List workspaces for a ticket                                                                 |
+| `setTicketStatus`                  | Resolve a status by name and update the ticket                                               |
+| `setWorkspaceAttemptStatus`        | Update a workspace attempt status by name                                                    |
+| `updateTicketWhenAllAttemptsMatch` | Update a ticket when all attempts share a target attempt status                              |
+| `removeAllWorktreesForTicket`      | Remove every worktree currently attached to a ticket                                         |
+| `bootstrapWorktree`                | Copy Prompt Studio and agent metadata into a worktree and optionally pull the ticket locally |
+| `pullTickets`                      | Write ticket markdown and attachments into `.pstdio/tickets/...`                             |
+| `runCommand`                       | Run a command array in a working directory and capture `stdout`, `stderr`, and `exitCode`    |
+
+These helpers accept action or hook context and resolve project-scoped ids for you where possible.
+
+## Hook Context Types
+
+`@pstdio/sdk/hooks` exposes the shared context types used by hooks and hook runtimes:
+
+`BaseHookContext`, `HookClient`, `HookPayload`, `SessionFollowupInput`, `AttemptStatusChangeContext`,
+`SessionHookContext`, `TicketContext`, `TicketCreationContext`, `TicketStatusChangeContext`, `WorktreeContext`,
+and `WorktreeCreateContext`.
+
+Import from this entrypoint when you want to annotate hook code explicitly:
+
+```ts
+import type {
+  SessionHookContext,
+  TicketStatusChangeContext,
+} from "@pstdio/sdk/hooks";
+
+const logStatusChange = (ctx: TicketStatusChangeContext) => {
+  console.log(ctx.shorthand, ctx.fromStatus, ctx.toStatus);
+};
+
+const onSessionStart = async (ctx: SessionHookContext) => {
+  console.log(ctx.sessionId, ctx.sessionStatus);
+};
+```
+
+## Package Development
+
+From the repo root:
+
+```bash
+bun run --cwd packages/sdk build
+bun run --cwd packages/sdk lint
+bun run --cwd packages/sdk test
+```
+
+From `packages/sdk`:
+
+```bash
+bun run build
+bun run lint
+bun run test
+```

package/dist/api/actions.d.ts

@@ -6,6 +6,7 @@ export type ExecuteActionInput = {
 export type ActionResult = {
     status: "success";
     session_id?: string;
+    message?: string;
 } | {
     status: "error";
     message: string;

package/dist/client/index.js

@@ -24,6 +24,8 @@ var createProjectClient = (request) => ({
   get: (projectId) => request(`/v1/projects/${projectId}`),
   create: (input) => request("/v1/projects", { method: "POST", body: input }),
   delete: (projectId) => request(`/v1/projects/${projectId}`, { method: "DELETE" }),
+  listPlugins: (projectId) => request(`/v1/projects/${projectId}/plugins`),
+  registerPlugins: (projectId) => request(`/v1/projects/${projectId}/plugins/register`, { method: "POST" }),
   listRepos: (projectId) => request(`/v1/projects/${projectId}/repos`),
   registerRepo: (projectId, input) => request(`/v1/projects/${projectId}/repos`, { method: "POST", body: input }),
   removeRepo: (projectId, repoId) => request(`/v1/projects/${projectId}/repos/${repoId}`, { method: "DELETE" })
@@ -38,9 +40,29 @@ class PstdioApiError extends Error {
     this.status = status;
   }
 }
+var formatZodIssues = (issues) => issues.map((issue) => {
+  const path = Array.isArray(issue.path) ? issue.path.filter((part) => part !== "").join(".") : "";
+  const message = typeof issue.message === "string" ? issue.message : JSON.stringify(issue);
+  return path ? `${path}: ${message}` : message;
+}).join("; ");
+var stringifyErrorField = (error) => {
+  if (typeof error === "string")
+    return error;
+  if (error && typeof error === "object") {
+    const issues = error.issues;
+    if (Array.isArray(issues))
+      return formatZodIssues(issues);
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  return String(error);
+};
 var readErrorMessage = (errorBody, status) => {
   if (errorBody && typeof errorBody === "object" && errorBody !== null && "error" in errorBody) {
-    const message = String(errorBody.error);
+    const message = stringifyErrorField(errorBody.error);
     const hookOutput = "hook_output" in errorBody && typeof errorBody.hook_output === "string" ? errorBody.hook_output.trim() : "";
     return hookOutput ? `${message}
 ${hookOutput}` : message;

package/dist/client/projects.d.ts

@@ -1,13 +1,24 @@
 import type { CreateProjectInput, RegisterRepoInput, Repo } from "pstdio-api-contracts";
 import type { Project } from "../resources";
 import type { RequestFn } from "./request";
+type RegisteredPlugin = {
+    identity: string;
+    filePath: string;
+};
+type RegisteredPluginsResponse = {
+    plugins: RegisteredPlugin[];
+    pluginsDir: string | null;
+};
 export type ProjectClient = {
     list(): Promise<Project[]>;
     get(projectId: string): Promise<Project>;
     create(input: CreateProjectInput): Promise<Project>;
     delete(projectId: string): Promise<void>;
+    listPlugins(projectId: string): Promise<RegisteredPluginsResponse>;
+    registerPlugins(projectId: string): Promise<RegisteredPluginsResponse>;
     listRepos(projectId: string): Promise<Repo[]>;
     registerRepo(projectId: string, input: RegisterRepoInput): Promise<Repo>;
     removeRepo(projectId: string, repoId: string): Promise<void>;
 };
 export declare const createProjectClient: (request: RequestFn) => ProjectClient;
+export {};

package/dist/hooks/session.d.ts

@@ -2,7 +2,7 @@ import type { BaseHookContext } from "./base";
 import type { HookTicket, HookWorkspace } from "./entities";
 export type SessionHookContext = BaseHookContext & {
     sessionId: string;
-    sessionStatus: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled";
+    sessionStatus: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled" | "disconnected";
     originalSessionId?: string;
     workspace?: HookWorkspace;
     workspaceId?: string;

package/dist/plugins/helpers/create-session.d.ts

@@ -5,7 +5,7 @@ export declare const createSession: (ctx: PluginHelperContext, input: CreateSess
     id: string;
     project_id: string | null;
     title: string;
-    status: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled";
+    status: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled" | "disconnected";
     archived: boolean;
     last_request_started: string | null;
     last_request_ended: string | null;

package/dist/plugins/helpers/followup-session.d.ts

@@ -7,7 +7,7 @@ export declare const followupSession: (ctx: PluginHelperContext, input: Followup
     id: string;
     project_id: string | null;
     title: string;
-    status: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled";
+    status: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled" | "disconnected";
     archived: boolean;
     last_request_started: string | null;
     last_request_ended: string | null;

package/dist/plugins/helpers/run-command.d.ts

@@ -1,4 +1,5 @@
 type CommandOutputOptions = {
+    env?: NodeJS.ProcessEnv;
     quiet?: boolean;
 };
 export declare const runCommand: (cwd: string, command: string[], options?: CommandOutputOptions) => Promise<{

package/dist/plugins/index.d.ts

@@ -2,4 +2,4 @@ export { renderPrompt } from "../prompts";
 export { definePlugin } from "./define-plugin";
 export { bootstrapWorktree, createAttempt, createSession, createWorkspace, findTicketByRef, findWorkspaceByRef, followupSession, getAttemptsForTicket, type PullTicketsInput, type PullTicketsResult, pullTickets, removeAllWorktreesForTicket, runCommand, setTicketStatus, setWorkspaceAttemptStatus, updateTicketWhenAllAttemptsMatch, workspacesForTicket, } from "./helpers";
 export type { HookResponse, PluginHooks, PostHookReturn, PostPluginHooks, PreHookReturn, PrePluginHooks, } from "./hooks";
-export type { ActionDefinition, ActionDescriptor, ActionInput, ActionParamDef, ActionParamValue, ActionPlacement, ActionTargetMap, ActionTriggerContext, AgentActionParam, AgentParamValue, LongTextActionParam, PluginDefinition, RepoActionParam, RepoParamValue, SelectActionParam, TargetType, TemplateSelectActionParam, TextActionParam, } from "./types";
+export type { ActionDefinition, ActionDescriptor, ActionInput, ActionParamDef, ActionParamValue, ActionPlacement, ActionTargetMap, ActionTriggerContext, ActionTriggerResult, AgentActionParam, AgentParamValue, LongTextActionParam, PluginDefinition, RepoActionParam, RepoParamValue, SelectActionParam, TargetType, TemplateSelectActionParam, TextActionParam, } from "./types";

package/dist/plugins/index.js

@@ -170,24 +170,29 @@ var removeAllWorktreesForTicket = async (ctx, input) => {
   return removed;
 };
 // src/plugins/helpers/run-command.ts
-import { spawn as nodeSpawn } from "node:child_process";
 var runCommand = async (cwd, command, options = {}) => {
   const [cmd, ...args] = command;
   const stdio = options.quiet ? "ignore" : "pipe";
-  return new Promise((resolve) => {
-    const proc = nodeSpawn(cmd, args, { cwd, stdio: ["ignore", stdio, stdio] });
-    const stdout = [];
-    const stderr = [];
-    proc.stdout?.on("data", (chunk) => stdout.push(chunk.toString()));
-    proc.stderr?.on("data", (chunk) => stderr.push(chunk.toString()));
-    proc.on("close", (code) => {
-      resolve({
-        exitCode: code ?? 1,
-        stdout: stdout.join("").trim(),
-        stderr: stderr.join("").trim()
-      });
+  let proc;
+  try {
+    proc = Bun.spawn([cmd, ...args], {
+      cwd,
+      env: options.env,
+      stdin: "ignore",
+      stdout: stdio,
+      stderr: stdio
     });
-  });
+  } catch (error) {
+    return { exitCode: 1, stdout: "", stderr: error.message };
+  }
+  const readStream = (stream) => stream && typeof stream !== "number" ? new Response(stream).text() : Promise.resolve("");
+  const [stdout, stderr] = await Promise.all([readStream(proc.stdout), readStream(proc.stderr)]);
+  const exitCode = await proc.exited;
+  return {
+    exitCode,
+    stdout: stdout.trim(),
+    stderr: stderr.trim()
+  };
 };
 // src/plugins/helpers/set-ticket-status.ts
 var setTicketStatus = async (ctx, input) => {

package/dist/plugins/types.d.ts

@@ -61,6 +61,11 @@ export type ActionTriggerContext<TTargetType extends TargetType = TargetType> =
     targetId: string;
     target: ActionTargetMap[TTargetType];
 } : never);
+export type ActionTriggerResult = {
+    session_id?: string;
+    message?: string;
+};
+type ActionTrigger<TTargetType extends TargetType = TargetType> = ((ctx: ActionTriggerContext<TTargetType>) => void) | ((ctx: ActionTriggerContext<TTargetType>) => ActionTriggerResult) | ((ctx: ActionTriggerContext<TTargetType>) => Promise<ActionTriggerResult | undefined>);
 export type ActionInput = {
     [K in TargetType]: {
         key: string;
@@ -68,7 +73,7 @@ export type ActionInput = {
         targetType: K;
         placement: ActionPlacement;
         params?: ActionParamDef[];
-        trigger: (ctx: ActionTriggerContext<K>) => void | Promise<void>;
+        trigger: ActionTrigger<K>;
     };
 }[TargetType];
 export type ActionDescriptor = {
@@ -79,7 +84,7 @@ export type ActionDescriptor = {
     params?: ActionParamDef[];
 };
 export type ActionDefinition = ActionDescriptor & {
-    trigger: (ctx: ActionTriggerContext) => void | Promise<void>;
+    trigger: ActionTrigger;
 };
 export type PluginDefinition = {
     key?: string;

package/dist/resources/index.d.ts

@@ -3,7 +3,7 @@ export type { AgentAvailabilityType, AgentConfig, AgentInfo, AgentModel } from "
 export type { FileRecord } from "./file";
 export type { Project } from "./project";
 export type { Session, SessionStatus } from "./session";
-export type { Skill, SkillWithContent } from "./skill";
+export type { Skill, SkillFile, SkillWithContent } from "./skill";
 export type { AttemptStatus, Status } from "./status";
 export type { Tag, TagOption } from "./tag";
 export type { Template, TemplateType, TemplateWithContent } from "./template";

package/dist/resources/skill.d.ts

@@ -1 +1 @@
-export type { Skill, SkillWithContent } from "pstdio-api-contracts";
+export type { Skill, SkillFile, SkillWithContent } from "pstdio-api-contracts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pstdio/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/pufflyai/prompt-studio"
@@ -56,6 +56,6 @@
     "@types/bun": "latest",
     "@types/mustache": "^4.2.6",
     "pstdio-api-contracts": "workspace:*",
-    "typescript": "^5.9.3"
+    "typescript": "6.0.2"
   }
 }