# 機能設計書 21-セッション作成

## 概要

本ドキュメントは、OpenCodeにおけるセッション作成機能の設計を定義する。セッションはユーザーとAIアシスタント間の会話を管理する基本単位であり、プロジェクト単位で管理される。

### 本機能の処理概要

セッション作成機能は、ユーザーがAIアシスタントとの新しい会話を開始する際に、セッションを生成し永続化する機能である。

**業務上の目的・背景**：AIコーディングアシスタントとの対話履歴を管理可能にし、作業の継続性と追跡可能性を確保する。複数の作業を並行して進める場合に、それぞれの文脈を独立して保持できるようにする。

**機能の利用シーン**：ユーザーが新しいコーディングタスクを開始する際、または既存のセッションから派生した子セッション（サブエージェント用）を作成する際に利用される。TUI、Web UI、デスクトップアプリなど複数のインターフェースから呼び出される。

**主要な処理内容**：
1. 一意なセッションIDとスラッグの生成
2. プロジェクト情報との関連付け
3. データベースへのセッション情報の永続化
4. セッション作成イベントの発行
5. 自動共有設定に基づく共有URL生成（オプション）

**関連システム・外部連携**：共有機能が有効な場合、opncd.aiへのAPI呼び出しが発生する。

**権限による制御**：セッション作成時に権限ルールセット（PermissionNext.Ruleset）を設定可能。親セッションを指定した場合、子セッションとして作成される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | セッション画面 | 主画面 | NewSessionViewコンポーネントによるセッション開始 |
| 4 | レイアウト | 遷移先機能 | サイドバーからセッションへのナビゲーション |
| 26 | セッション | 主画面 | ルートデータからのセッション同期 |

## 機能種別

データ登録処理（CREATE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| parentID | string | No | 親セッションのID（子セッション作成時） | session_で始まるIdentifier形式 |
| title | string | No | セッションタイトル | 省略時は自動生成 |
| permission | PermissionNext.Ruleset | No | 権限ルールセット | zodスキーマによる検証 |
| directory | string | Yes (内部) | 作業ディレクトリ | Instance.directoryから自動取得 |

### 入力データソース

- Instance.directory: 現在のプロジェクトの作業ディレクトリ
- Instance.project: 現在のプロジェクト情報
- Config: 共有設定（share: "auto" | "disabled"）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | セッションの一意識別子（session_プレフィックス付き） |
| slug | string | URLフレンドリーなスラッグ |
| projectID | string | 関連プロジェクトのID |
| directory | string | 作業ディレクトリパス |
| parentID | string? | 親セッションID（子セッションの場合） |
| title | string | セッションタイトル |
| version | string | OpenCodeのバージョン |
| time.created | number | 作成日時（UNIXタイムスタンプ） |
| time.updated | number | 更新日時（UNIXタイムスタンプ） |
| permission | PermissionNext.Ruleset? | 権限ルールセット |
| share | {url: string}? | 共有URL情報 |

### 出力先

- SQLiteデータベース（SessionTable）
- Busイベント（session.created、session.updated）
- 共有API（opncd.ai）（自動共有有効時）

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ zodスキーマによる型チェック

2. セッション情報の構築
   └─ ID生成（Identifier.descending）、スラッグ生成（Slug.create）

3. デフォルトタイトルの設定
   └─ 親セッションの有無に応じて"New session - "または"Child session - "プレフィックス

4. データベースへの挿入
   └─ SessionTableへのINSERT

5. イベント発行
   └─ Session.Event.Createdの発行

6. 自動共有の実行（条件付き）
   └─ Flag.OPENCODE_AUTO_SHAREまたはconfig.share === "auto"の場合

7. 更新イベント発行
   └─ Session.Event.Updatedの発行
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力パラメータ検証]
    B --> C[セッションID生成]
    C --> D[スラッグ生成]
    D --> E{親セッションあり?}
    E -->|Yes| F[子セッションタイトル設定]
    E -->|No| G[通常タイトル設定]
    F --> H[Session.Info構築]
    G --> H
    H --> I[DBにINSERT]
    I --> J[Createdイベント発行]
    J --> K{自動共有有効?}
    K -->|Yes| L[share関数呼び出し]
    K -->|No| M[Updatedイベント発行]
    L --> M
    M --> N[セッション情報返却]
    N --> O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-21-01 | デフォルトタイトル生成 | タイトル未指定時はISO8601形式の日時付きタイトルを自動生成 | title パラメータが未指定の場合 |
| BR-21-02 | 子セッションタイトル | 親セッション指定時は"Child session - "プレフィックスを使用 | parentIDが指定された場合 |
| BR-21-03 | 自動共有 | 設定で有効な場合、セッション作成時に自動的に共有URLを生成 | OPENCODE_AUTO_SHAREフラグまたはconfig.share === "auto" |
| BR-21-04 | 共有無効化 | config.share === "disabled"の場合は共有を行わない | 共有が無効化されている場合 |

### 計算ロジック

- セッションIDは降順ソート可能な形式で生成（Identifier.descending）
- タイムスタンプはDate.now()を使用

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| セッション作成 | session | INSERT | 新規セッションレコードの挿入 |

### テーブル別操作詳細

#### SessionTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | Identifier.descending("session")で生成 | 主キー |
| INSERT | project_id | Instance.project.id | 外部キー |
| INSERT | parent_id | input.parentID | 子セッションの場合のみ |
| INSERT | slug | Slug.create()で生成 | URLフレンドリーなスラッグ |
| INSERT | directory | input.directory | 作業ディレクトリ |
| INSERT | title | input.title または自動生成 | セッションタイトル |
| INSERT | version | Installation.VERSION | OpenCodeバージョン |
| INSERT | time_created | Date.now() | 作成日時 |
| INSERT | time_updated | Date.now() | 更新日時 |
| INSERT | permission | input.permission | 権限ルールセット（JSON） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | データベースエラー | SQLite書き込み失敗 | エラーログ出力、例外伝播 |
| - | 共有エラー | 共有API呼び出し失敗 | 静かに無視（catch内で抑制） |

### リトライ仕様

自動共有失敗時はリトライせず、エラーを静かに無視する（セッション作成自体は成功とする）。

## トランザクション仕様

Database.use()によるトランザクション管理。セッション挿入が成功した場合のみイベントが発行される（Database.effect）。

## パフォーマンス要件

- セッション作成は100ms以内に完了すること
- 自動共有はバックグラウンドで非同期実行

## セキュリティ考慮事項

- セッションIDは予測不可能な形式で生成
- 権限ルールセットによるツール実行制御が可能
- 共有URLは別途シークレットトークンで保護

## 備考

- セッションは削除時にCASCADE DELETEでメッセージとパーツも自動削除される
- 親セッション削除時は子セッションも再帰的に削除される

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、セッション情報のスキーマ定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | session.sql.ts | `packages/opencode/src/session/session.sql.ts` | SessionTableの定義、カラム構造、外部キー関係 |
| 1-2 | index.ts | `packages/opencode/src/session/index.ts` | Session.Info zodスキーマ（116-157行目） |

**読解のコツ**: drizzle-ormの`sqliteTable`関数でテーブル定義を行い、zodでAPIスキーマを定義している。両者の対応関係を理解する。

#### Step 2: エントリーポイントを理解する

処理の起点となる関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/opencode/src/session/index.ts` | Session.create関数（212-228行目） |

**主要処理フロー**:
1. **212-228行目**: create関数 - 入力パラメータをfnでラップしzodバリデーション
2. **220-227行目**: createNext関数への委譲

#### Step 3: コア処理を理解する

実際のセッション作成ロジックを読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/opencode/src/session/index.ts` | createNext関数（287-326行目） |

**主要処理フロー**:
- **294-307行目**: Session.Info オブジェクトの構築
- **295行目**: Identifier.descending によるID生成
- **296行目**: Slug.create によるスラッグ生成
- **301行目**: デフォルトタイトル生成
- **309-316行目**: データベースINSERTとイベント発行
- **318-321行目**: 自動共有の条件判定と実行

#### Step 4: 関連機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `packages/opencode/src/session/index.ts` | share関数（341-355行目）- 共有URL生成 |
| 4-2 | share-next.ts | `packages/opencode/src/share/share-next.ts` | ShareNext.create（69-93行目）- 外部APIとの連携 |

### プログラム呼び出し階層図

```
Session.create (public API)
    │
    └─ Session.createNext (internal)
           │
           ├─ Identifier.descending("session")
           │      └─ ID生成
           │
           ├─ Slug.create()
           │      └─ スラッグ生成
           │
           ├─ createDefaultTitle()
           │      └─ タイトル生成
           │
           ├─ Database.use()
           │      ├─ db.insert(SessionTable)
           │      └─ Database.effect()
           │             └─ Bus.publish(Event.Created)
           │
           └─ Session.share() [条件付き]
                  └─ ShareNext.create()
                         ├─ fetch (opncd.ai API)
                         └─ DB更新 (SessionShareTable)
```

### データフロー図

```
[入力]                    [処理]                         [出力]

parentID ───────┐
title ──────────┤                                    ┌─> Session.Info
permission ─────┼──▶ Session.createNext() ──────────┼─> DB (session)
directory ──────┤           │                        └─> Bus Events
                │           ├─ ID生成
Instance.       │           ├─ スラッグ生成
  project ──────┘           ├─ タイトル設定
                            └─ DB保存

Config.share ───────▶ 条件判定 ──▶ ShareNext.create() ──▶ share_url
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/opencode/src/session/index.ts` | ソース | セッション管理のメインモジュール |
| session.sql.ts | `packages/opencode/src/session/session.sql.ts` | ソース | データベーステーブル定義 |
| share-next.ts | `packages/opencode/src/share/share-next.ts` | ソース | 共有機能の実装 |
| id.ts | `packages/opencode/src/id/id.ts` | ソース | 識別子生成ユーティリティ |
| slug.ts | `@opencode-ai/util/slug` | ソース | スラッグ生成ユーティリティ |
| config.ts | `packages/opencode/src/config/config.ts` | ソース | 設定管理 |
| bus.ts | `packages/opencode/src/bus/index.ts` | ソース | イベントバス |
