Casos

Las consultas de detalle y acceso aceptan UUID o código inmutable como PANDA-317. Las demás operaciones usan el UUID. Case get incluye los últimos diez Registros. Continúe con records_next_cursor y records_scope (self) en CLI, o recordsNextCursor y recordsScope en API/MCP.

Los Casos públicos muestran el título, entrada, Tareas, Registros y traspasos legibles actuales, incluidas las incorporaciones posteriores. Conservan referencias públicas de autores y responsables, pero omiten permisos privados, fuentes vinculadas, informes y resúmenes de Review y configuración privada. La publicación permite solo leer. Los lectores explícitos también pueden leer Casos privados y sus fuentes; escribir requiere edición.

Las lecturas públicas de casos cuestan 0 créditos sin iniciar sesión en Web, CLI, API y MCP. Las lecturas de trabajo en API / CLI / MCP agrupan las lecturas auxiliares en un solo case get de 1 crédito; las lecturas normales de Web siguen gratis.

Utilice epismo_case_start cuando deba compartirse o reanudarse un resultado. Comience desde una versión de playbook o cree un caso ad hoc con un título.

• Mantener el trabajo intermedio local en el tiempo de ejecución del agente.
• Adjunte resultados, decisiones, evaluaciones (kind=note), compromisos compartidos (kind=agreement) y resúmenes de transferencias con epismo_case_record_append.
• Edite o redacte un registro que creó con epismo_case_record_update o epismo_case_record_delete.
• Crear tareas con epismo_case_task_create solo para responsabilidad explícita o aprobación.
• Los editores del caso pueden encolar una evaluación asíncrona de AI review sobre las evidencias y registros del caso con epismo_report_case_generate. La llamada devuelve de inmediato los metadatos del trabajo. Review utiliza instrucciones de evaluación integradas; no admite instrucciones personalizadas de la cuenta propietaria ni prompts por solicitud. Inspeccione la evaluación y propuestas resultantes con epismo_report_case_get. Confirme o descarte propuestas (como crear tareas de seguimiento) con epismo_report_case_act. Revise todo el contenido de la propuesta guardada y envíe reportId, proposalId y action (create o dismiss), con feedback opcional al descartar. La creación utiliza el contenido guardado sin cambios para crear una tarea, un caso con un enlace de traspaso dirigido, una sugerencia o un playbook con su primera versión. No envíe title, content, cambios de definición ni idempotencyKey; los reintentos utilizan la identidad de la propuesta. Las decisiones se conservan por propuesta: repetir una ya atendida devuelve el informe guardado actual sin crear más trabajo.

Los nuevos casos y playbooks utilizan la cuenta de facturación activa de quien confirma, con acceso restringido al creador; no se copian los permisos ni las fuentes externas del caso original. Crear un caso añade un enlace de traspaso dirigido desde el caso evaluado sin cerrarlo. La creación de playbooks se propone con moderación, cuando hay evidencia de un patrón recurrente y un uso futuro probable; las recomendaciones de creación ya atendidas no se vuelven a proponer para ese caso. Un informe desactualizado muestra un aviso orientativo de reevaluación y no bloquea las acciones; siguen aplicándose los permisos actuales y la validación de cada operación.

• Conecte flujos de trabajo relacionados mediante epismo_case_handoff_create e inspeccione el grafo DAG con epismo_case_handoff_graph_get.
• Consulte casos candidatos válidos con epismo_case_handoff_candidates_list (direction=outgoing o direction=incoming) para evitar bucles y enlaces duplicados.
• Generar una nueva clave de idempotencia para cada nueva mutación.
• Lea la última versión de bloqueo antes de cambiar un caso o tarea.

Después de un conflicto, vuelva a leer el objeto y decida si la intención sigue siendo válida. Nunca reproduzca una solicitud obsoleta cambiando solo su versión de bloqueo.

No invente un agente cesionario. Cuando sea necesaria una asignación de usuario, seleccione una ID del recurso de usuarios y asegúrese de que el usuario ya esté en la ACL del caso.

Utilice epismo_case_record_list con el ID del caso para reanudar desde su línea de tiempo. Pase scope (self, ancestors, descendants, neighbors, connected) para incluir registros de transferencias conectadas respetando las ACL individuales de cada caso. Los filtros de tarea, autor, tipo y origen solo limitan esa línea de tiempo; nunca conceden acceso.

La configuración explícita de creación y los cambios de acceso usan access: { visibility, grants }: visibilidad restricted/public y claves UUID de usuarios o equipos, o correos de usuarios registrados, con valores viewer/editor. Los correos se resuelven a UUID antes de guardar; las respuestas usan UUID. Un correo no registrado o roles en conflicto para el mismo usuario resuelto rechazan toda la operación. Cada cambio reemplaza el objeto completo; conserve los permisos ajenos al cambio e incluya el suyo si desea mantenerlo. Los propietarios conservan la gestión independientemente de los permisos. Los responsables y mantenedores no reciben acceso implícito. Los editores pueden consultar y reemplazar permisos, conservar al menos un editor explícito al cambiar permisos, archivar y restaurar. El JSON normal omite mapas privados; los editores pueden obtenerlos con access-get. Consulte Acceso e identidad.

Entrada y selección de playbook

Utilice epismo_case_update con caseId, el último expectedLockVersion e idempotencyKey para actualizar un caso abierto (open). Use versionId para adjuntar o sustituir una versión legible y no archivada de un playbook, null para quitarlo u omita el campo para conservar la selección actual. Se requiere edición del caso.

Cada actualización de título, entrada o playbook valida la entrada resultante contra el esquema de la versión seleccionada, si hay un playbook. Enviar input sustituye el objeto completo; omitirlo reutiliza la entrada actual. La selección del playbook y la sustitución opcional de entrada se guardan juntas; si falla la validación, no se guarda ninguna. Quitar el playbook conserva la entrada sin aplicar el esquema anterior.

{
	"caseId": "<case-uuid>",
	"versionId": "<version-uuid>",
	"input": { "customer": "Acme" },
	"expectedLockVersion": 1,
	"idempotencyKey": "<new-uuid>"
}

Para quitar el playbook, envíe "versionId": null con la última versión de bloqueo y una nueva clave de idempotencia.

Adjuntar, sustituir o quitar un playbook crea una actividad del sistema con las versiones anterior y seleccionada, según corresponda. Se conservan las tareas, los registros y los informes existentes; las tareas mantienen sus referencias originales a pasos.

Propiedad, responsabilidad y ciclo de vida

Playbooks y Casos tienen una cuenta propietaria de Usuario o Espacio de trabajo (ownerId), que también paga su uso. El propietario personal tiene todos los derechos; los Owners y Admins actuales ejercen esos derechos para un Espacio de trabajo. Los demás miembros necesitan permisos explícitos de usuario o Equipo, o visibilidad pública para leer contenido publicado. La membresía por sí sola no concede acceso. Al eliminar un miembro, se revocan sus permisos directos sobre los recursos propiedad de ese Espacio, incluidos los completados y archivados. Si la eliminación dejara algún recurso sin editor explícito, añada primero otro usuario o equipo editor, incluidos los recursos completados o archivados. Se conservan los permisos sobre recursos personales y de otros Espacios. Los permisos de Equipo y administración dependen de la membresía actual. El SSO obligatorio se aplica a los miembros; los usuarios externos con permisos directos usan la autenticación normal de Epismo. El acceso de Equipo entre espacios verifica el SSO del espacio de participación. Los listados usan permisos explícitos y la visibilidad pública admitida; la propiedad por sí sola no incluye un recurso.

Las mutaciones de Casos y Tareas requieren el último expectedLockVersion (la lectura devuelve lockVersion). Ante un conflicto, lea el estado actual y reconsidere el cambio. Los editores pueden asignar, cambiar títulos, cerrar, reabrir, reemplazar todos los permisos, archivar y restaurar. La asignación no concede acceso: el destinatario debe tener edición. Eliminar permisos no cambia al responsable. Los iniciadores, autores y aprobaciones completadas permanecen como historial.

Omita ownerId al crear o copiar para usar el Espacio de trabajo activo, o su cuenta personal si no hay uno seleccionado. La selección explícita también requiere autorización. Cuando hay un Espacio seleccionado, incluido el predeterminado de la conexión, la creación requiere exactamente una opción: private: true, teamIds no vacío o access. En el espacio personal puede omitirse la configuración. El permiso de edición del Equipo cubre al creador sin añadir un permiso directo redundante; se conserva un permiso directo solicitado explícitamente. Mantener o tener asignado un recurso no sustituye los permisos.

Archivar es distinto de cerrar. Los editores y propietarios pueden archivar desde Web, CLI, API o MCP. Los Casos archivados salen de vistas activas, recuentos y grafos y no pueden abrirse, pero conservan su trabajo. Liste con archived=true (case list --archived) para obtener el UUID y la última versión de bloqueo; restaurar conserva estado, responsables y permisos. Solo un propietario puede eliminar definitivamente un Caso archivado, con el último expectedLockVersion. Se eliminan sus Tareas, Registros, Fuentes y enlaces; otros Casos y el contenido original del proveedor permanecen.

epismo_case_archive / epismo_case_restore / epismo_case_delete

Transfiera la propiedad de un Caso con epismo_case_owner_transfer, case owner transfer <case-id> --owner-id <account-id> --lock-version <n> o PATCH /v1/cases/{caseId}/owner (ownerId, expectedLockVersion, idempotencyKey). Requiere propiedad actual. Un Caso personal puede pasar al Espacio conectado; si es público, también exige gestión del Espacio de destino. Un Caso del Espacio puede pasar a su creador o a un Owner de ese Espacio. Se rechazan transferencias entre usuarios o entre Espacios. Se conservan asignación y permisos, cambia la cuenta de facturación y se borran los informes de Review derivados. Reasignar por sí solo no realiza estos cambios de propiedad.

Descubra Casos públicos con epismo_case_list, sin necesidad de iniciar sesión. Los resultados se ordenan por actualización e incluyen Casos sin Registros. Filtre el Playbook de origen con playbookId. Con sesión iniciada, omita sharingScope para incluir todas las clasificaciones legibles o elija only_me, shared o anyone. Los filtros no conceden acceso; consulte Acceso e identidad.

Consultar evaluaciones guardadas

El detalle del caso incluye el último informe accesible y el trabajo de generación sin cargar el historial ni ejecutar IA. Usa epismo_report_case_list con caseId y los campos opcionales pageSize y cursor para consultar fechas, diagnósticos de salud y resúmenes del más reciente al más antiguo. Pasa un reportId guardado a epismo_report_case_get para leer el informe completo.

El historial exige acceso de trabajo actual al caso y devuelve solo evaluaciones que coinciden con la audiencia compartida actual. Los lectores públicos no reciben informes ni resúmenes. Los informes reemplazados tienen historical: true y son de solo lectura: crear o descartar una propuesta pendiente de uno devuelve HTTP 409. Lee el informe más reciente y reconsidera la propuesta antes de actuar. Los cambios de evidencia por sí solos siguen mostrando un aviso orientativo de reevaluación.

Los registros usan note, output, activity, agreement (reservado al sistema) o agreement. Los nuevos registros y los cambios de tipo aceptan note, output o agreement. Las evaluaciones humanas y de agentes pueden guardarse como notas; AI Review guarda informes separados.

Informes personales y de equipo

Los informes personales son privados para quien los generó en la cuenta de facturación activa. Los informes de equipo y las decisiones sobre propuestas se comparten con los miembros actuales desde el espacio activo. Consulta AI review para los criterios de selección, salud, historial y permisos de los informes.

Generar, leer y listar informes de equipo requiere teamId; actuar obtiene el alcance del reportId guardado. La generación recibe un UUID idempotencyKey y devuelve un trabajo. Lee con jobId o reportId, nunca ambos; pagina las listas con pageSize y cursor. Antes de actuar, lee toda la propuesta y envía reportId, proposalId, action (create o dismiss) y feedback opcional al descartar. Las acciones usan el contenido guardado sin cambios y no reciben clave de idempotencia.