@miaws/miaw 1.18.4 → 1.18.5

package/src/question/index.ts

@@ -0,0 +1,229 @@
+import { LayerNode } from "@miaw/core/effect/layer-node"
+import { Deferred, Effect, Layer, Schema, Context } from "effect"
+import { InstanceState } from "@/effect/instance-state"
+import { SessionID, MessageID } from "@/session/schema"
+import { QuestionID } from "./schema"
+import { EventV2Bridge } from "@/event-v2-bridge"
+import { EventV2 } from "@miaw/core/event"
+
+// Schemas — these are pure data; nothing checks class identity (see PR
+// description) so they're plain `Schema.Struct` + type alias. That lets
+// `Question.ask` and other internal sites trust the type contract without a
+// re-decode to coerce nested class instances.
+
+export const Option = Schema.Struct({
+  label: Schema.String.annotate({
+    description: "Display text (1-5 words, concise)",
+  }),
+  description: Schema.String.annotate({
+    description: "Explanation of choice",
+  }),
+}).annotate({ identifier: "QuestionOption" })
+export type Option = Schema.Schema.Type<typeof Option>
+
+const base = {
+  question: Schema.String.annotate({
+    description: "Complete question",
+  }),
+  header: Schema.String.annotate({
+    description: "Very short label (max 30 chars)",
+  }),
+  options: Schema.Array(Option).annotate({
+    description: "Available choices",
+  }),
+  multiple: Schema.optional(Schema.Boolean).annotate({
+    description: "Allow selecting multiple choices",
+  }),
+}
+
+export const Info = Schema.Struct({
+  ...base,
+  custom: Schema.optional(Schema.Boolean).annotate({
+    description: "Allow typing a custom answer (default: true)",
+  }),
+}).annotate({ identifier: "QuestionInfo" })
+export type Info = Schema.Schema.Type<typeof Info>
+
+export const Prompt = Schema.Struct(base).annotate({ identifier: "QuestionPrompt" })
+export type Prompt = Schema.Schema.Type<typeof Prompt>
+
+export const Tool = Schema.Struct({
+  messageID: MessageID,
+  callID: Schema.String,
+}).annotate({ identifier: "QuestionTool" })
+export type Tool = Schema.Schema.Type<typeof Tool>
+
+export const Request = Schema.Struct({
+  id: QuestionID,
+  sessionID: SessionID,
+  questions: Schema.Array(Info).annotate({
+    description: "Questions to ask",
+  }),
+  tool: Schema.optional(Tool),
+}).annotate({ identifier: "QuestionRequest" })
+export type Request = Schema.Schema.Type<typeof Request>
+
+export const Answer = Schema.Array(Schema.String).annotate({ identifier: "QuestionAnswer" })
+export type Answer = Schema.Schema.Type<typeof Answer>
+
+export const Reply = Schema.Struct({
+  answers: Schema.Array(Answer).annotate({
+    description: "User answers in order of questions (each answer is an array of selected labels)",
+  }),
+}).annotate({ identifier: "QuestionReply" })
+export type Reply = Schema.Schema.Type<typeof Reply>
+
+export const Replied = Schema.Struct({
+  sessionID: SessionID,
+  requestID: QuestionID,
+  answers: Schema.Array(Answer),
+}).annotate({ identifier: "QuestionReplied" })
+
+export const Rejected = Schema.Struct({
+  sessionID: SessionID,
+  requestID: QuestionID,
+}).annotate({ identifier: "QuestionRejected" })
+
+export const Event = {
+  Asked: EventV2.define({ type: "question.asked", schema: Request.fields }),
+  Replied: EventV2.define({ type: "question.replied", schema: Replied.fields }),
+  Rejected: EventV2.define({ type: "question.rejected", schema: Rejected.fields }),
+}
+
+export class RejectedError extends Schema.TaggedErrorClass<RejectedError>()("QuestionRejectedError", {}) {
+  override get message() {
+    return "The user dismissed this question"
+  }
+}
+
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Question.NotFoundError", {
+  requestID: QuestionID,
+}) {}
+
+interface PendingEntry {
+  info: Request
+  deferred: Deferred.Deferred<ReadonlyArray<Answer>, RejectedError>
+}
+
+interface State {
+  pending: Map<QuestionID, PendingEntry>
+}
+
+// Service
+
+export interface Interface {
+  readonly ask: (input: {
+    sessionID: SessionID
+    questions: ReadonlyArray<Info>
+    tool?: Tool
+  }) => Effect.Effect<ReadonlyArray<Answer>, RejectedError>
+  readonly reply: (input: {
+    requestID: QuestionID
+    answers: ReadonlyArray<Answer>
+  }) => Effect.Effect<void, NotFoundError>
+  readonly reject: (requestID: QuestionID) => Effect.Effect<void, NotFoundError>
+  readonly list: () => Effect.Effect<ReadonlyArray<Request>>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@miaw/Question") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const events = yield* EventV2Bridge.Service
+    const state = yield* InstanceState.make<State>(
+      Effect.fn("Question.state")(function* () {
+        const state = {
+          pending: new Map<QuestionID, PendingEntry>(),
+        }
+
+        yield* Effect.addFinalizer(() =>
+          Effect.gen(function* () {
+            for (const item of state.pending.values()) {
+              yield* Deferred.fail(item.deferred, new RejectedError())
+            }
+            state.pending.clear()
+          }),
+        )
+
+        return state
+      }),
+    )
+
+    const ask = Effect.fn("Question.ask")(function* (input: {
+      sessionID: SessionID
+      questions: ReadonlyArray<Info>
+      tool?: Tool
+    }) {
+      const pending = (yield* InstanceState.get(state)).pending
+      const id = QuestionID.ascending()
+      yield* Effect.logInfo("asking", { id, questions: input.questions.length })
+
+      const deferred = yield* Deferred.make<ReadonlyArray<Answer>, RejectedError>()
+      const info: Request = {
+        id,
+        sessionID: input.sessionID,
+        questions: input.questions,
+        tool: input.tool,
+      }
+      pending.set(id, { info, deferred })
+      yield* events.publish(Event.Asked, info)
+
+      return yield* Effect.ensuring(
+        Deferred.await(deferred),
+        Effect.sync(() => {
+          pending.delete(id)
+        }),
+      )
+    })
+
+    const reply = Effect.fn("Question.reply")(function* (input: {
+      requestID: QuestionID
+      answers: ReadonlyArray<Answer>
+    }) {
+      const pending = (yield* InstanceState.get(state)).pending
+      const existing = pending.get(input.requestID)
+      if (!existing) {
+        yield* Effect.logWarning("reply for unknown request", { requestID: input.requestID })
+        return yield* new NotFoundError({ requestID: input.requestID })
+      }
+      pending.delete(input.requestID)
+      yield* Effect.logInfo("replied", { requestID: input.requestID, answers: input.answers })
+      yield* events.publish(Event.Replied, {
+        sessionID: existing.info.sessionID,
+        requestID: existing.info.id,
+        answers: input.answers.map((a) => [...a]),
+      })
+      yield* Deferred.succeed(existing.deferred, input.answers)
+    })
+
+    const reject = Effect.fn("Question.reject")(function* (requestID: QuestionID) {
+      const pending = (yield* InstanceState.get(state)).pending
+      const existing = pending.get(requestID)
+      if (!existing) {
+        yield* Effect.logWarning("reject for unknown request", { requestID })
+        return yield* new NotFoundError({ requestID })
+      }
+      pending.delete(requestID)
+      yield* Effect.logInfo("rejected", { requestID })
+      yield* events.publish(Event.Rejected, {
+        sessionID: existing.info.sessionID,
+        requestID: existing.info.id,
+      })
+      yield* Deferred.fail(existing.deferred, new RejectedError())
+    })
+
+    const list = Effect.fn("Question.list")(function* () {
+      const pending = (yield* InstanceState.get(state)).pending
+      return Array.from(pending.values(), (x) => x.info)
+    })
+
+    return Service.of({ ask, reply, reject, list })
+  }),
+)
+
+export const defaultLayer = layer.pipe(Layer.provide(EventV2Bridge.defaultLayer))
+
+export const node = LayerNode.make(layer, [EventV2Bridge.node])
+
+export * as Question from "."

package/src/question/schema.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect"
+
+import { Identifier } from "@/id/id"
+import { Newtype } from "@miaw/core/schema"
+
+export class QuestionID extends Newtype<QuestionID>()("QuestionID", Schema.String.check(Schema.isStartsWith("que"))) {
+  static ascending(id?: string): QuestionID {
+    return this.make(Identifier.ascending("question", id))
+  }
+}

package/src/server/auth.ts

@@ -0,0 +1,48 @@
+export * as ServerAuth from "./auth"
+
+import { ConfigService } from "@/effect/config-service"
+import { Flag } from "@miaw/core/flag/flag"
+import { Config as EffectConfig, Context, Option, Redacted } from "effect"
+
+export type Credentials = {
+  password?: string
+  username?: string
+}
+
+export type DecodedCredentials = {
+  readonly username: string
+  readonly password: Redacted.Redacted
+}
+
+export class Config extends ConfigService.Service<Config>()("@miaw/ServerAuthConfig", {
+  password: EffectConfig.string("MIAW_SERVER_PASSWORD").pipe(EffectConfig.option),
+  username: EffectConfig.string("MIAW_SERVER_USERNAME").pipe(EffectConfig.withDefault("miaw")),
+}) {}
+
+export type Info = Context.Service.Shape<typeof Config>
+
+export function required(config: Info) {
+  return Option.isSome(config.password) && config.password.value !== ""
+}
+
+export function authorized(credentials: DecodedCredentials, config: Info) {
+  return (
+    Option.isSome(config.password) &&
+    credentials.username === config.username &&
+    Redacted.value(credentials.password) === config.password.value
+  )
+}
+
+export function header(credentials?: Credentials) {
+  const password = credentials?.password ?? Flag.MIAW_SERVER_PASSWORD
+  if (!password) return undefined
+
+  const username = credentials?.username ?? Flag.MIAW_SERVER_USERNAME ?? "miaw"
+  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`
+}
+
+export function headers(credentials?: Credentials) {
+  const authorization = header(credentials)
+  if (!authorization) return undefined
+  return { Authorization: authorization }
+}

package/src/server/event.ts

@@ -0,0 +1,13 @@
+import { EventV2 } from "@miaw/core/event"
+import { Schema } from "effect"
+
+export const Event = {
+  Connected: EventV2.define({ type: "server.connected", schema: {} }),
+  Disposed: EventV2.define({ type: "global.disposed", schema: {} }),
+}
+
+export const InstanceDisposed = Schema.Struct({
+  id: Schema.String,
+  type: Schema.Literal("server.instance.disposed"),
+  properties: Schema.Struct({ directory: Schema.String }),
+}).annotate({ identifier: "Event.server.instance.disposed" })

package/src/server/global-lifecycle.ts

@@ -0,0 +1,28 @@
+import { GlobalBus } from "@/bus/global"
+import { InstanceStore } from "@/project/instance-store"
+import { Effect } from "effect"
+import { Event } from "./event"
+
+export const emitGlobalDisposed = Effect.sync(() =>
+  GlobalBus.emit("event", {
+    directory: "global",
+    payload: {
+      type: Event.Disposed.type,
+      properties: {},
+    },
+  }),
+)
+
+export const disposeAllInstancesAndEmitGlobalDisposed = Effect.fn("Server.disposeAllInstancesAndEmitGlobalDisposed")(
+  function* (options?: { swallowErrors?: boolean }) {
+    const store = yield* InstanceStore.Service
+    yield* Effect.gen(function* () {
+      yield* options?.swallowErrors
+        ? store.disposeAll().pipe(Effect.catchCause((cause) => Effect.logWarning("global disposal failed", { cause })))
+        : store.disposeAll()
+      yield* emitGlobalDisposed
+    }).pipe(Effect.uninterruptible)
+  },
+)
+
+export * as GlobalLifecycle from "./global-lifecycle"

package/src/server/init-projectors.ts

@@ -0,0 +1,3 @@
+import { initProjectors } from "./projectors"
+
+initProjectors()

package/src/server/mdns.ts

@@ -0,0 +1,47 @@
+import { Bonjour } from "bonjour-service"
+
+let bonjour: Bonjour | undefined
+let currentPort: number | undefined
+
+export function publish(port: number, domain?: string) {
+  if (currentPort === port) return
+  if (bonjour) unpublish()
+
+  try {
+    const host = domain ?? "miaw.local"
+    const name = `miaw-${port}`
+    bonjour = new Bonjour()
+    const service = bonjour.publish({
+      name,
+      type: "http",
+      host,
+      port,
+      txt: { path: "/" },
+    })
+
+    service.on("error", () => {})
+
+    currentPort = port
+  } catch {
+    if (bonjour) {
+      try {
+        bonjour.destroy()
+      } catch {}
+    }
+    bonjour = undefined
+    currentPort = undefined
+  }
+}
+
+export function unpublish() {
+  if (bonjour) {
+    try {
+      bonjour.unpublishAll()
+      bonjour.destroy()
+    } catch {}
+    bonjour = undefined
+    currentPort = undefined
+  }
+}
+
+export * as MDNS from "./mdns"

package/src/server/projectors.ts

@@ -0,0 +1 @@
+export function initProjectors() {}

package/src/server/proxy-util.ts

@@ -0,0 +1,48 @@
+const hop = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+])
+
+function sanitize(out: Headers) {
+  for (const key of hop) out.delete(key)
+  out.delete("accept-encoding")
+  out.delete("x-miaw-directory")
+  out.delete("x-miaw-workspace")
+}
+
+export function headers(input: Request | HeadersInit | Record<string, string>, extra?: HeadersInit) {
+  const raw = input instanceof Request ? input.headers : input
+  const out = new Headers(raw instanceof Headers ? raw : Object.entries(raw as Record<string, string>))
+  sanitize(out)
+  if (!extra) return out
+  for (const [key, value] of new Headers(extra).entries()) {
+    out.set(key, value)
+  }
+  return out
+}
+
+export function websocketProtocols(input: Request | Record<string, string | undefined>) {
+  const value = input instanceof Request ? input.headers.get("sec-websocket-protocol") : input["sec-websocket-protocol"]
+  if (!value) return []
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+}
+
+export function websocketTargetURL(url: string | URL) {
+  const next = new URL(url)
+  if (next.protocol === "http:") next.protocol = "ws:"
+  if (next.protocol === "https:") next.protocol = "wss:"
+  return next.toString()
+}
+
+export * as ProxyUtil from "./proxy-util"

package/src/server/routes/instance/httpapi/AGENTS.md

@@ -0,0 +1,39 @@
+# HttpApi Route Patterns
+
+Use `HttpApiBuilder.group(...)` for normal HTTP endpoints, including streaming HTTP responses such as server-sent events. Handlers should yield stable services once while building the handler layer, then close over those services in endpoint implementations.
+
+```ts
+export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session", (handlers) =>
+  Effect.gen(function* () {
+    const session = yield* Session.Service
+
+    return handlers.handle("list", () => session.list())
+  }),
+)
+```
+
+For SSE endpoints, stay in `HttpApiBuilder.group(...)` and return `HttpServerResponse.stream(...)` from the handler. Annotate the endpoint success schema with `HttpApiSchema.asText({ contentType: "text/event-stream" })` so OpenAPI documents the stream content type.
+
+Use `HttpApiBuilder.group(...)` with `handleRaw(...)` for declared endpoints that need the raw request or response, including WebSocket upgrade routes. This keeps endpoint middleware, routing context, and OpenAPI metadata on one typed route tree.
+
+```ts
+export const ptyConnectHandlers = HttpApiBuilder.group(PtyConnectApi, "pty-connect", (handlers) =>
+  Effect.gen(function* () {
+    const pty = yield* Pty.Service
+
+    return handlers.handleRaw("connect", (ctx) => connectPty(ctx.request, pty))
+  }),
+)
+```
+
+Use raw `HttpRouter.use(...)` only for routes outside the declared API surface, such as a catch-all UI fallback.
+
+Avoid `Effect.provide(SomeLayer)` inside request handlers or raw route callbacks. Stable layers should be provided once at the application/layer boundary, not rebuilt or scoped per request.
+
+Avoid `HttpRouter.provideRequest(...)` unless the dependency is intentionally request-level. Prefer `HttpRouter.use(...)` for stable app services.
+
+Use `Effect.provideService(...)` in middleware only for request-derived context, such as `WorkspaceRouteContext`, `InstanceRef`, or `WorkspaceRef`. Do not use it to smuggle stable services through request effects when they can be yielded at layer construction.
+
+Public JSON errors should be explicit `Schema.ErrorClass` contracts declared on each endpoint. Use built-in `HttpApiError.*` classes only when their empty/tagged body is the intended wire shape; for SDK-visible errors with messages, define an API error schema such as `ApiNotFoundError` and fail with that exact declared error. Keep domain and storage services free of HttpApi types, and translate expected domain errors at the handler boundary.
+
+When adding middleware, declare endpoint-contract middleware on the owning `HttpApiGroup` and provide its implementation layer at the assembly boundary in `server.ts`. Keep router middleware for truly raw fallback routes or global transport policy.

package/src/server/routes/instance/httpapi/api.ts

@@ -0,0 +1,78 @@
+import { Schema } from "effect"
+import { HttpApi } from "effect/unstable/httpapi"
+import { EventV2 } from "@miaw/core/event"
+import { InstanceDisposed } from "@/server/event"
+import { Question } from "@/question"
+import { ConfigApi } from "./groups/config"
+import { ControlApi } from "./groups/control"
+import { ControlPlaneApi } from "./groups/control-plane"
+import { EventApi } from "./groups/event"
+import { ExperimentalApi } from "./groups/experimental"
+import { FileApi } from "./groups/file"
+import { InstanceApi } from "./groups/instance"
+import { McpApi } from "./groups/mcp"
+import { PermissionApi } from "./groups/permission"
+import { ProjectApi } from "./groups/project"
+import { ProjectCopyApi } from "./groups/project-copy"
+import { ProviderApi } from "./groups/provider"
+import { PtyApi, PtyConnectApi } from "./groups/pty"
+import { QuestionApi } from "./groups/question"
+import { SessionApi } from "./groups/session"
+import { SyncApi } from "./groups/sync"
+import { TuiApi } from "./groups/tui"
+import { WorkspaceApi } from "./groups/workspace"
+import { Api } from "@miaw/server/api"
+// GlobalEventSchema snapshots the registry after event-producing groups register their variants.
+import { GlobalApi } from "./groups/global"
+import { Authorization } from "./middleware/authorization"
+import { SchemaErrorMiddleware } from "./middleware/schema-error"
+
+const EventSchema = Schema.Union([
+  ...EventV2.registry
+    .values()
+    .map((definition) =>
+      Schema.Struct({
+        id: EventV2.ID,
+        type: Schema.Literal(definition.type),
+        properties: definition.data,
+      }).annotate({ identifier: `Event.${definition.type}` }),
+    )
+    .toArray(),
+  InstanceDisposed,
+]).annotate({ identifier: "Event" })
+
+export const RootHttpApi = HttpApi.make("miaw-root")
+  .addHttpApi(ControlApi)
+  .addHttpApi(ControlPlaneApi)
+  .addHttpApi(GlobalApi)
+  .middleware(SchemaErrorMiddleware)
+  .middleware(Authorization)
+
+export const InstanceHttpApi = HttpApi.make("miaw-instance")
+  .addHttpApi(ConfigApi)
+  .addHttpApi(ExperimentalApi)
+  .addHttpApi(FileApi)
+  .addHttpApi(InstanceApi)
+  .addHttpApi(McpApi)
+  .addHttpApi(ProjectApi)
+  .addHttpApi(ProjectCopyApi)
+  .addHttpApi(PtyApi)
+  .addHttpApi(QuestionApi)
+  .addHttpApi(PermissionApi)
+  .addHttpApi(ProviderApi)
+  .addHttpApi(SessionApi)
+  .addHttpApi(SyncApi)
+  .addHttpApi(TuiApi)
+  .addHttpApi(WorkspaceApi)
+  .middleware(SchemaErrorMiddleware)
+
+export const MiawHttpApi = HttpApi.make("miaw")
+  .addHttpApi(RootHttpApi)
+  .addHttpApi(EventApi)
+  .addHttpApi(InstanceHttpApi)
+  .addHttpApi(Api)
+  .addHttpApi(PtyConnectApi)
+  .annotate(HttpApi.AdditionalSchemas, [EventSchema, Question.Replied, Question.Rejected])
+
+export type RootHttpApiType = typeof RootHttpApi
+export type InstanceHttpApiType = typeof InstanceHttpApi