> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript Types

> Core TypeScript types and interfaces used across T3 Code contracts

## Overview

The contracts package provides foundational TypeScript types and Effect schemas used throughout T3 Code. These types ensure type safety and validation across the client-server boundary.

## Base Schemas

### String Types

#### TrimmedString

A string that has leading and trailing whitespace removed.

```typescript theme={null}
import { Schema } from "effect";

export const TrimmedString = Schema.Trim;
```

#### TrimmedNonEmptyString

A trimmed string that must contain at least one character.

```typescript theme={null}
export const TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
```

### Numeric Types

#### NonNegativeInt

An integer greater than or equal to zero.

```typescript theme={null}
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
```

#### PositiveInt

An integer greater than or equal to one.

```typescript theme={null}
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
```

### DateTime Types

#### IsoDateTime

An ISO 8601 formatted datetime string.

```typescript theme={null}
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
```

## Branded Identifiers

Branded types provide type-safe identifiers that prevent mixing different ID types.

### Entity IDs

#### ThreadId

Unique identifier for a conversation thread.

```typescript theme={null}
export const ThreadId = makeEntityId("ThreadId");
export type ThreadId = typeof ThreadId.Type;
```

#### ProjectId

Unique identifier for a workspace project.

```typescript theme={null}
export const ProjectId = makeEntityId("ProjectId");
export type ProjectId = typeof ProjectId.Type;
```

#### CommandId

Unique identifier for a command in the event-sourced system.

```typescript theme={null}
export const CommandId = makeEntityId("CommandId");
export type CommandId = typeof CommandId.Type;
```

#### EventId

Unique identifier for a domain event.

```typescript theme={null}
export const EventId = makeEntityId("EventId");
export type EventId = typeof EventId.Type;
```

#### MessageId

Unique identifier for a message in a thread.

```typescript theme={null}
export const MessageId = makeEntityId("MessageId");
export type MessageId = typeof MessageId.Type;
```

#### TurnId

Unique identifier for a turn (user input + assistant response cycle).

```typescript theme={null}
export const TurnId = makeEntityId("TurnId");
export type TurnId = typeof TurnId.Type;
```

### Provider Runtime IDs

#### ProviderItemId

Identifier for a provider-specific item (e.g., a Codex conversation item).

```typescript theme={null}
export const ProviderItemId = makeEntityId("ProviderItemId");
export type ProviderItemId = typeof ProviderItemId.Type;
```

#### RuntimeSessionId

Identifier for a runtime session.

```typescript theme={null}
export const RuntimeSessionId = makeEntityId("RuntimeSessionId");
export type RuntimeSessionId = typeof RuntimeSessionId.Type;
```

#### RuntimeItemId

Identifier for a runtime item.

```typescript theme={null}
export const RuntimeItemId = makeEntityId("RuntimeItemId");
export type RuntimeItemId = typeof RuntimeItemId.Type;
```

#### RuntimeRequestId

Identifier for a runtime request.

```typescript theme={null}
export const RuntimeRequestId = makeEntityId("RuntimeRequestId");
export type RuntimeRequestId = typeof RuntimeRequestId.Type;
```

#### RuntimeTaskId

Identifier for a runtime task.

```typescript theme={null}
export const RuntimeTaskId = makeEntityId("RuntimeTaskId");
export type RuntimeTaskId = typeof RuntimeTaskId.Type;
```

#### ApprovalRequestId

Identifier for an approval request.

```typescript theme={null}
export const ApprovalRequestId = makeEntityId("ApprovalRequestId");
export type ApprovalRequestId = typeof ApprovalRequestId.Type;
```

#### CheckpointRef

Reference to a git checkpoint for rollback.

```typescript theme={null}
export const CheckpointRef = makeEntityId("CheckpointRef");
export type CheckpointRef = typeof CheckpointRef.Type;
```

## Provider Types

### ProviderKind

Supported AI provider types.

```typescript theme={null}
export const ProviderKind = Schema.Literal("codex");
export type ProviderKind = typeof ProviderKind.Type;
```

<Info>
  Currently, only Codex is supported. Additional providers may be added in the future.
</Info>

### Runtime Modes

#### RuntimeMode

Controls the level of access the provider has to the system.

```typescript theme={null}
export const RuntimeMode = Schema.Literals(["approval-required", "full-access"]);
export type RuntimeMode = typeof RuntimeMode.Type;

export const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
```

* `approval-required` - User must approve each tool call
* `full-access` - Provider can execute tools without approval

#### ProviderApprovalPolicy

Detailed approval policy configuration.

```typescript theme={null}
export const ProviderApprovalPolicy = Schema.Literals([
  "untrusted",
  "on-failure",
  "on-request",
  "never",
]);
export type ProviderApprovalPolicy = typeof ProviderApprovalPolicy.Type;
```

#### ProviderSandboxMode

File system access level for the provider.

```typescript theme={null}
export const ProviderSandboxMode = Schema.Literals([
  "read-only",
  "workspace-write",
  "danger-full-access",
]);
export type ProviderSandboxMode = typeof ProviderSandboxMode.Type;
```

### Interaction Modes

#### ProviderInteractionMode

Controls how the provider interacts with the user.

```typescript theme={null}
export const ProviderInteractionMode = Schema.Literals(["default", "plan"]);
export type ProviderInteractionMode = typeof ProviderInteractionMode.Type;

export const DEFAULT_PROVIDER_INTERACTION_MODE: ProviderInteractionMode = "default";
```

* `default` - Standard conversational mode
* `plan` - Provider proposes a plan before execution

### Service Tiers

#### ProviderServiceTier

Service tier for API requests.

```typescript theme={null}
export const ProviderServiceTier = Schema.Literals(["fast", "flex"]);
export type ProviderServiceTier = typeof ProviderServiceTier.Type;
```

### Approval Types

#### ProviderApprovalDecision

User's decision on an approval request.

```typescript theme={null}
export const ProviderApprovalDecision = Schema.Literals([
  "accept",
  "acceptForSession",
  "decline",
  "cancel",
]);
export type ProviderApprovalDecision = typeof ProviderApprovalDecision.Type;
```

* `accept` - Approve this specific request
* `acceptForSession` - Approve this and future similar requests in the session
* `decline` - Reject this request
* `cancel` - Cancel the entire turn

#### ProviderRequestKind

Type of request requiring approval.

```typescript theme={null}
export const ProviderRequestKind = Schema.Literals(["command", "file-read", "file-change"]);
export type ProviderRequestKind = typeof ProviderRequestKind.Type;
```

### Message Delivery

#### AssistantDeliveryMode

How assistant messages are delivered to the client.

```typescript theme={null}
export const AssistantDeliveryMode = Schema.Literals(["buffered", "streaming"]);
export type AssistantDeliveryMode = typeof AssistantDeliveryMode.Type;
```

## Chat Attachments

### ChatImageAttachment

An image attached to a chat message.

<ResponseField name="type" type="'image'" required>
  Attachment type discriminator
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique attachment ID (max 128 chars, alphanumeric with dashes/underscores)
</ResponseField>

<ResponseField name="name" type="string" required>
  File name (max 255 chars)
</ResponseField>

<ResponseField name="mimeType" type="string" required>
  MIME type starting with "image/" (max 100 chars)
</ResponseField>

<ResponseField name="sizeBytes" type="number" required>
  File size in bytes (max 10MB)
</ResponseField>

```typescript theme={null}
export const ChatImageAttachment = Schema.Struct({
  type: Schema.Literal("image"),
  id: ChatAttachmentId,
  name: TrimmedNonEmptyString.check(Schema.isMaxLength(255)),
  mimeType: TrimmedNonEmptyString.check(Schema.isMaxLength(100), Schema.isPattern(/^image\//i)),
  sizeBytes: NonNegativeInt.check(Schema.isLessThanOrEqualTo(PROVIDER_SEND_TURN_MAX_IMAGE_BYTES)),
});
export type ChatImageAttachment = typeof ChatImageAttachment.Type;
```

### ChatAttachment

Union of all attachment types.

```typescript theme={null}
export const ChatAttachment = Schema.Union([ChatImageAttachment]);
export type ChatAttachment = typeof ChatAttachment.Type;
```

## Git Types

### GitBranch

Represents a git branch with metadata.

<ResponseField name="name" type="string" required>
  Branch name
</ResponseField>

<ResponseField name="isRemote" type="boolean" optional>
  Whether this is a remote branch
</ResponseField>

<ResponseField name="remoteName" type="string" optional>
  Name of the remote (e.g., "origin")
</ResponseField>

<ResponseField name="current" type="boolean" required>
  Whether this is the currently checked out branch
</ResponseField>

<ResponseField name="isDefault" type="boolean" required>
  Whether this is the default branch (main/master)
</ResponseField>

<ResponseField name="worktreePath" type="string | null" required>
  Path to the worktree if this branch has one
</ResponseField>

```typescript theme={null}
export const GitBranch = Schema.Struct({
  name: TrimmedNonEmptyString,
  isRemote: Schema.optional(Schema.Boolean),
  remoteName: Schema.optional(TrimmedNonEmptyString),
  current: Schema.Boolean,
  isDefault: Schema.Boolean,
  worktreePath: TrimmedNonEmptyString.pipe(Schema.NullOr),
});
export type GitBranch = typeof GitBranch.Type;
```

### GitStackedAction

Git actions that can be performed in sequence.

```typescript theme={null}
export const GitStackedAction = Schema.Literals(["commit", "commit_push", "commit_push_pr"]);
export type GitStackedAction = typeof GitStackedAction.Type;
```

* `commit` - Create a commit
* `commit_push` - Create a commit and push
* `commit_push_pr` - Create a commit, push, and open a PR

## Project Types

### ProjectEntry

Represents a file or directory in a project.

<ResponseField name="path" type="string" required>
  Relative path from project root
</ResponseField>

<ResponseField name="kind" type="'file' | 'directory'" required>
  Entry type
</ResponseField>

<ResponseField name="parentPath" type="string" optional>
  Parent directory path
</ResponseField>

```typescript theme={null}
export const ProjectEntry = Schema.Struct({
  path: TrimmedNonEmptyString,
  kind: ProjectEntryKind,
  parentPath: Schema.optional(TrimmedNonEmptyString),
});
export type ProjectEntry = typeof ProjectEntry.Type;
```

## Editor Types

### EditorId

Supported code editors.

```typescript theme={null}
export const EditorId = Schema.Literals(["cursor", "vscode", "zed", "file-manager"]);
export type EditorId = typeof EditorId.Type;
```

### Editor Configuration

```typescript theme={null}
export const EDITORS = [
  { id: "cursor", label: "Cursor", command: "cursor" },
  { id: "vscode", label: "VS Code", command: "code" },
  { id: "zed", label: "Zed", command: "zed" },
  { id: "file-manager", label: "File Manager", command: null },
] as const;
```

## Usage Examples

### Creating Branded IDs

```typescript theme={null}
import { ThreadId, MessageId } from "@t3tools/contracts";
import { nanoid } from "nanoid";

const threadId: ThreadId = nanoid() as ThreadId;
const messageId: MessageId = nanoid() as MessageId;

// TypeScript prevents mixing ID types
function getMessage(id: MessageId) {
  // ...
}

getMessage(threadId); // Type error!
getMessage(messageId); // OK
```

### Validating with Effect Schema

```typescript theme={null}
import { Schema } from "effect";
import { TrimmedNonEmptyString, NonNegativeInt } from "@t3tools/contracts";

// Decode and validate
const result = Schema.decodeUnknownSync(TrimmedNonEmptyString)("  hello  ");
// result === "hello"

const count = Schema.decodeUnknownSync(NonNegativeInt)(5);
// count === 5

const invalid = Schema.decodeUnknownSync(NonNegativeInt)(-1);
// Throws ParseError
```

### Working with Chat Attachments

```typescript theme={null}
import { ChatImageAttachment } from "@t3tools/contracts";

const attachment: typeof ChatImageAttachment.Type = {
  type: "image",
  id: "img_abc123",
  name: "screenshot.png",
  mimeType: "image/png",
  sizeBytes: 1024 * 500, // 500KB
};
```

### Using Git Types

```typescript theme={null}
import { GitBranch, GitStackedAction } from "@t3tools/contracts";

const branch: typeof GitBranch.Type = {
  name: "feature/new-api",
  isRemote: false,
  current: true,
  isDefault: false,
  worktreePath: null,
};

const action: GitStackedAction = "commit_push_pr";
```

## Type Guards

Effect Schema provides runtime type guards:

```typescript theme={null}
import { Schema } from "effect";
import { RuntimeMode } from "@t3tools/contracts";

const isRuntimeMode = Schema.is(RuntimeMode);

isRuntimeMode("full-access"); // true
isRuntimeMode("invalid"); // false
```

## Related Types

See also:

* [Model Contracts](/api/contracts/models) - Model configuration types
* [Orchestration Schemas](/api/contracts/schemas) - Domain models and events