# agent-shell

`agent-shell`은 Flutter 앱들이 공통으로 가져다 쓰는 embeddable agent interaction package다.
제품 앱이 아니며, IOP, NomadCode, OTO 같은 host가 각자의 capability pack을 붙일 수 있는 채팅형 agent shell과 domain model만 제공한다.

## 현재 상태

- Flutter package `agent_shell` scaffold가 준비되어 있다.
- `AgentShell`, message list, composer, tool call card, approval prompt 위젯을 제공한다.
- `AgentMessage`, `AgentToolCall`, `AgentCapability`, `AgentCommand`, `AgentEvent` 같은 제품 비종속 interface/model을 제공한다.
- backend transport, auth, endpoint, persistence, navigation, product-specific capability는 host 앱 책임이다.

## 빠른 시작

```bash
flutter pub get
flutter test
flutter analyze --no-fatal-infos
```

Host app에서 local path dependency로 사용할 때:

```yaml
dependencies:
  agent_shell:
    path: ../agent-shell
```

기본 사용 예:

```dart
AgentShell(
  messages: messages,
  busy: isRunning,
  onSubmit: (text) => agentRuntime.send(text),
  onToolAction: (action) => agentRuntime.handleToolAction(action),
)
```

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|
| 의존성 설치 | `flutter pub get` | `pubspec.yaml` 기준 |
| 테스트 | `flutter test` | widget test 포함 |
| 분석 | `flutter analyze --no-fatal-infos` | `analysis_options.yaml` 기준 |
| 포맷 확인 | `dart format --set-exit-if-changed lib test` | package 소스와 테스트 |

## 구조

| 경로 | 역할 |
|------|------|
| `lib/agent_shell.dart` | public export entrypoint |
| `lib/src/domain/` | 제품 비종속 message, tool call, command, event, capability model |
| `lib/src/widgets/` | embeddable agent UI primitives |
| `test/` | Flutter widget/model tests |
| `agent-ops/rules/project/rules.md` | 프로젝트 작업 규칙과 domain mapping |
| `agent-ops/rules/project/domain/` | domain별 작업 규칙 |

## 조립 경계

```text
agent_shell
  AgentShell widget
  AgentMessage / AgentToolCall models
  AgentCapability / AgentCommand / AgentEvent interfaces
  tool call and approval UI primitives

iop_console_flutter
  IOP-specific capability pack
  IOP Control Plane / Edge / Node integration

nomadcode_app
  NomadCode workbench shell
  NomadCode WebView/workflow capability pack
  optional IOP composition package
```

IOP standalone:

```text
iop/apps/client
  -> iop_console_flutter
  -> agent_shell
```

NomadCode without IOP:

```text
nomadcode/apps/client
  -> nomadcode workbench shell
  -> agent_shell
```

NomadCode with IOP:

```text
nomadcode optional composition layer
  -> nomadcode workbench shell
  -> iop_console_flutter
  -> agent_shell
```

IOP import는 optional composition layer에만 있어야 한다.
NomadCode 기본 빌드는 IOP package 없이도 성공해야 한다.

## 작업 맥락

- `lib/` 안에는 `runApp`, `MaterialApp`, Firebase/SystemChrome bootstrap을 넣지 않는다.
- 제품별 package를 import하지 않는다. IOP/NomadCode 연결은 각 제품의 capability pack 또는 optional composition layer에서 구현한다.
- Public API를 추가하면 `lib/agent_shell.dart` export와 이 README 예시를 함께 확인한다.
- UI는 좌측 rail, 우측 rail, center content, modal 등 다양한 host layout에 embedded될 수 있어야 한다.
- 자세한 작업 규칙은 `agent-ops/rules/project/rules.md`와 관련 domain rule을 먼저 확인한다.

## 환경 변수

이 package 자체가 요구하는 환경 변수는 없다.
endpoint, token, auth, persistence 설정은 host app이 주입한다.

## 참고 문서

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/domain-model/rules.md`
- `agent-ops/rules/project/domain/widgets/rules.md`