t3code-cli 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "t3code-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "CLI for t3code",
   "keywords": [
     "claude",
@@ -32,13 +32,15 @@
       "types": "./src/index.ts"
     }
   },
+  "dependencies": {},
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@effect/platform-node": "4.0.0-beta.74",
     "@types/node": "^25.9.1",
     "effect": "4.0.0-beta.74",
     "typescript": "^6.0.3",
-    "vite-plus": "^0.1.24"
+    "vite-plus": "^0.1.24",
+    "@t3tools/contracts": "0.0.24"
   },
   "engines": {
     "node": "^24.0.0"

package/src/application/model-selection.ts

@@ -1,4 +1,7 @@
 import * as Effect from "effect/Effect";
+import { ModelSelection, ProviderInstanceId } from "@t3tools/contracts";
+import type { OrchestrationProjectShell } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
 
 import { ModelSelectionError } from "../domain/error.ts";
 import {
@@ -6,23 +9,18 @@ import {
   firstSelectableModel,
   firstSelectableProvider,
 } from "../domain/model-config.ts";
-import {
-  decodeModelSelection,
-  type ModelSelection,
-  type ProjectShell,
-  type ServerConfig,
-} from "../domain/schema.ts";
+import type { ServerConfigForCli } from "../orchestration/service.ts";
 import type { StartThreadInput } from "./service.ts";
 
 export function resolveModelSelection(input: {
   readonly start: StartThreadInput;
-  readonly project: ProjectShell;
-  readonly serverConfig: ServerConfig;
+  readonly project: OrchestrationProjectShell;
+  readonly serverConfig: ServerConfigForCli;
 }) {
   return Effect.gen(function* () {
     if (input.start.provider !== undefined && input.start.model !== undefined) {
       return withModelOptions(input.start, {
-        instanceId: input.start.provider,
+        instanceId: ProviderInstanceId.make(input.start.provider),
         model: input.start.model,
       });
     }
@@ -33,7 +31,7 @@ export function resolveModelSelection(input: {
         return yield* failNoAvailableModel();
       }
       return withModelOptions(input.start, {
-        instanceId: input.start.provider,
+        instanceId: ProviderInstanceId.make(input.start.provider),
         model: model.slug,
       });
     }
@@ -70,7 +68,7 @@ export function mergeModelOptions(
   for (const option of options) {
     optionsById.set(option.id, option);
   }
-  return decodeModelSelection({
+  return Schema.decodeUnknownSync(ModelSelection)({
     ...selection,
     options: [...optionsById.values()],
   });
@@ -83,8 +81,8 @@ function withModelOptions(input: StartThreadInput, selection: ModelSelection): M
   return mergeModelOptions(selection, input.options);
 }
 
-function firstAvailableModel(serverConfig: ServerConfig) {
-  const providers = serverConfig.providers ?? [];
+function firstAvailableModel(serverConfig: ServerConfigForCli) {
+  const providers = serverConfig.providers;
   const provider = firstSelectableProvider(providers);
   if (provider === undefined) {
     return failNoAvailableModel();
@@ -92,8 +90,8 @@ function firstAvailableModel(serverConfig: ServerConfig) {
   return Effect.succeed(provider);
 }
 
-function findProvider(serverConfig: ServerConfig, instanceId: string) {
-  const provider = findSelectableProvider(serverConfig.providers ?? [], instanceId);
+function findProvider(serverConfig: ServerConfigForCli, instanceId: string) {
+  const provider = findSelectableProvider(serverConfig.providers, instanceId);
   if (provider === undefined) {
     return failNoAvailableModel();
   }

package/src/application/models.ts

@@ -12,7 +12,7 @@ export const makeModelsApplication = Effect.fn("makeModelsApplication")(function
   }) {
     const config = yield* orchestration.getServerConfig();
     return filterProvidersForModelListing({
-      providers: config.providers ?? [],
+      providers: config.providers,
       all: input.all === true,
       ...(input.provider !== undefined && input.provider.length > 0
         ? { provider: input.provider }

package/src/application/project-commands.ts

@@ -2,9 +2,9 @@ import * as Crypto from "effect/Crypto";
 import * as DateTime from "effect/DateTime";
 import * as Effect from "effect/Effect";
 import * as Path from "effect/Path";
+import { CommandId, ProjectId, type ClientOrchestrationCommand } from "@t3tools/contracts";
 
 import { Environment } from "../environment/service.ts";
-import type { ProjectCreateCommand } from "../domain/command-schema.ts";
 
 export const makeProjectCreateCommand = Effect.fn("makeProjectCreateCommand")(function* (input: {
   readonly path: string;
@@ -14,15 +14,17 @@ export const makeProjectCreateCommand = Effect.fn("makeProjectCreateCommand")(fu
   const crypto = yield* Crypto.Crypto;
   const environment = yield* Environment;
   const workspaceRoot = path.resolve(environment.cwd, input.path);
-  const projectId = yield* crypto.randomUUIDv4.pipe(Effect.orDie);
+  const projectId = ProjectId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
   const title = input.title?.trim();
   const createdAt = DateTime.formatIso(yield* DateTime.now);
   return {
     type: "project.create",
-    commandId: `t3cli:project-create:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    commandId: CommandId.make(
+      `t3cli:project-create:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    ),
     projectId,
     title: title !== undefined && title.length > 0 ? title : path.basename(workspaceRoot),
     workspaceRoot,
     createdAt,
-  } satisfies ProjectCreateCommand & { readonly projectId: string };
+  } satisfies Extract<ClientOrchestrationCommand, { readonly type: "project.create" }>;
 });

package/src/application/service.ts

@@ -1,18 +1,18 @@
 import * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
 import type * as Stream from "effect/Stream";
-
-import type { ApplicationError } from "./error.ts";
-import type { DispatchResult } from "../domain/command-schema.ts";
 import type {
-  ProjectShell,
-  ServerProvider,
-  ShellSnapshot,
-  ThreadDetail,
-  ThreadMessage,
-  ThreadShell,
+  DispatchResult,
   ModelSelection,
-} from "../domain/schema.ts";
+  OrchestrationMessage,
+  OrchestrationProjectShell,
+  OrchestrationShellSnapshot,
+  OrchestrationThread,
+  OrchestrationThreadShell,
+  ServerProvider,
+} from "@t3tools/contracts";
+
+import type { ApplicationError } from "./error.ts";
 
 export type StartThreadInput = {
   readonly projectRef: string;
@@ -35,15 +35,15 @@ export type StartThreadPolicy = {
 };
 
 export type WaitEvent =
-  | { readonly type: "thread"; readonly thread: ThreadDetail }
-  | { readonly type: "message"; readonly message: ThreadMessage }
+  | { readonly type: "thread"; readonly thread: OrchestrationThread }
+  | { readonly type: "message"; readonly message: OrchestrationMessage }
   | { readonly type: "status"; readonly status: string; readonly threadId: string }
-  | { readonly type: "done"; readonly thread: ThreadDetail };
+  | { readonly type: "done"; readonly thread: OrchestrationThread };
 
 export class T3Application extends Context.Service<
   T3Application,
   {
-    readonly loadShell: () => Effect.Effect<ShellSnapshot, ApplicationError>;
+    readonly loadShell: () => Effect.Effect<OrchestrationShellSnapshot, ApplicationError>;
     readonly listModels: (input: {
       readonly all?: boolean;
       readonly provider?: string;
@@ -52,17 +52,19 @@ export class T3Application extends Context.Service<
       readonly path: string;
       readonly title?: string;
     }) => Effect.Effect<
-      { readonly dispatch: DispatchResult; readonly project: ProjectShell },
+      { readonly dispatch: DispatchResult; readonly project: OrchestrationProjectShell },
       ApplicationError
     >;
     readonly listThreads: (projectRef: string) => Effect.Effect<
       {
-        readonly project: ProjectShell;
-        readonly threads: ReadonlyArray<ThreadShell>;
+        readonly project: OrchestrationProjectShell;
+        readonly threads: ReadonlyArray<OrchestrationThreadShell>;
       },
       ApplicationError
     >;
-    readonly getThreadMessages: (threadId: string) => Effect.Effect<ThreadDetail, ApplicationError>;
+    readonly getThreadMessages: (
+      threadId: string,
+    ) => Effect.Effect<OrchestrationThread, ApplicationError>;
     readonly archiveThread: (threadId: string) => Effect.Effect<DispatchResult, ApplicationError>;
     readonly startThread: (
       input: StartThreadInput,
@@ -70,9 +72,9 @@ export class T3Application extends Context.Service<
     ) => Effect.Effect<
       {
         readonly dispatch: DispatchResult;
-        readonly project: ProjectShell;
+        readonly project: OrchestrationProjectShell;
         readonly threadId: string;
-        readonly thread?: ThreadDetail;
+        readonly thread?: OrchestrationThread;
       },
       ApplicationError
     >;
@@ -83,11 +85,13 @@ export class T3Application extends Context.Service<
       {
         readonly dispatch: DispatchResult;
         readonly threadId: string;
-        readonly thread?: ThreadDetail;
+        readonly thread?: OrchestrationThread;
       },
       ApplicationError
     >;
     readonly watchThread: (threadId: string) => Stream.Stream<WaitEvent, ApplicationError>;
-    readonly waitForThread: (threadId: string) => Effect.Effect<ThreadDetail, ApplicationError>;
+    readonly waitForThread: (
+      threadId: string,
+    ) => Effect.Effect<OrchestrationThread, ApplicationError>;
   }
 >()("t3cli/T3Application") {}

package/src/application/shell-sequence.ts

@@ -1,10 +1,10 @@
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
+import { ORCHESTRATION_WS_METHODS } from "@t3tools/contracts";
 
 import type { Orchestration } from "../orchestration/service.ts";
 import { RpcError } from "../rpc/error.ts";
-import { ORCHESTRATION_WS_METHODS } from "../protocol/schema.ts";
 
 export function waitForShellSequence(input: {
   readonly orchestration: Orchestration;

package/src/application/thread-commands.ts

@@ -1,23 +1,25 @@
 import * as Crypto from "effect/Crypto";
 import * as DateTime from "effect/DateTime";
 import * as Effect from "effect/Effect";
-
-import type {
-  ThreadArchiveCommand,
-  ThreadCreateCommand,
-  ThreadTurnStartCommand,
-} from "../domain/command-schema.ts";
-import type { ModelSelection, ProjectShell, ServerConfig } from "../domain/schema.ts";
+import {
+  CommandId,
+  MessageId,
+  ThreadId,
+  type ClientOrchestrationCommand,
+  type ModelSelection,
+  type OrchestrationProjectShell,
+} from "@t3tools/contracts";
+import type { ServerConfigForCli } from "../orchestration/service.ts";
 import { resolveModelSelection } from "./model-selection.ts";
 import type { SendThreadInput, StartThreadInput } from "./service.ts";
 
 export const makeThreadStartCommands = Effect.fn("makeThreadStartCommands")(function* (input: {
   readonly start: StartThreadInput;
-  readonly project: ProjectShell;
-  readonly serverConfig: ServerConfig;
+  readonly project: OrchestrationProjectShell;
+  readonly serverConfig: ServerConfigForCli;
 }) {
   const crypto = yield* Crypto.Crypto;
-  const threadId = yield* crypto.randomUUIDv4.pipe(Effect.orDie);
+  const threadId = ThreadId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
   const createdAt = DateTime.formatIso(yield* DateTime.now);
   const modelSelection = yield* resolveModelSelection(input);
   const inputTitle = input.start.title?.trim();
@@ -25,7 +27,9 @@ export const makeThreadStartCommands = Effect.fn("makeThreadStartCommands")(func
   const title = inputTitle !== undefined && inputTitle.length > 0 ? inputTitle : messageTitle;
   const createCommand = {
     type: "thread.create",
-    commandId: `t3cli:thread-create:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    commandId: CommandId.make(
+      `t3cli:thread-create:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    ),
     threadId,
     projectId: input.project.id,
     title: title.length > 0 ? title : "New thread",
@@ -35,13 +39,15 @@ export const makeThreadStartCommands = Effect.fn("makeThreadStartCommands")(func
     branch: null,
     worktreePath: input.start.worktreePath ?? null,
     createdAt,
-  } satisfies ThreadCreateCommand;
+  } satisfies Extract<ClientOrchestrationCommand, { readonly type: "thread.create" }>;
   const turnCommand = {
     type: "thread.turn.start",
-    commandId: `t3cli:thread-start:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    commandId: CommandId.make(
+      `t3cli:thread-start:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    ),
     threadId,
     message: {
-      messageId: yield* crypto.randomUUIDv4.pipe(Effect.orDie),
+      messageId: MessageId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie)),
       role: "user",
       text: input.start.message,
       attachments: [],
@@ -51,7 +57,7 @@ export const makeThreadStartCommands = Effect.fn("makeThreadStartCommands")(func
     runtimeMode: "full-access",
     interactionMode: "default",
     createdAt,
-  } satisfies ThreadTurnStartCommand;
+  } satisfies Extract<ClientOrchestrationCommand, { readonly type: "thread.turn.start" }>;
   return { createCommand, turnCommand, threadId };
 });
 
@@ -62,10 +68,12 @@ export const makeThreadTurnContinueCommand = Effect.fn("makeThreadTurnContinueCo
   const createdAt = DateTime.formatIso(yield* DateTime.now);
   return {
     type: "thread.turn.start",
-    commandId: `t3cli:thread-start:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
-    threadId: input.threadId,
+    commandId: CommandId.make(
+      `t3cli:thread-start:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    ),
+    threadId: ThreadId.make(input.threadId),
     message: {
-      messageId: yield* crypto.randomUUIDv4.pipe(Effect.orDie),
+      messageId: MessageId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie)),
       role: "user",
       text: input.message,
       attachments: [],
@@ -74,7 +82,7 @@ export const makeThreadTurnContinueCommand = Effect.fn("makeThreadTurnContinueCo
     interactionMode: "default",
     ...(input.modelSelection !== undefined ? { modelSelection: input.modelSelection } : {}),
     createdAt,
-  } satisfies ThreadTurnStartCommand;
+  } satisfies Extract<ClientOrchestrationCommand, { readonly type: "thread.turn.start" }>;
 });
 
 export const makeThreadArchiveCommand = Effect.fn("makeThreadArchiveCommand")(function* (
@@ -83,7 +91,9 @@ export const makeThreadArchiveCommand = Effect.fn("makeThreadArchiveCommand")(fu
   const crypto = yield* Crypto.Crypto;
   return {
     type: "thread.archive",
-    commandId: `t3cli:thread-archive:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
-    threadId,
-  } satisfies ThreadArchiveCommand;
+    commandId: CommandId.make(
+      `t3cli:thread-archive:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`,
+    ),
+    threadId: ThreadId.make(threadId),
+  } satisfies Extract<ClientOrchestrationCommand, { readonly type: "thread.archive" }>;
 });

package/src/application/thread-wait.ts

@@ -1,10 +1,10 @@
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
+import type { OrchestrationMessage, OrchestrationThread } from "@t3tools/contracts";
 
 import { ThreadSessionError } from "../domain/error.ts";
 import type { Orchestration } from "../orchestration/service.ts";
-import type { ThreadDetail, ThreadMessage } from "../domain/schema.ts";
 import type { WaitEvent } from "./service.ts";
 import {
   applyThreadEvent,
@@ -19,13 +19,13 @@ export function watchThread(input: {
   readonly orchestration: Orchestration;
   readonly threadId: string;
 }) {
-  let current: ThreadDetail | undefined;
-  let currentMessages: Map<string, ThreadMessage> | undefined;
+  let current: OrchestrationThread | undefined;
+  let currentMessages: Map<string, OrchestrationMessage> | undefined;
   return Stream.scoped(
     input.orchestration.watchThreadItems(input.threadId).pipe(
       Stream.flatMap((item) => {
         if (item.kind === "snapshot") {
-          const messages = new Map<string, ThreadMessage>();
+          const messages = new Map<string, OrchestrationMessage>();
           for (const message of item.snapshot.thread.messages) {
             messages.set(messageKey(message), message);
           }

package/src/auth/error.ts

@@ -23,7 +23,11 @@ export class AuthTransportError extends Schema.TaggedErrorClass<AuthTransportErr
   {
     message: Schema.String,
     cause: Schema.optionalKey(
-      Schema.Union([HttpClientError.HttpClientErrorSchema, Schema.instanceOf(Schema.SchemaError)]),
+      Schema.Union([
+        HttpClientError.HttpClientErrorSchema,
+        Schema.instanceOf(Schema.SchemaError),
+        UrlError,
+      ]),
     ),
   },
 ) {}

package/src/auth/pairing.ts

@@ -14,7 +14,11 @@ export function parsePairingUrl(value: string): Effect.Effect<PairingUrl, AuthPa
 
     const hostedHost = url.searchParams.get("host")?.trim();
     const baseUrl = normalizeBaseUrl(
-      yield* parseUrl(hostedHost !== undefined && hostedHost.length > 0 ? hostedHost : url.origin),
+      yield* parseUrl(
+        hostedHost !== undefined && hostedHost.length > 0
+          ? hostedHost
+          : new URL(".", url).toString(),
+      ),
     );
     return { baseUrl, credential: token };
   });
@@ -33,7 +37,7 @@ function normalizeBaseUrl(url: URL) {
   return Url.mutate(url, (current) => {
     current.hash = "";
     current.search = "";
-    current.pathname = "";
+    current.pathname = current.pathname === "/" ? "" : current.pathname.replace(/\/+$/u, "");
   })
     .toString()
     .replace(/\/$/, "");

package/src/auth/transport.ts

@@ -2,6 +2,7 @@ import * as Effect from "effect/Effect";
 import { HttpClient, HttpClientError, HttpClientRequest } from "effect/unstable/http";
 
 import type { ResolvedConfig } from "../config/service.ts";
+import { toHttpEndpointUrl } from "../config/url.ts";
 import { AuthTransportError } from "./error.ts";
 import {
   decodeAuthBearerBootstrapResult,
@@ -16,8 +17,8 @@ export const makeAuthTransport = Effect.fn("makeAuthTransport")(function* () {
     readonly baseUrl: string;
     readonly credential: string;
   }) {
-    const request = HttpClientRequest.post(input.baseUrl).pipe(
-      HttpClientRequest.appendUrl("/api/auth/bootstrap/bearer"),
+    const url = yield* makeHttpEndpointUrl(input.baseUrl, "/api/auth/bootstrap/bearer");
+    const request = HttpClientRequest.post(url).pipe(
       HttpClientRequest.acceptJson,
       HttpClientRequest.bodyJsonUnsafe({ credential: input.credential }),
     );
@@ -51,7 +52,7 @@ export const makeAuthTransport = Effect.fn("makeAuthTransport")(function* () {
   });
 
   const getSession = Effect.fn("AuthTransport.getSession")(function* (config: ResolvedConfig) {
-    const request = authenticatedRequest(config, "/api/auth/session", "get");
+    const request = yield* authenticatedRequest(config, "/api/auth/session", "get");
     const response = yield* client.execute(request).pipe(
       Effect.catchTags({
         HttpClientError: (error) =>
@@ -84,7 +85,7 @@ export const makeAuthTransport = Effect.fn("makeAuthTransport")(function* () {
   const issueWebSocketToken = Effect.fn("AuthTransport.issueWebSocketToken")(function* (
     config: ResolvedConfig,
   ) {
-    const request = authenticatedRequest(config, "/api/auth/ws-token", "post");
+    const request = yield* authenticatedRequest(config, "/api/auth/ws-token", "post");
     const response = yield* client.execute(request).pipe(
       Effect.catchTags({
         HttpClientError: (error) =>
@@ -122,11 +123,21 @@ export const makeAuthTransport = Effect.fn("makeAuthTransport")(function* () {
 });
 
 function authenticatedRequest(config: ResolvedConfig, path: string, method: "get" | "post") {
-  const request =
-    method === "get" ? HttpClientRequest.get(config.url) : HttpClientRequest.post(config.url);
-  return request.pipe(
-    HttpClientRequest.appendUrl(path),
-    HttpClientRequest.acceptJson,
-    HttpClientRequest.bearerToken(config.token),
+  return makeHttpEndpointUrl(config.url, path).pipe(
+    Effect.map((url) =>
+      method === "get" ? HttpClientRequest.get(url) : HttpClientRequest.post(url),
+    ),
+    Effect.map((request) =>
+      request.pipe(HttpClientRequest.acceptJson, HttpClientRequest.bearerToken(config.token)),
+    ),
+  );
+}
+
+function makeHttpEndpointUrl(baseUrl: string, path: string) {
+  return toHttpEndpointUrl(baseUrl, path).pipe(
+    Effect.catchTags({
+      UrlError: (error) =>
+        Effect.fail(new AuthTransportError({ message: "auth request failed", cause: error })),
+    }),
   );
 }

package/src/cli/model-format.ts

@@ -1,4 +1,4 @@
-import type { ServerProvider } from "../domain/schema.ts";
+import type { ServerProvider } from "@t3tools/contracts";
 
 export function formatModelsHuman(providers: ReadonlyArray<ServerProvider>) {
   if (providers.length === 0) {

package/src/cli/project-format.ts

@@ -1,11 +1,11 @@
-import type { ProjectShell } from "../domain/schema.ts";
+import type { OrchestrationProjectShell } from "@t3tools/contracts";
 
-export function formatProjectsHuman(projects: ReadonlyArray<ProjectShell>) {
+export function formatProjectsHuman(projects: ReadonlyArray<OrchestrationProjectShell>) {
   return projects
     .map((project) => `- ${project.title}\n  id: ${project.id}\n  path: ${project.workspaceRoot}\n`)
     .join("");
 }
 
-export function formatProjectAddedHuman(project: ProjectShell) {
+export function formatProjectAddedHuman(project: OrchestrationProjectShell) {
   return `project added: ${project.title}\nid: ${project.id}\npath: ${project.workspaceRoot}`;
 }

package/src/cli/thread-format.ts

@@ -1,8 +1,8 @@
 import type { WaitEvent } from "../application/service.ts";
-import type { ThreadDetail, ThreadShell } from "../domain/schema.ts";
+import type { OrchestrationThread, OrchestrationThreadShell } from "@t3tools/contracts";
 import { latestAssistantMessage, threadStatus } from "../domain/thread-lifecycle.ts";
 
-export function formatThreadsHuman(threads: ReadonlyArray<ThreadShell>) {
+export function formatThreadsHuman(threads: ReadonlyArray<OrchestrationThreadShell>) {
   return threads
     .map(
       (thread) =>
@@ -12,23 +12,23 @@ export function formatThreadsHuman(threads: ReadonlyArray<ThreadShell>) {
 }
 
 export function formatThreadStartedHuman(input: {
-  readonly thread: ThreadDetail;
+  readonly thread: OrchestrationThread;
   readonly sequence: number;
 }) {
   return `thread started: ${input.thread.title}\nid: ${input.thread.id}\nstatus: ${threadStatus(input.thread)}\nsequence: ${input.sequence}`;
 }
 
-export function formatThreadMessagesHuman(thread: ThreadDetail, limit: number) {
+export function formatThreadMessagesHuman(thread: OrchestrationThread, limit: number) {
   const messages = limit === 0 ? thread.messages : thread.messages.slice(-limit);
   return messages.map((message) => `\n### ${message.role}\n\n${message.text}\n`).join("");
 }
 
-export function formatWaitDoneHuman(thread: ThreadDetail) {
+export function formatWaitDoneHuman(thread: OrchestrationThread) {
   const latest = latestAssistantMessage(thread);
   return `status: ${threadStatus(thread)}\n${latest !== undefined ? `\n### ${latest.role}\n\n${latest.text}\n` : ""}`;
 }
 
-export function formatThreadMessagesJson(thread: ThreadDetail, full: boolean) {
+export function formatThreadMessagesJson(thread: OrchestrationThread, full: boolean) {
   return full ? thread : { thread: stripThreadMessages(thread), messages: thread.messages };
 }
 

package/src/config/url.ts

@@ -26,6 +26,31 @@ export function toWebSocketBaseUrl(httpBaseUrl: string) {
   );
 }
 
+export function toHttpEndpointUrl(httpBaseUrl: string, pathname: string) {
+  return parseUrl(httpBaseUrl).pipe(
+    Effect.flatMap((url) => Effect.succeed(withPathname(url, pathname).toString())),
+  );
+}
+
+export function toWebSocketEndpointUrl(httpBaseUrl: string, pathname: string) {
+  return parseUrl(httpBaseUrl).pipe(
+    Effect.flatMap((url) => {
+      if (url.protocol === "http:") {
+        return Effect.succeed(withPathname(url, pathname, "ws:").toString());
+      }
+      if (url.protocol === "https:") {
+        return Effect.succeed(withPathname(url, pathname, "wss:").toString());
+      }
+      return Effect.fail(
+        new UrlError({
+          message: `unsupported server url protocol: ${url.protocol}`,
+          protocol: url.protocol,
+        }),
+      );
+    }),
+  );
+}
+
 function parseUrl(value: string): Effect.Effect<URL, UrlError> {
   return Effect.fromResult(Url.fromString(value)).pipe(
     Effect.catchTags({
@@ -39,7 +64,7 @@ function normalizeBaseUrl(url: URL) {
   return Url.mutate(url, (current) => {
     current.hash = "";
     current.search = "";
-    current.pathname = "";
+    current.pathname = normalizePathname(current.pathname);
   })
     .toString()
     .replace(/\/$/, "");
@@ -48,8 +73,27 @@ function normalizeBaseUrl(url: URL) {
 function makeWebSocketUrl(url: URL, protocol: "ws:" | "wss:") {
   return Url.mutate(url, (current) => {
     current.protocol = protocol;
-    current.pathname = "/ws";
+    current.pathname = appendPathname(current.pathname, "/ws");
     current.search = "";
     current.hash = "";
   }).toString();
 }
+
+function withPathname(url: URL, pathname: string, protocol?: "ws:" | "wss:") {
+  return Url.mutate(url, (current) => {
+    if (protocol !== undefined) {
+      current.protocol = protocol;
+    }
+    current.pathname = appendPathname(current.pathname, pathname);
+    current.search = "";
+    current.hash = "";
+  });
+}
+
+function normalizePathname(pathname: string) {
+  return pathname === "/" ? "" : pathname.replace(/\/+$/u, "");
+}
+
+function appendPathname(basePathname: string, pathname: string) {
+  return `${normalizePathname(basePathname)}${pathname.startsWith("/") ? pathname : `/${pathname}`}`;
+}

package/src/domain/helpers.ts

@@ -1,9 +1,14 @@
 import type * as Path from "effect/Path";
+import type { OrchestrationProjectShell, OrchestrationShellSnapshot } from "@t3tools/contracts";
 
 import { ProjectLookupError } from "./error.ts";
-import type { ProjectShell, ShellSnapshot } from "./schema.ts";
 
-export function resolveProject(snapshot: ShellSnapshot, ref: string, path: Path.Path, cwd: string) {
+export function resolveProject(
+  snapshot: OrchestrationShellSnapshot,
+  ref: string,
+  path: Path.Path,
+  cwd: string,
+) {
   const byId = findProjectById(snapshot, ref);
   if (byId !== null) {
     return byId;
@@ -18,6 +23,9 @@ export function resolveProject(snapshot: ShellSnapshot, ref: string, path: Path.
   throw new ProjectLookupError({ message: `project not found: ${ref}`, ref });
 }
 
-export function findProjectById(snapshot: ShellSnapshot, projectId: string): ProjectShell | null {
+export function findProjectById(
+  snapshot: OrchestrationShellSnapshot,
+  projectId: string,
+): OrchestrationProjectShell | null {
   return snapshot.projects.find((project) => project.id === projectId) ?? null;
 }