권한, 설정, 저장소, 알림

권한 목록

Manifest는 요청 가능한 최대 권한, capability와 UI extension은 실제 필요한 부분집합을 선언합니다. 사용자가 허용하지 않은 권한은 runtime에서 다시 차단됩니다. 화면을 볼 수 있다는 사실과 작업 권한은 동일하지 않습니다.

Settings

Settings는 default Instance에 저장되는 작은 사용자 환경설정입니다. UI Runtime state를 유지하려면 initial_state에 key를 선언하고 해당 control 또는 set_state에 persist: true를 사용합니다.

적합한 값:

• 기본 기간, 정렬 방식, 표시 옵션
• 알림 on/off와 사용자 선택 시간
• 공개 school code처럼 민감하지 않은 외부 식별자

저장하면 안 되는 값:

• OAuth access/refresh token, API key
• 파일 원문이나 큰 목록
• 다른 플러그인의 설정
• 서버가 검증하지 않은 실행 코드

Settings 전체는 32 KiB 이하입니다. UI state의 client 저장 경계는 더 작을 수 있으므로 화면에 필요한 최소 key만 유지합니다.

Plugin Local Storage

storage는 사용자·Installation·Instance·namespace로 격리됩니다. 문자열, 숫자, boolean, JSON과 목록을 저장하며 package가 업데이트되어도 정책에 따라 유지됩니다. generation이 바뀐 오래된 실행은 새 상태를 쓸 수 없습니다.

삭제 시 data_policy가 일반 storage의 purge 또는 retain을 정합니다. credential, OAuth state, pending Host action은 별도 보안 수명주기를 따르며 일반 storage retention으로 보존하지 않습니다.

ai_storage는 설치/설정에서 한 번 허용한 뒤 매 CRUD 승인을 반복하지 않습니다. 그래도 Host는 현재 사용자·활성 Instance·허용 namespace와 read/read_write 범위를 매 호출 확인합니다. Manifest, CRUD 인자, quota, migration, 오류와 초기화는 Plugin Local Storage와 AI 접근을 참고하세요.

Network

외부 통신은 http_json, mcp_http, 지원되는 Host adapter를 통과합니다.

• 공개 HTTPS만 허용
• redirect 비허용
• DNS/IP와 SSRF 정책 적용
• Connector timeout 최대 30초
• retry 최대 4회
• Instance별 rate limit
• credential은 Host가 요청 직전에 주입

endpoint, Authorization header, secret을 UI state나 capability 결과에 복사하지 않습니다.

Capability 결과 URL을 image 또는 avatar에 표시하는 경우에도 같은 권한 경계를 사용합니다. Manifest의 network 요청과 활성 Instance의 network grant가 모두 필요합니다. Flutter 앱은 외부 이미지를 직접 요청하지 않고 인증된 Host proxy를 호출하며, Host가 public HTTPS·SSRF·redirect·이미지 형식·512 KiB·4096 px·16 MP 제한을 적용합니다. 선언과 상세 제한은 UI Runtime v2, endpoint는 수명주기와 HTTP API를 참고하세요.

Notification Host action

Capability 결과의 data.host_actions는 Host가 서버에서 다시 확인하고 durable outbox에 기록합니다. 알림을 직접 OS API로 호출하지 않습니다.

{
  "type": "schedule_notification",
  "id": 41001,
  "key": "school_life:morning:2026-08-14",
  "title": "내일 학교 일정",
  "body": "1교시는 수학입니다.",
  "at_millis": 1786640400000,
  "category": "reminder",
  "visibility": "private",
  "silent": false,
  "actions": [
    {"id": "done", "type": "check", "label": "완료", "capability": "school_life.task.complete", "arguments": {"task_id": "42"}},
    {"id": "later", "type": "snooze", "label": "10분 후", "minutes": 10},
    {"id": "open", "type": "open_plugin", "label": "학교 생활", "target": "school_life.dashboard"},
    {"id": "reply", "type": "reply", "label": "답장", "capability": "school_life.task.reply", "arguments": {"task_id": "42"}}
  ]
}

지원 type:

• show_notification: 즉시 표시
• schedule_notification: at_millis에 예약
• cancel_notification: 같은 id와 key 취소

공통 한도는 id 0~2,147,483,647, key 최대 240자, title 160자, body 500자, big_text 2,000자입니다. category는 general, reminder, progress, status, visibility는 private, public, secret입니다. 예약은 현재부터 최대 366일 안입니다.

알림당 action은 최대 4개이며 check, capability, snooze, open_plugin, reply를 지원합니다. check/custom/reply는 현재 Instance에 선언된 Tool·Skill capability만 실행하고, 클릭 순간 enabled, generation, permission, Connection을 다시 검사합니다. reply text는 Host가 제한된 argument로만 넣습니다. event token과 action ID로 중복 클릭을 제거하고 성공한 event만 ACK합니다. capability가 Storage를 변경하면 같은 storage revision 신호로 열린 UI를 갱신합니다.

progress:

{
  "current": 3,
  "max": 10,
  "indeterminate": false
}

max는 11,000,000이고 current는 0max입니다. 진행 알림은 실제 작업 상태와 일치해야 하며 완료된 뒤 ongoing 상태로 남기지 않습니다.

Durable delivery

Host는 pending action을 lease한 뒤 플랫폼 gateway에 전달하고 결과를 ACK합니다. 앱이 중단되어도 lease가 만료되면 재전달할 수 있으므로 key를 안정적인 중복 제거 키로 만듭니다. 권한 철회, Instance disable/delete, package generation 변경은 해당 owner의 pending action을 폐기합니다.

현재 알림 gateway 실사용 검증은 Android 기준입니다. iOS/Desktop은 같은 Host action 계약 위에 플랫폼 adapter를 구현해야 합니다. 지원되지 않는 플랫폼에서 알림 실패를 원본 데이터 저장 성공으로 위장하지 않되, 알림 하나 때문에 읽기 화면 전체를 깨뜨리지 않습니다.

Background

Background capability는 background 권한과 15~10,080분의 interval_minutes가 필요합니다. Host는 enabled, granted permission, generation, 연결 상태를 확인한 뒤 실행합니다. 앱이 꺼져 있을 때 정확한 시각 실행을 보장하는 cron으로 설명하지 않습니다. 사용자에게 주기, 마지막 실행, 오류, 끄기 동작을 settings에서 제공합니다.