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 앱 책임이다.

빠른 시작

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

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

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

기본 사용 예:

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별 작업 규칙

조립 경계

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:

iop/apps/client
  -> iop_console_flutter
  -> agent_shell

NomadCode without IOP:

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

NomadCode with IOP:

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