Safe Storage Names

Caller-supplied names stay inside the storage directory, with legacy filenames preserved

Any plan, todo list, or PRP name you pass in — even one an LLM made up — is written inside its storage directory. ../../x can never escape, and ordinary names keep the exact filename they always had.

Quick Start

1. Let an agent name what it saves

   from praisonaiagents import Agent
   from praisonaiagents.planning.storage import PlanStorage
   from praisonaiagents.planning.todo import TodoList
   
   store = PlanStorage(base_path="./my_store")
   
   def save_todo_list(name: str, tasks: list[str]) -> str:
       """Save a todo list under the given name."""
       todo = TodoList()
       for task in tasks:
           todo.add(task)
       return store.save_todo(todo, name=name)  # always inside ./my_store/todos/
   
   agent = Agent(
       name="Planner",
       instructions="Plan tasks and save them with save_todo_list.",
       tools=[save_todo_list],
   )
   agent.start("Plan an auth migration and save it as 'auth/login migration'.")

2. Any name is confined

   from praisonaiagents.planning.storage import PlanStorage
   from praisonaiagents.planning.todo import TodoList
   
   store = PlanStorage(base_path="./my_store")
   
   store.save_todo(TodoList(), name="current")        # ./my_store/todos/current.json
   store.save_todo(TodoList(), name="../../escaped")  # ./my_store/todos/%2E.%2F..%2Fescaped.json
   store.save_todo(TodoList(), name="我的任务")       # ./my_store/todos/我的任务.json
   
   # Listed names round-trip through load/delete.
   for name in store.list_todos():
       assert store.load_todo(name) is not None

How It Works

Only characters that could change the path are percent-encoded: %, /, \, :, *, ?, ", <, >, |, control characters, and a leading .. Everything else — including spaces and non-ASCII — is kept as-is.

list_todos() decodes filenames back to the original names, so whatever it returns works with load_todo() and delete_todo().

Which APIs use it

You can use the same helper for your own storage:

from praisonaiagents.utils.atomic_io import safe_join

path = safe_join("./reports", "Q3/summary", ".md")  # ./reports/Q3%2Fsummary.md

Common Patterns

from praisonaiagents.planning.plan import Plan
from praisonaiagents.planning.storage import PlanStorage

store = PlanStorage()
llm_suggested_name = "../release/plan v2.md"
path = store.save_plan(Plan(name="Release"), filename=llm_suggested_name)
# -> <plans_dir>/%2E.%2Frelease%2Fplan v2.md — always under store.plans_dir

from praisonaiagents.planning.storage import PlanStorage
from praisonaiagents.planning.todo import TodoList

store = PlanStorage()
store.save_todo(TodoList(), name="我的任务")
print(store.list_todos())   # [..., '我的任务']
store.delete_todo("我的任务")

Best Practices

Related