import { Query, type UnwrapPlan } from "@distilled.cloud/core/query";
import {
Railway,
type CloudAgent as RailwayCloudAgent,
type CloudAgentStatus,
} from "@distilled.cloud/railway";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { waitUntilDeleted } from "./GraphQL.ts";
import { createRailwayName, matchesAlchemyPhysicalName, sanitizeRailwayName } from "./Metadata.ts";
import { ownedProjects, projectEnvironmentIds } from "./Project.ts";
import type { Providers } from "./Providers.ts";
const agentFields = <E>(agent: Query<RailwayCloudAgent, E>) => ({
id: agent.id,
name: agent.name,
environmentId: agent.environmentId,
projectId: agent.projectId,
status: agent.status,
domain: agent.domain,
domains: agent.domains.pipe(
Query.map((item) => ({ domain: item.domain, port: item.port, prefix: item.prefix })),
),
consoleTargetId: agent.consoleTargetId,
createdAt: agent.createdAt,
});
type CloudRow = UnwrapPlan<ReturnType<typeof agentFields>>;
/**
* A resource-valued prop: the resource itself, or an Effect that produces
* it (so `yield* Project(...)` and `Project(...)` both type-check).
*/
type Ref<T> = T | Effect.Effect<T, never, Providers>;
/**
* Environment identity a cloud agent is created in. Accepts a
* `Railway.Project` (its primary environment), a `Railway.Environment`,
* or an `{ environmentId }` stub.
*/
export type CloudAgentEnvironment = { readonly environmentId: string; readonly projectId?: string };
export interface CloudAgentProps {
/**
* Environment the agent VM lives in. Accepts a `Railway.Project`
* (primary environment), a `Railway.Environment`, or `{ environmentId }`.
* Changing it replaces the agent.
*/
environment: Ref<CloudAgentEnvironment>;
/**
* Agent name. Unique per environment for this user. If omitted, a
* unique name is generated from the stack, stage and logical ID.
* Changing it replaces the agent — Railway has no rename API.
*/
name?: string;
/**
* Variables written to the agent at create time. Values may be
* Railway reference templates (`Railway.ref(...)`). Create-only;
* ignored on update. Never persisted in attributes.
*/
variables?: Record<string, string>;
}
export type CloudAgent = Resource<
"Railway.CloudAgent",
CloudAgentProps,
{
/** Railway cloud agent id. */
cloudAgentId: string;
/** Physical agent name. */
name: string;
/** Environment the agent lives in. */
environmentId: string;
/** Parent Railway project id. */
projectId: string;
/** Observed lifecycle status (`STARTING`, `RUNNING`, `SLEEPING`, …). */
status: CloudAgentStatus;
/**
* Public hostname serving port 8080. Stable across sleep and wake;
* `undefined` while the machine is asleep.
*/
domain: string | undefined;
/** Every public domain on the machine, one per port. */
domains: ReadonlyArray<{ domain: string; port: number; prefix: string }>;
/** Console / exec target id. `undefined` while unavailable. */
consoleTargetId: string | undefined;
/** RFC3339 creation timestamp. */
createdAt: string;
},
never,
Providers
>;
/**
* A Railway.CloudAgent is a persistent coding-agent VM in an
* environment. Sleep keeps the disk; wake re-runs the entrypoint.
* Cloud agents are Priority Boarding and bill at VM rates while
* running.
*
* @see https://docs.railway.com/cloud-agents
*
* ### Create a CloudAgent
* Pass the Project (or an Environment). Alchemy generates a unique
* name unless you pass one. `domain` is the public URL for port 8080.
*
* **Example:** Next to a Project
* ```typescript
* const site = yield* Railway.Project("Site");
* const agent = yield* Railway.CloudAgent("Coder", {
* environment: site,
* });
* ```
*
* :::caution[Changing `environment` or `name` replaces the agent]
* Railway has no cloud-agent update API. A new VM is created, then
* the old one is deleted — the disk is not copied.
* :::
*
* ### A stable name
* Pass `name` when you need a stable agent name. Changing it later
* replaces the agent.
*
* **Example:** Explicit name
* ```typescript
* const agent = yield* Railway.CloudAgent("Coder", {
* environment: site,
* name: "reviews",
* });
* ```
*
* ### Variables
* `variables` are create-only. Pair them with a new agent — Railway
* does not update variables on an existing VM. Values may reference
* other services via `Railway.ref`.
*
* **Example:** Variables at create
* ```typescript
* const agent = yield* Railway.CloudAgent("Coder", {
* environment: site,
* variables: {
* DATABASE_URL: Railway.ref(db, "DATABASE_URL"),
* },
* });
* ```
*
* ### Sleep and wake
* Sleep stops compute billing and keeps the disk. Wake re-runs the
* entrypoint with files in place. These are not reconciler steps —
* call {@link sleepCloudAgent} / {@link wakeCloudAgent}.
*
* **Example:** Sleep then wake
* ```typescript
* yield* Railway.sleepCloudAgent(agent);
* yield* Railway.wakeCloudAgent(agent);
* ```
*
* ### Module-scope declarations
* Resource-valued props accept the resource or an Effect producing it.
*
* **Example:** Module-scope CloudAgent
* ```typescript
* // src/agent.ts
* import * as Railway from "@alchemy.run/railway";
*
* export const Site = Railway.Project("Site");
* export const Coder = Railway.CloudAgent("Coder", {
* environment: Site,
* });
* ```
*
* @resource
* @product Cloud Agent
*/
export const CloudAgent = Resource<CloudAgent>("Railway.CloudAgent");
export class CloudAgentNotCreated extends Data.TaggedError("Railway.CloudAgentNotCreated")<{
resourceName: string;
environmentId: string;
}> {}
export class CloudAgentEnvironmentRequired extends Data.TaggedError(
"Railway.CloudAgentEnvironmentRequired",
)<{ message: string }> {}
const toAttrs = (
agent: CloudRow,
fallback?: { name?: string; environmentId?: string; projectId?: string },
): CloudAgent["Attributes"] => ({
cloudAgentId: agent.id,
name: agent.name || fallback?.name || "",
environmentId: agent.environmentId || fallback?.environmentId || "",
projectId: agent.projectId || fallback?.projectId || "",
status: agent.status,
domain: agent.domain ?? undefined,
domains: agent.domains.map((item) => ({
domain: item.domain,
port: item.port,
prefix: item.prefix,
})),
consoleTargetId: agent.consoleTargetId ?? undefined,
createdAt: agent.createdAt,
});
const resolveName = (id: string, name: string | undefined, existing?: string) =>
Effect.gen(function* () {
if (name !== undefined) return sanitizeRailwayName(name);
if (existing !== undefined) return existing;
return yield* createRailwayName(id);
});
const isGone = (agent: CloudRow | undefined) => agent === undefined || agent.status === "DELETING";
const environmentIdOf = (value: unknown): string | undefined => {
if (value === null || typeof value !== "object") return undefined;
const rec = value as { environmentId?: unknown };
return typeof rec.environmentId === "string" && rec.environmentId.length > 0
? rec.environmentId
: undefined;
};
const projectIdOf = (value: unknown): string | undefined => {
if (value === null || typeof value !== "object") return undefined;
const rec = value as { projectId?: unknown };
return typeof rec.projectId === "string" && rec.projectId.length > 0 ? rec.projectId : undefined;
};
const cloudAgents = Query.fn((environmentId: string) =>
Railway.cloudAgents({ environmentId, mine: true }).pipe(Query.map(agentFields)),
);
const listAgents = (environmentId: string) =>
cloudAgents(environmentId).pipe(
Effect.catchTag(["RailwayForbidden", "RailwayPlanLimitExceeded"], () =>
Effect.succeed([] as CloudRow[]),
),
);
const cloudAgentCreate = Query.fn(
(input: { environmentId: string; name: string; variables?: Record<string, string> }) =>
agentFields(Railway.cloudAgentCreate({ input })),
);
const cloudAgentSleep = Query.fn((id: string) => agentFields(Railway.cloudAgentSleep({ id })));
const cloudAgentWake = Query.fn((id: string) => agentFields(Railway.cloudAgentWake({ id })));
const cloudAgentDelete = Query.fn((id: string) => Railway.cloudAgentDelete({ id }));
const findById = (environmentId: string, id: string) =>
listAgents(environmentId).pipe(Effect.map((items) => items.find((agent) => agent.id === id)));
const findByName = (environmentId: string, name: string) =>
listAgents(environmentId).pipe(
Effect.map((items) => items.find((agent) => !isGone(agent) && agent.name === name)),
);
const waitUntilGone = (environmentId: string, cloudAgentId: string) =>
waitUntilDeleted(
"CloudAgent",
cloudAgentId,
findById(environmentId, cloudAgentId).pipe(Effect.map((agent) => isGone(agent))),
);
const cloudAgentIdOf = (agent: { readonly cloudAgentId: string } | string): string =>
typeof agent === "string" ? agent : agent.cloudAgentId;
/**
* Sleep a running cloud agent. Compute billing stops; the disk is
* kept. Waking re-runs the entrypoint.
*/
export const sleepCloudAgent = Effect.fn(function* (
agent: { readonly cloudAgentId: string } | string,
) {
return yield* cloudAgentSleep(cloudAgentIdOf(agent));
});
/**
* Wake a sleeping cloud agent. Crashed or failed agents cannot be
* woken — create a new one instead.
*/
export const wakeCloudAgent = Effect.fn(function* (
agent: { readonly cloudAgentId: string } | string,
) {
return yield* cloudAgentWake(cloudAgentIdOf(agent));
});
export const CloudAgentProvider = () =>
Provider.succeed(CloudAgent, {
stables: ["cloudAgentId", "environmentId", "projectId", "createdAt"],
nuke: { dependsOn: ["Railway.Project"] },
diff: Effect.fn(function* ({ news, output }) {
if (news === undefined || !isResolved(news)) return undefined;
if (output === undefined) return undefined;
const nextEnvironmentId = environmentIdOf(news.environment);
const environmentChanged =
nextEnvironmentId !== undefined && nextEnvironmentId !== output.environmentId;
const nameChanged = news.name !== undefined && sanitizeRailwayName(news.name) !== output.name;
if (environmentChanged || nameChanged) {
return { action: "replace" as const };
}
return undefined;
}),
read: Effect.fn(function* ({ id, olds, output }) {
const name = yield* resolveName(id, olds?.name, output?.name);
const environmentId =
output?.environmentId ??
(olds !== undefined ? environmentIdOf(olds.environment) : undefined);
if (environmentId === undefined) return undefined;
const found =
(output?.cloudAgentId !== undefined
? yield* findById(environmentId, output.cloudAgentId)
: undefined) ?? (yield* findByName(environmentId, name));
if (found === undefined || isGone(found)) return undefined;
const attrs = toAttrs(found, {
name,
environmentId,
projectId:
output?.projectId ?? (olds !== undefined ? projectIdOf(olds.environment) : undefined),
});
if (output !== undefined) return attrs;
return matchesAlchemyPhysicalName(found.name) ? attrs : Unowned(attrs);
}),
list: Effect.fn(function* () {
const projects = yield* ownedProjects();
const rows = yield* Effect.forEach(projects, (project) =>
Effect.gen(function* () {
const envIds = yield* projectEnvironmentIds(project);
const nested = yield* Effect.forEach(envIds, (environmentId) =>
listAgents(environmentId).pipe(
Effect.map((agents) =>
agents
.filter((agent) => !isGone(agent) && matchesAlchemyPhysicalName(agent.name))
.map((agent) => toAttrs(agent, { environmentId, projectId: project.projectId })),
),
),
);
return nested.flat();
}),
);
const seen = new Set<string>();
const unique: CloudAgent["Attributes"][] = [];
for (const row of rows.flat()) {
if (seen.has(row.cloudAgentId)) continue;
seen.add(row.cloudAgentId);
unique.push(row);
}
return unique;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const props = news ?? ({} as CloudAgentProps);
const environmentId = environmentIdOf(props.environment) ?? output?.environmentId;
if (environmentId === undefined) {
return yield* new CloudAgentEnvironmentRequired({
message: "CloudAgent requires a resolved Railway.Project or Railway.Environment",
});
}
const name = yield* resolveName(id, props.name, output?.name);
const projectId = projectIdOf(props.environment) ?? output?.projectId ?? "";
let current =
output?.cloudAgentId !== undefined
? yield* findById(environmentId, output.cloudAgentId)
: undefined;
if (current === undefined || isGone(current)) {
current = yield* findByName(environmentId, name);
}
if (current === undefined || isGone(current)) {
const created = yield* cloudAgentCreate({
environmentId,
name,
...(props.variables !== undefined ? { variables: props.variables } : {}),
}).pipe(Effect.catchTag("RailwayValidationError", () => Effect.undefined));
current =
created !== undefined && !isGone(created)
? created
: yield* findByName(environmentId, name);
}
if (current === undefined || isGone(current)) {
return yield* new CloudAgentNotCreated({ resourceName: name, environmentId });
}
return toAttrs(current, { name, environmentId, projectId });
}),
delete: Effect.fn(function* ({ output }) {
const cloudAgentId = output.cloudAgentId;
if (cloudAgentId.length === 0) return;
yield* cloudAgentDelete(cloudAgentId);
if (output.environmentId.length > 0) {
yield* waitUntilGone(output.environmentId, cloudAgentId);
}
}),
});