Coding Standards

// data-analysis.ts
export function getSandbox() {
  // ...
}

// data-analysis.ts
export function getDataAnalysisSandbox() {
  // ...
}

const DATABASE_URL = process.env.DATABASE_URL;

if (!DATABASE_URL) {
  throw createError({
    status: 500,
    message: "DATABASE_URL is required",
    why: "DATABASE_URL was not set in the environment",
    fix: "Set DATABASE_URL before starting the service",
  });
}

const DATABASE_URL =
  process.env.DATABASE_URL ??
  process.env.LEGACY_DATABASE_URL ??
  "postgres://localhost:5432/app";

async function readOnlyQuery({ db, query }) {
  const result = await db.explainQuery({ query });

  if (result.statementType !== "SELECT") {
    // throw structured error
  }

  return query;
}

function readOnlyQuery(query) {
  const sql = String(query).trim().replace(/;+\s*$/, "");
  if (!/^(select|with|explain)\b/i.test(sql)) throw new Error("read only only");
  if (/\b(insert|update|delete|drop|alter|create)\b/i.test(sql)) throw new Error("mutating sql");
  return sql;
}

/**
 * Parse an email address from untrusted input.
 *
 * The input is trimmed and lower-cased before validation. Construct values
 * only through this function; the brand makes raw strings unusable where an
 * {@link EmailAddress} is required.
 *
 * @param input - The untrusted string to parse.
 * @returns A parsed {@link EmailAddress}, or {@link InvalidEmailAddress} when
 *   the input is invalid.
 */
export function parse(input: string): Result<EmailAddress, InvalidEmailAddress> {
  // ...
}

/** Input required to evaluate a boolean flag for a single user. */
export type BooleanFlagInput = {
  /** The feature flag key to evaluate. */
  readonly flagKey: string;
  /** The user's email, used as both context key and email attribute. */
  readonly userEmail: string;
  /** The value returned when the flag cannot be evaluated. */
  readonly defaultValue: boolean;
};

/**
 * Parses input.
 *
 * @inheritDoc
 * @param input - string
 * @returns Result<EmailAddress, InvalidEmailAddress>
 */
export function parse(input: string): Result<EmailAddress, InvalidEmailAddress> {
  // ...
}

export type BooleanFlagInput = {
  readonly flagKey: string;
  readonly userEmail: string;
  readonly defaultValue: boolean;
};

/**
 * Context window of {@link MODEL_ID}. Declared here because this model is
 * unlisted in the gateway catalog, so the build cannot resolve compaction
 * metadata. Keep it in sync when the model changes.
 * See https://example.com/docs/agent-config
 */
export const MODEL_CONTEXT_WINDOW_TOKENS = 1_000_000;

export const MODEL_CONTEXT_WINDOW_TOKENS = 1_000_000;

/**
 * Terminal assistant message held until the turn ends.
 *
 * `message.completed` fires inside the step that produced it, before that
 * step's `step.completed` reports usage. Posting there would render a footer
 * whose cost is always missing on a single-step turn, so delivery waits for
 * `turn.completed`. See https://example.com/docs/sessions
 */
const pendingChannelResponse = defineState<PendingChannelResponse | null>(
  "my-agent.pending-channel-response",
  () => null,
);

const pendingChannelResponse = defineState<PendingChannelResponse | null>(
  "my-agent.pending-channel-response",
  () => null,
);