@neurocode-ai/protocol 1.18.9

package/src/groups/session.ts

@@ -0,0 +1,379 @@
+import { SessionMessage } from "@neurocode-ai/schema/session-message"
+import { SessionInput } from "@neurocode-ai/schema/session-input"
+import { PromptInput } from "@neurocode-ai/schema/prompt-input"
+import { Session } from "@neurocode-ai/schema/session"
+import { Project } from "@neurocode-ai/schema/project"
+import { AbsolutePath, NonNegativeInt, PositiveInt, RelativePath, statics } from "@neurocode-ai/schema/schema"
+import { Workspace } from "@neurocode-ai/schema/workspace"
+import { Context, Effect, Encoding, Result, Schema, Struct } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import {
+  ConflictError,
+  InvalidCursorError,
+  InvalidRequestError,
+  MessageNotFoundError,
+  ServiceUnavailableError,
+  SessionNotFoundError,
+  UnknownError,
+} from "../errors"
+import { Agent } from "@neurocode-ai/schema/agent"
+import { Model } from "@neurocode-ai/schema/model"
+import { Location } from "@neurocode-ai/schema/location"
+import { Revert } from "@neurocode-ai/schema/revert"
+import { SessionEvent } from "@neurocode-ai/schema/session-event"
+
+const SessionsQueryFields = {
+  workspace: Workspace.ID.pipe(Schema.optional),
+  limit: Schema.NumberFromString.pipe(Schema.decodeTo(PositiveInt), Schema.optional).annotate({
+    description: "Maximum number of sessions to return. Defaults to the newest 50 sessions.",
+  }),
+  order: Schema.optional(Schema.Union([Schema.Literal("asc"), Schema.Literal("desc")])).annotate({
+    description: "Session order for the first page. Use desc for newest first or asc for oldest first.",
+  }),
+  search: Schema.optional(Schema.String),
+}
+
+const SessionsDirectoryQuery = Schema.Struct({
+  ...SessionsQueryFields,
+  directory: AbsolutePath,
+})
+
+const SessionsProjectQuery = Schema.Struct({
+  ...SessionsQueryFields,
+  project: Project.ID,
+  subpath: RelativePath.pipe(Schema.optional),
+})
+
+const SessionsAllQuery = Schema.Struct(SessionsQueryFields)
+
+const withCursor = <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) =>
+  schema.mapFields((fields) => ({
+    ...Struct.omit(fields, ["limit"]),
+    anchor: Session.ListAnchor,
+  }))
+
+const SessionsCursorInput = Schema.Union([
+  withCursor(SessionsDirectoryQuery),
+  withCursor(SessionsProjectQuery),
+  withCursor(SessionsAllQuery),
+])
+const SessionsCursorJson = Schema.fromJsonString(SessionsCursorInput)
+const encodeSessionsCursor = Schema.encodeSync(SessionsCursorJson)
+const decodeSessionsCursor = Schema.decodeUnknownEffect(SessionsCursorJson)
+const invalidCursor = "Invalid cursor" as const
+
+export const SessionsCursor = Schema.String.pipe(
+  Schema.brand("SessionsCursor"),
+  statics((schema) => {
+    const make = schema.make.bind(schema)
+    return {
+      make: (input: typeof SessionsCursorInput.Type) => make(Encoding.encodeBase64Url(encodeSessionsCursor(input))),
+      parse: (input: string) =>
+        Effect.suspend(() => {
+          const result = Encoding.decodeBase64UrlString(input)
+          return Result.isFailure(result)
+            ? Effect.fail(invalidCursor)
+            : decodeSessionsCursor(result.success).pipe(Effect.mapError(() => invalidCursor))
+        }),
+    }
+  }),
+)
+export type SessionsCursor = typeof SessionsCursor.Type
+
+const SessionActive = Schema.Struct({
+  type: Schema.Literal("running"),
+}).annotate({ identifier: "SessionActive" })
+
+const SessionHistoryLimit = PositiveInt.check(Schema.isLessThanOrEqualTo(100))
+
+export const SessionHistoryQuery = Schema.Struct({
+  limit: Schema.NumberFromString.pipe(Schema.decodeTo(SessionHistoryLimit), Schema.optional),
+  after: Schema.NumberFromString.pipe(Schema.decodeTo(NonNegativeInt), Schema.optional),
+})
+
+const SessionsQueryCursor = SessionsCursor.annotate({
+  description: "Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.",
+})
+
+export const SessionsQuery = Schema.Struct({
+  ...SessionsQueryFields,
+  directory: AbsolutePath.pipe(Schema.optional),
+  project: Project.ID.pipe(Schema.optional),
+  subpath: RelativePath.pipe(Schema.optional),
+  cursor: SessionsQueryCursor.pipe(Schema.optional),
+}).annotate({ identifier: "SessionsQuery" })
+
+export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLocationMiddleware: Context.Key<I, S>) =>
+  HttpApiGroup.make("server.session")
+    .add(
+      HttpApiEndpoint.get("session.list", "/api/session", {
+        query: SessionsQuery,
+        success: Schema.Struct({
+          data: Schema.Array(Session.Info),
+          cursor: Schema.Struct({
+            previous: SessionsCursor.pipe(Schema.optional),
+            next: SessionsCursor.pipe(Schema.optional),
+          }),
+        }).annotate({ identifier: "SessionsResponse" }),
+        error: [InvalidCursorError, InvalidRequestError],
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.session.list",
+          summary: "List sessions",
+          description:
+            "Retrieve sessions in the requested order. Items keep that order across pages; use cursor.next or cursor.previous to move through the ordered list.",
+        }),
+      ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.create", "/api/session", {
+        payload: Schema.Struct({
+          id: Session.ID.pipe(Schema.optional),
+          agent: Agent.ID.pipe(Schema.optional),
+          model: Model.Ref.pipe(Schema.optional),
+          location: Location.Ref.pipe(Schema.optional),
+        }),
+        success: Schema.Struct({ data: Session.Info }),
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.session.create",
+          summary: "Create session",
+          description: "Create a session at the requested location.",
+        }),
+      ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.active", "/api/session/active", {
+        success: Schema.Struct({ data: Schema.Record(Session.ID, SessionActive) }),
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.session.active",
+          summary: "List active sessions",
+          description:
+            "Retrieve foreground Session drains currently owned by this OpenCode process. Sessions absent from the result are inactive.",
+        }),
+      ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.get", "/api/session/:sessionID", {
+        params: { sessionID: Session.ID },
+        success: Schema.Struct({ data: Session.Info }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.get",
+            summary: "Get session",
+            description: "Retrieve a session by ID.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.switchAgent", "/api/session/:sessionID/agent", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({ agent: Agent.ID }),
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.switchAgent",
+            summary: "Switch session agent",
+            description: "Switch the agent used by subsequent provider turns.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.switchModel", "/api/session/:sessionID/model", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({ model: Model.Ref }),
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.switchModel",
+            summary: "Switch session model",
+            description: "Switch the model used by subsequent provider turns.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.prompt", "/api/session/:sessionID/prompt", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({
+          id: SessionMessage.ID.pipe(Schema.optional),
+          prompt: PromptInput.Prompt,
+          delivery: SessionInput.Delivery.pipe(Schema.optional),
+          resume: Schema.Boolean.pipe(Schema.optional),
+        }),
+        success: Schema.Struct({ data: SessionInput.Admitted }),
+        error: [ConflictError, SessionNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.prompt",
+            summary: "Send message",
+            description: "Durably admit one session input and schedule agent-loop execution unless resume is false.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.compact", "/api/session/:sessionID/compact", {
+        params: { sessionID: Session.ID },
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, ServiceUnavailableError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.compact",
+            summary: "Compact session",
+            description: "Compact a session conversation.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.wait", "/api/session/:sessionID/wait", {
+        params: { sessionID: Session.ID },
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, ServiceUnavailableError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.wait",
+            summary: "Wait for session",
+            description: "Wait for a session agent loop to become idle.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.revert.stage", "/api/session/:sessionID/revert/stage", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({ messageID: SessionMessage.ID, files: Schema.Boolean.pipe(Schema.optional) }),
+        success: Schema.Struct({ data: Revert.State }),
+        error: [MessageNotFoundError, SessionNotFoundError, UnknownError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.revert.stage",
+            summary: "Stage session revert",
+            description: "Stage or move a reversible session boundary and optionally apply its file changes.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.revert.clear", "/api/session/:sessionID/revert/clear", {
+        params: { sessionID: Session.ID },
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, UnknownError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(OpenApi.annotations({ identifier: "v2.session.revert.clear", summary: "Clear staged revert" })),
+    )
+    .add(
+      HttpApiEndpoint.post("session.revert.commit", "/api/session/:sessionID/revert/commit", {
+        params: { sessionID: Session.ID },
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({ identifier: "v2.session.revert.commit", summary: "Commit staged revert" }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.context", "/api/session/:sessionID/context", {
+        params: { sessionID: Session.ID },
+        success: Schema.Struct({ data: Schema.Array(SessionMessage.Message) }),
+        error: [SessionNotFoundError, UnknownError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.context",
+            summary: "Get session context",
+            description: "Retrieve the active context messages for a session (all messages after the last compaction).",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.history", "/api/session/:sessionID/history", {
+        params: { sessionID: Session.ID },
+        query: SessionHistoryQuery,
+        success: Schema.Struct({
+          data: Schema.Array(SessionEvent.Durable),
+          hasMore: Schema.Boolean,
+        }).annotate({ identifier: "SessionHistory" }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.history",
+            summary: "Get session history",
+            description:
+              "Read one finite page of public durable Session events after an exclusive aggregate sequence. Newly committed events may appear on later pages.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.events", "/api/session/:sessionID/event", {
+        params: { sessionID: Session.ID },
+        query: {
+          after: Schema.NumberFromString.pipe(Schema.decodeTo(NonNegativeInt), Schema.optional),
+        },
+        success: HttpApiSchema.StreamSse({ data: SessionEvent.Durable }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.events",
+            summary: "Subscribe to session events",
+            description: "Replay durable events after an aggregate sequence, then continue with new durable events.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.interrupt", "/api/session/:sessionID/interrupt", {
+        params: { sessionID: Session.ID },
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.interrupt",
+            summary: "Interrupt session execution",
+            description: "Interrupt active execution owned by this OpenCode process. Idle interruption is a no-op.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.message", "/api/session/:sessionID/message/:messageID", {
+        params: { sessionID: Session.ID, messageID: SessionMessage.ID },
+        success: Schema.Struct({ data: SessionMessage.Message }),
+        error: [SessionNotFoundError, MessageNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.message",
+            summary: "Get session message",
+            description: "Retrieve one projected message owned by the Session.",
+          }),
+        ),
+    )
+    .annotateMerge(
+      OpenApi.annotations({
+        title: "sessions",
+        description: "Experimental session routes.",
+      }),
+    )

package/src/groups/skill.ts

@@ -0,0 +1,27 @@
+import { Skill } from "@neurocode-ai/schema/skill"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const SkillGroup = HttpApiGroup.make("server.skill")
+  .add(
+    HttpApiEndpoint.get("skill.list", "/api/skill", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Skill.Info)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.skill.list",
+          summary: "List skills",
+          description: "Retrieve currently registered skills.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "skills",
+      description: "Experimental skill routes.",
+    }),
+  )

package/src/middleware/authorization.ts

@@ -0,0 +1,6 @@
+import { HttpApiMiddleware } from "effect/unstable/httpapi"
+import { UnauthorizedError } from "../errors"
+
+export class Authorization extends HttpApiMiddleware.Service<Authorization>()("@neurocode/HttpApiAuthorization", {
+  error: UnauthorizedError,
+}) {}

package/src/middleware/schema-error.ts

@@ -0,0 +1,7 @@
+import { HttpApiMiddleware } from "effect/unstable/httpapi"
+import { InvalidRequestError } from "../errors"
+
+export class SchemaErrorMiddleware extends HttpApiMiddleware.Service<SchemaErrorMiddleware>()(
+  "@neurocode/HttpApiSchemaError",
+  { error: InvalidRequestError },
+) {}

package/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/test/session-cursor.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Schema } from "effect"
+import { SessionHistoryQuery, SessionsCursor } from "../src/groups/session"
+import { Session } from "@neurocode-ai/schema/session"
+
+describe("SessionsCursor", () => {
+  test("round trips without Node globals", async () => {
+    const input = {
+      workspace: undefined,
+      search: "protocol",
+      order: "desc" as const,
+      anchor: { id: Session.ID.make("ses_test"), time: 1, direction: "next" as const },
+    }
+    const cursor = SessionsCursor.make(input)
+
+    expect(await Effect.runPromise(SessionsCursor.parse(cursor))).toEqual(input)
+  })
+})
+
+describe("SessionHistoryQuery", () => {
+  test("decodes numeric paging inputs", async () => {
+    const query = await Effect.runPromise(Schema.decodeUnknownEffect(SessionHistoryQuery)({ after: "3", limit: "10" }))
+
+    expect(query).toEqual({ after: 3, limit: 10 })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@tsconfig/bun/tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "noUncheckedIndexedAccess": false
+  }
+}